1 /* Name:
   2       stcschan-demo4.c
   3 
   4    Purpose:
   5       A demonstration of the facilities provided by the AST library 
   6       for reading STC metadata encoded using the STC-S linear string 
   7       format.
   8 
   9    Description:
  10       This program reads two STC-S descriptions from two disk files, 
  11       and tests them for overlap. The two descriptions need not refer 
  12       to the same coordinate system. Built-in conversions within AST
  13       will be used to align them if the coordinate systems differ.
  14 
  15    Usage:
  16       % stcschan-demo4 <stcs-file1> <stcs-file2> 
  17 
  18       <stcs-file1>: The path to the disk file containing the first STC-S
  19       description.
  20 
  21       <stcs-file2>: The path to the disk file containing the second STC-S
  22       description.
  23 
  24    Example:
  25       % stcschan-demo4 stcs-ex1.txt stcs-ex2.txt
  26 
  27    To compile and link:
  28       Assuming your starlink distribution is in "/star":
  29 
  30       % gcc -o stcschan-demo4 stcschan-demo4.c -L/star/lib \
  31             -I/star/include `ast_link`
  32 */
  33 
  34 /* Include system headers. */
  35 #include <stdio.h>
  36 #include <string.h>
  37 
  38 /* Include the AST library header. */
  39 #include "ast.h"
  40 
  41 /* Maximum number of axes in an STC-S AstroCoordSystem. */
  42 #define MAX_AXES 5
  43 
  44 /* Maximum allowed length for a single line of text form the disk file. */
  45 #define MAX_LINE_LEN 500
  46 
  47 /* Prototypes: */
  48 const char *source( void );
  49 AstRegion *ReadStcs( AstStcsChan *chan, const char *file, int *status );
  50 
  51 int main( int argc, char **argv ){
  52 
  53 /* Local variables: */
  54    AstRegion *region1;
  55    AstRegion *region2;
  56    AstStcsChan *channel;
  57    int status;
  58 
  59 /* Initialised the returned system status to indicate success. */
  60    status = 0;
  61 
  62 /* Check two files were specified on the command line. */
  63    if( argc < 3 ) {
  64       printf( "Usage: stcschan-demo4 <stcs-file1> <stcs-file2> \n" );
  65       status = 1;
  66    } 
  67 
  68 /* Start an AST object context. This means we do not need to annull 
  69    each AST Object individually. Instead, all Objects created within 
  70    this context will be annulled automatically by the corresponding
  71    invocation of astEnd. */
  72    astBegin;
  73 
  74 /* Create an StcsChan. This is the object that converts between external 
  75    STC-S descriptions and the corresponding AST Objects. Tell it to use the
  76    "source" function for obtaining lines of text from the disk file. Also
  77    tell it to store all warnings generated by the conversion for later
  78    use. Other attributes of the StcsChan class retain their default
  79    values. */
  80    channel = astStcsChan( source, NULL, "ReportLevel=3" );
  81   
  82 /* Attempt to read the STC-S description from the first file, and produce
  83    a corresponding AST Region object. The conversion is performed by the
  84    StcsChan created above. */
  85    region1 = ReadStcs( channel, argv[ 1 ], &status );
  86 
  87 /* Now attempt to read the STC-S description from the second file,
  88    producing a corresponding AST Region object. We re-use the StcsChan 
  89    created above. */
  90    region2 = ReadStcs( channel, argv[ 2 ], &status );
  91 
  92 /* If we have two Regions, test them for overlap and tell the user the 
  93    result of the test. */
  94    if( region1 && region2 ) {
  95       switch( astOverlap( region1, region2 ) ) {
  96 
  97          case 1:
  98             printf( "\n   There is no overlap between the two Regions.\n\n");
  99             break;
 100    
 101          case 2:
 102             printf( "\n   The first Region is completely inside the second Region.\n\n");
 103             break;
 104    
 105          case 3:
 106             printf( "\n   The second Region is completely inside the first Region.\n\n");
 107             break;
 108    
 109          case 4:
 110             printf( "\n   There is partial overlap between the two Regions.\n\n");
 111             break;
 112    
 113          case 5:
 114             printf( "\n   The Regions are identical to within their uncertainties.\n\n");
 115             break;
 116    
 117          case 6:
 118             printf( "\n   The second Region is the exact negation of the first "
 119                     "Region to within their uncertainties. \n\n");
 120             break;
 121 
 122          default:
 123             if( astOK ) printf( "\n   Unexpected value returned by astOverlap\n\n" );
 124       }
 125    }
 126 
 127 /* End the AST Object context. All Objects created since the
 128    corresponding invocation of astbegin will be annulled automatically. */
 129    astEnd;
 130 
 131 /* If an error occurred in the AST library, set the retiurns system
 132    status non-zero. */
 133    if( !astOK ) status = 1;
 134    return status;
 135 }
 136 
 137 
 138 
 139 
 140 
 141 
 142 
 143 /* This is a function that reads a line of text from the disk file and
 144    returns it to the AST library. It is called from within the astRead
 145    function. */
 146 const char *source( void ){
 147    static char buffer[ MAX_LINE_LEN + 2 ];
 148    FILE *fd = astChannelData;
 149    return fgets( buffer, MAX_LINE_LEN + 2, fd );
 150 }
 151 
 152 
 153 
 154 
 155 
 156 /* -------------------------------------------------------------------
 157  * This function reads an STC-S description from a given text file,
 158  * and attempts to convert them into an AST Region. If successful, a
 159  * pointer to the Region is returned. A NULL pointer is returned if
 160  * anything goes wrong. 
 161 */
 162 
 163 AstRegion *ReadStcs( AstStcsChan *chan, const char *file, int *status ){
 164    AstKeyMap *warnings;
 165    AstObject *object;
 166    AstRegion *result;
 167    FILE *fd;
 168    char key[ 15 ];
 169    const char *message;
 170    int iwarn;
 171 
 172 /* Initialise the returned pointer to indicate that no Region has yet
 173    been read. */
 174    result = NULL;
 175 
 176 /* If an error has already occurred, return without action. */
 177    if( *status != 0 ) return result;
 178 
 179 /* Attempt to open the STC-S file */
 180    fd = fopen( file, "r" );
 181    if( !fd ) {
 182       printf("Failed to open STC-S descrption file '%s'.\n", file );
 183 
 184 /* If successful... */
 185    } else {
 186 
 187 /* Associate the descriptor for the input disk file with the StcsChan.
 188    This makes it available to the "source" function. Since this
 189    application is single threaded, we could instead have made "fd" a 
 190    global variable, but the ChannelData facility is used here to illustrate 
 191    how to pass data to a source or sink function safely in a multi-threaded 
 192    application. */
 193       astPutChannelData( chan, fd );
 194 
 195 /* The default behaviour of the astRead function when used on an StcsChan is 
 196    to read and return the AstroCoordArea as an AST Region. This behaviour
 197    can be changed by assigning appropriate values to the StcsChan attributes
 198    "StcsArea", "StcsCoords" and "StcsProps". Options exist to return the 
 199    AstroCoords as an AST PointList, and/or to return the individual
 200    property values read from the STC-S text in the form of an AST KeyMap
 201    (a sort of hashmap). For now, just take the default action of reading the 
 202    AstroCoordsArea. */
 203       object = astRead( chan );
 204       
 205 /* The astRead function is a generic function and so returns a generic
 206    AstObject pointer. Check an Object was created successfully. */
 207       if( !object ) {
 208          printf( "Failed to read an AST Object from STC-S description "
 209                  "file '%s'.\n", file );
 210 
 211 /* Now check that the object read is actually an AST Region, rather than
 212    some other class of AST Object. */
 213       } else if( !astIsARegion( object ) ) {      
 214          printf( "Expected a Region but read a %s from STC-S description "
 215                  "file '%s'.\n", astGetC( object, "Class" ), file );
 216 
 217 /* If the Object is a Region, return the Region pointer. */
 218       } else {
 219          result = (AstRegion *) object;
 220       }
 221 
 222 /* Close the file. */
 223       fclose( fd );
 224 
 225 /* If the StcsChan recorded any warnings that were generated whilst 
 226    converting the STC-S description into a corresponding AST Object,
 227    we now display them. First test the ReportLevel attribute value to see
 228    if warnings were recored. */
 229       if( astGetI( chan, "ReportLevel" ) > 0 ) {
 230 
 231 /* Any warnings recorded during the conversion performed by astRead above 
 232    are returned by the astWarnings method, in the form of an AST "KeyMap" 
 233    (a type of hash map ). */
 234          warnings = astWarnings( chan );
 235 
 236 /* If any warnings were generated, and if no other error has occurred so
 237    far, display the warnings. */
 238          if( warnings && !status && astOK ) {
 239             printf( "\nThe following warnings were issued reading file "
 240                     "'%s':\n", file );
 241 
 242 /* The warnings are stored in an AST KeyMap (a sort of hashmap). Each
 243    warning message is associated with a key of the form "Warning_1",
 244    "Warning_2", etc. Loop round successive keys, obtaining a value for
 245    each key from the warnings KeyMap, and displaying it. */
 246             iwarn = 1;
 247             while( astOK ) {
 248                sprintf( key, "Warning_%d", iwarn++ );
 249                if( astMapGet0C( warnings, key, &message ) ) {
 250                   printf( "\n- %s\n", message );
 251                } else {
 252                   break;
 253                }
 254             }             
 255          }
 256       }
 257    }
 258 
 259    return result;
 260 }
 261 
 262 
 263