1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5758 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 5897 5898 5899 5900 5901 5902 5903 5904 5905 5906 5907 5908 5909 5910 5911 5912 5913 5914 5915 5916 5917 5918 5919 5920 5921 5922 5923 5924 5925 5926 5927 5928 5929 5930 5931 5932 5933 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 5949 5950 5951 5952 5953 5954 5955 5956 5957 5958 5959 5960 5961 5962 5963 5964 5965 5966 5967 5968 5969 5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 6002 6003 6004 6005 6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 6046 6047 6048 6049 6050 6051 6052 6053 6054 6055 6056 6057 6058 6059 6060 6061 6062 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110 6111 6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 6140 6141 6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 6207 6208 6209 6210 6211 6212 6213 6214 6215 6216 6217 6218 6219 6220 6221 6222 6223 6224 6225 6226 6227 6228 6229 6230 6231 6232 6233 6234 6235 6236 6237 6238 6239 6240 6241 6242 6243 6244 6245 6246 6247 6248 6249 6250 6251 6252 6253 6254 6255 6256 6257 6258 6259 6260 6261 6262 6263 6264 6265 6266 6267 6268 6269 6270 6271 6272 6273 6274 6275 6276 6277 6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 6291 6292 6293 6294 6295 6296 6297 6298 6299 6300 6301 6302 6303 6304 6305 6306 6307 6308 6309 6310 6311 6312 6313 6314 6315 6316 6317 6318 6319 6320 6321 6322 6323 6324 6325 6326 6327 6328 6329 6330 6331 6332 6333 6334 6335 6336 6337 6338 6339 6340 6341 6342 6343 6344 6345 6346 6347 6348 6349 6350 6351 6352 6353 6354 6355 6356 6357 6358 6359 6360 6361 6362 6363 6364 6365 6366 6367 6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 6393 6394 6395 6396 6397 6398 6399 6400 6401 6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432 6433 6434 6435 6436 6437 6438 6439 6440 6441 6442 6443 6444 6445 6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457 6458 6459 6460 6461 6462 6463 6464 6465 6466 6467 6468 6469 6470 6471 6472 6473 6474 6475 6476 6477 6478 6479 6480 6481 6482 6483 6484 6485 6486 6487 6488 6489 6490 6491 6492 6493 6494 6495 6496 6497 6498 6499 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510 6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526 6527 6528 6529 6530 6531 6532 6533 6534 6535 6536 6537 6538 6539 6540 6541 6542 6543 6544 6545 6546 6547 6548 6549 6550 6551 6552 6553 6554 6555 6556 6557 6558 6559 6560 6561 6562 6563 6564 6565 6566 6567 6568 6569 6570 6571 6572 6573 6574 6575 6576 6577 6578 6579 6580 6581 6582 6583 6584 6585 6586 6587 6588 6589 6590 6591 6592 6593 6594 6595 6596 6597 6598 6599 6600 6601 6602 6603 6604 6605 6606 6607 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6619 6620 6621 6622 6623 6624 6625 6626 6627 6628 6629 6630 6631 6632 6633 6634 6635 6636 6637 6638 6639 6640 6641 6642 6643 6644 6645 6646 6647 6648 6649 6650 6651 6652 6653 6654 6655 6656 6657 6658 6659 6660 6661 6662 6663 6664 6665 6666 6667 6668 6669 6670 6671 6672 6673 6674 6675 6676 6677 6678 6679 6680 6681 6682 6683 6684 6685 6686 6687 6688 6689 6690 6691 6692 6693 6694 6695 6696 6697 6698 6699 6700 6701 6702 6703 6704 6705 6706 6707 6708 6709 6710 6711 6712 6713 6714 6715 6716 6717 6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 6732 6733 6734 6735 6736 6737 6738 6739 6740 6741 6742 6743 6744 6745 6746 6747 6748 6749 6750 6751 6752 6753 6754 6755 6756 6757 6758 6759 6760 6761 6762 6763 6764 6765 6766 6767 6768 6769 6770 6771 6772 6773 6774 6775 6776 6777 6778 6779 6780 6781 6782 6783 6784 6785 6786 6787 6788 6789 6790 6791 6792 6793 6794 6795 6796 6797 6798 6799 6800 6801 6802 6803 6804 6805 6806 6807 6808 6809 6810 6811 6812 6813 6814 6815 6816 6817 6818 6819 6820 6821 6822 6823 6824 6825 6826 6827 6828 6829 6830 6831 6832 6833 6834 6835 6836 6837 6838 6839 6840 6841 6842 6843 6844 6845 6846 6847 6848 6849 6850 6851 6852 6853 6854 6855 6856 6857 6858 6859 6860 6861 6862 6863 6864 6865 6866 6867 6868 6869 6870 6871 6872 6873 6874 6875 6876 6877 6878 6879 6880 6881 6882 6883 6884 6885 6886 6887 6888 6889 6890 6891 6892 6893 6894 6895 6896 6897 6898 6899 6900 6901 6902 6903 6904 6905 6906 6907 6908 6909 6910 6911 6912 6913 6914 6915 6916 6917 6918 6919 6920 6921 6922 6923 6924 6925 6926 6927 6928 6929 6930 6931 6932 6933 6934 6935 6936 6937 6938 6939 6940 6941 6942 6943 6944 6945 6946 6947 6948 6949 6950 6951 6952 6953 6954 6955 6956 6957 6958 6959 6960 6961 6962 6963 6964 6965 6966 6967 6968 6969 6970 6971 6972 6973 6974 6975 6976 6977 6978 6979 6980 6981 6982 6983 6984 6985 6986 6987 6988 6989 6990 6991 6992 6993 6994 6995 6996 6997 6998 6999 7000 7001 7002 7003 7004 7005 7006 7007 7008 7009 7010 7011 7012 7013 7014 7015 7016 7017 7018 7019 7020 7021 7022 7023 7024 7025 7026 7027 7028 7029 7030 7031 7032 7033 7034 7035 7036 7037 7038 7039 7040 7041 7042 7043 7044 7045 7046 7047 7048 7049 7050 7051 7052 7053 7054 7055 7056 7057 7058 7059 7060 7061 7062 7063 7064 7065 7066 7067 7068 7069 7070 7071 7072 7073 7074 7075 7076 7077 7078 7079 7080 7081 7082 7083 7084 7085 7086 7087 7088 7089 7090 7091 7092 7093 7094 7095 7096 7097 7098 7099 7100 7101 7102 7103 7104 7105 7106 7107 7108 7109 7110 7111 7112 7113 7114 7115 7116 7117 7118 7119 7120 7121 7122 7123 7124 7125 7126 7127 7128 7129 7130 7131 7132 7133 7134 7135 7136 7137 7138 7139 7140 7141 7142 7143 7144 7145 7146 7147 7148 7149 7150 7151 7152 7153 7154 7155 7156 7157 7158 7159 7160 7161 7162 7163 7164 7165 7166 7167 7168 7169 7170 7171 7172 7173 7174 7175 7176 7177 7178 7179 7180 7181 7182 7183 7184 7185 7186 7187 7188 7189 7190 7191 7192 7193 7194 7195 7196 7197 7198 7199 7200 7201 7202 7203 7204 7205 7206 7207 7208 7209 7210 7211 7212 7213 7214 7215 7216 7217 7218 7219 7220 7221 7222 7223 7224 7225 7226 7227 7228 7229 7230 7231 7232 7233 7234 7235 7236 7237 7238 7239 7240 7241 7242 7243 7244 7245 7246 7247 7248 7249 7250 7251 7252 7253 7254 7255 7256 7257 7258 7259 7260 7261 7262 7263 7264 7265 7266 7267 7268 7269 7270 7271 7272 7273 7274 7275 7276 7277 7278 7279 7280 7281 7282 7283 7284 7285 7286 7287 7288 7289 7290 7291 7292 7293 7294 7295 7296 7297 7298 7299 7300 7301 7302 7303 7304 7305 7306 7307 7308 7309 7310 7311 7312 7313 7314 7315 7316 7317 7318 7319 7320 7321 7322 7323 7324 7325 7326 7327 7328 7329 7330 7331 7332 7333 7334 7335 7336 7337 7338 7339 7340 7341 7342 7343 7344 7345 7346 7347 7348 7349 7350 7351 7352 7353 7354 7355 7356 7357 7358 7359 7360 7361 7362 7363 7364 7365 7366 7367 7368 7369 7370 7371 7372 7373 7374 7375 7376 7377 7378 7379 7380 7381 7382 7383 7384 7385 7386 7387 7388 7389 7390 7391 7392 7393 7394 7395 7396 7397 7398 7399 7400 7401 7402 7403 7404 7405 7406 7407 7408 7409 7410 7411 7412 7413 7414 7415 7416 7417 7418 7419 7420 7421 7422 7423 7424 7425 7426 7427 7428 7429 7430 7431 7432 7433 7434 7435 7436 7437 7438 7439 7440 7441 7442 7443 7444 7445 7446 7447 7448 7449 7450 7451 7452 7453 7454 7455 7456 7457 7458 7459 7460 7461 7462 7463 7464 7465 7466 7467 7468 7469 7470 7471 7472 7473 7474 7475 7476 7477 7478 7479 7480 7481 7482 7483 7484 7485 7486 7487 7488 7489 7490 7491 7492 7493 7494 7495 7496 7497 7498 7499 7500 7501 7502 7503 7504 7505 7506 7507 7508 7509 7510 7511 7512 7513 7514 7515 7516 7517 7518 7519 7520 7521 7522 7523 7524 7525 7526 7527 7528 7529 7530 7531 7532 7533 7534 7535 7536 7537 7538 7539 7540 7541 7542 7543 7544 7545 7546 7547 7548 7549 7550 7551 7552 7553 7554 7555 7556 7557 7558 7559 7560 7561 7562 7563 7564 7565 7566 7567 7568 7569 7570 7571 7572 7573 7574 7575 7576 7577 7578 7579 7580 7581 7582 7583 7584 7585 7586 7587 7588 7589 7590 7591 7592 7593 7594 7595 7596 7597 7598 7599 7600 7601 7602 7603 7604 7605 7606 7607 7608 7609 7610 7611 7612 7613 7614 7615 7616 7617 7618 7619 7620 7621 7622 7623 7624 7625 7626 7627 7628 7629 7630 7631 7632 7633 7634 7635 7636 7637 7638 7639 7640 7641 7642 7643 7644 7645 7646 7647 7648 7649 7650 7651 7652 7653 7654 7655 7656 7657 7658 7659 7660 7661 7662 7663 7664 7665 7666 7667 7668 7669 7670 7671 7672 7673 7674 7675 7676 7677 7678 7679 7680 7681 7682 7683 7684 7685 7686 7687 7688 7689 7690 7691 7692 7693 7694 7695 7696 7697 7698 7699 7700 7701 7702 7703 7704 7705 7706 7707 7708 7709 7710 7711 7712 7713 7714 7715 7716 7717 7718 7719 7720 7721 7722 7723 7724 7725 7726 7727 7728 7729 7730 7731 7732 7733 7734 7735 7736 7737 7738 7739 7740 7741 7742 7743 7744 7745 7746 7747 7748 7749 7750 7751 7752 7753 7754 7755 7756 7757 7758 7759 7760 7761 7762 7763 7764 7765 7766 7767 7768 7769 7770 7771 7772 7773 7774 7775 7776 7777 7778 7779 7780 7781 7782 7783 7784 7785 7786 7787 7788 7789 7790 7791 7792 7793 7794 7795 7796 7797 7798 7799 7800 7801 7802 7803 7804 7805 7806 7807 7808 7809 7810 7811 7812 7813 7814 7815 7816 7817 7818 7819 7820 7821 7822 7823 7824 7825 7826 7827 7828 7829 7830 7831 7832 7833 7834 7835 7836 7837 7838 7839 7840 7841 7842 7843 7844 7845 7846 7847 7848 7849 7850 7851 7852 7853 7854 7855 7856 7857 7858 7859 7860 7861 7862 7863 7864 7865 7866 7867 7868 7869 7870 7871 7872 7873 7874 7875 7876 7877 7878 7879 7880 7881 7882 7883 7884 7885 7886 7887 7888 7889 7890 7891 7892 7893 7894 7895 7896 7897 7898 7899 7900 7901 7902 7903 7904 7905 7906 7907 7908 7909 7910 7911 7912 7913 7914 7915 7916 7917 7918 7919 7920 7921 7922 7923 7924 7925 7926 7927 7928 7929 7930 7931 7932 7933 7934 7935 7936 7937 7938 7939 7940 7941 7942 7943 7944 7945 7946 7947 7948 7949 7950 7951 7952 7953 7954 7955 7956 7957 7958 7959 7960 7961 7962 7963 7964 7965 7966 7967 7968 7969 7970 7971 7972 7973 7974 7975 7976 7977 7978 7979 7980 7981 7982 7983 7984 7985 7986 7987 7988 7989 7990 7991 7992 7993 7994 7995 7996 7997 7998 7999 8000 8001 8002 8003 8004 8005 8006 8007 8008 8009 8010 8011 8012 8013 8014 8015 8016 8017 8018 8019 8020 8021 8022 8023 8024 8025 8026 8027 8028 8029 8030 8031 8032 8033 8034 8035 8036 8037 8038 8039 8040 8041 8042 8043 8044 8045 8046 8047 8048 8049 8050 8051 8052 8053 8054 8055 8056 8057 8058 8059 8060 8061 8062 8063 8064 8065 8066 8067 8068 8069 8070 8071 8072 8073 8074 8075 8076 8077 8078 8079 8080 8081 8082 8083 8084 8085 8086 8087 8088 8089 8090 8091 8092 8093 8094 8095 8096 8097 8098 8099 8100 8101 8102 8103 8104 8105 8106 8107 8108 8109 8110 8111 8112 8113 8114 8115 8116 8117 8118 8119 8120 8121 8122 8123 8124 8125 8126 8127 8128 8129 8130 8131 8132 8133 8134 8135 8136 8137 8138 8139 8140 8141 8142 8143 8144 8145 8146 8147 8148 8149 8150 8151 8152 8153 8154 8155 8156 8157 8158 8159 8160 8161 8162 8163 8164 8165 8166 8167 8168 8169 8170 8171 8172 8173 8174 8175 8176 8177 8178 8179 8180 8181 8182 8183 8184 8185 8186 8187 8188 8189 8190 8191 8192 8193 8194 8195 8196 8197 8198 8199 8200 8201 8202 8203 8204 8205 8206 8207 8208 8209 8210 8211 8212 8213 8214 8215 8216 8217 8218 8219 8220 8221 8222 8223 8224 8225 8226 8227 8228 8229 8230 8231 8232 8233 8234 8235 8236 8237 8238 8239 8240 8241 8242 8243 8244 8245 8246 8247 8248 8249 8250 8251 8252 8253 8254 8255 8256 8257 8258 8259 8260 8261 8262 8263 8264 8265 8266 8267 8268 8269 8270 8271 8272 8273 8274 8275 8276 8277 8278 8279 8280 8281 8282 8283 8284 8285 8286 8287 8288 8289 8290 8291 8292 8293 8294 8295 8296 8297 8298 8299 8300 8301 8302 8303 8304 8305 8306 8307 8308 8309 8310 8311 8312 8313 8314 8315 8316 8317 8318 8319 8320 8321 8322 8323 8324 8325 8326 8327 8328 8329 8330 8331 8332 8333 8334 8335 8336 8337 8338 8339 8340 8341 8342 8343 8344 8345 8346 8347 8348 8349 8350 8351 8352 8353 8354 8355 8356 8357 8358 8359 8360 8361 8362 8363 8364 8365 8366 8367 8368 8369 8370 8371 8372 8373 8374 8375 8376 8377 8378 8379 8380 8381 8382 8383 8384 8385 8386 8387 8388 8389 8390 8391 8392 8393 8394 8395 8396 8397 8398 8399 8400 8401 8402 8403 8404 8405 8406 8407 8408 8409 8410 8411 8412 8413 8414 8415 8416 8417 8418 8419 8420 8421 8422 8423 8424 8425 8426 8427 8428 8429 8430 8431 8432 8433 8434 8435 8436 8437 8438 8439 8440 8441 8442 8443 8444 8445 8446 8447 8448 8449 8450 8451 8452 8453 8454 8455 8456 8457 8458 8459 8460 8461 8462 8463 8464 8465 8466 8467 8468 8469 8470 8471 8472 8473 8474 8475 8476 8477 8478 8479 8480 8481 8482 8483 8484 8485 8486 8487 8488 8489 8490 8491 8492 8493 8494 8495 8496 8497 8498 8499 8500 8501 8502 8503 8504 8505 8506 8507 8508 8509 8510 8511 8512 8513 8514 8515 8516 8517 8518 8519 8520 8521 8522 8523 8524 8525 8526 8527 8528 8529 8530 8531 8532 8533 8534 8535 8536 8537 8538 8539 8540 8541 8542 8543 8544 8545 8546 8547 8548 8549 8550 8551 8552 8553 8554 8555 8556 8557 8558 8559 8560 8561 8562 8563 8564 8565 8566 8567 8568 8569 8570 8571 8572 8573 8574 8575 8576 8577 8578 8579 8580 8581 8582 8583 8584 8585 8586 8587 8588 8589 8590 8591 8592 8593 8594 8595 8596 8597 8598 8599 8600 8601 8602 8603 8604 8605 8606 8607 8608 8609 8610 8611 8612 8613 8614 8615 8616 8617 8618 8619 8620 8621 8622 8623 8624 8625 8626 8627 8628 8629 8630 8631 8632 8633 8634 8635 8636 8637 8638 8639 8640 8641 8642 8643 8644 8645 8646 8647 8648 8649 8650 8651 8652 8653 8654 8655 8656 8657 8658 8659 8660 8661 8662 8663 8664 8665 8666 8667 8668 8669 8670 8671 8672 8673 8674 8675 8676 8677 8678 8679 8680 8681 8682 8683 8684 8685 8686 8687 8688 8689 8690 8691 8692 8693 8694 8695 8696 8697 8698 8699 8700 8701 8702 8703 8704 8705 8706 8707 8708 8709 8710 8711 8712 8713 8714 8715 8716 8717 8718 8719 8720 8721 8722 8723 8724 8725 8726 8727 8728 8729 8730 8731 8732 8733 8734 8735 8736 8737 8738 8739 8740 8741 8742 8743 8744 8745 8746 8747 8748 8749 8750 8751 8752 8753 8754 8755 8756 8757 8758 8759 8760 8761 8762 8763 8764 8765 8766 8767 8768 8769 8770 8771 8772 8773 8774 8775 8776 8777 8778 8779 8780 8781 8782 8783 8784 8785 8786 8787 8788 8789 8790 8791 8792 8793 8794 8795 8796 8797 8798 8799 8800 8801 8802 8803 8804 8805 8806 8807 8808 8809 8810 8811 8812 8813 8814 8815 8816 8817 8818 8819 8820 8821 8822 8823 8824 8825 8826 8827 8828 8829 8830 8831 8832 8833 8834 8835 8836 8837 8838 8839 8840 8841 8842 8843 8844 8845 8846 8847 8848 8849 8850 8851 8852 8853 8854 8855 8856 8857 8858 8859 8860 8861 8862 8863 8864 8865 8866 8867 8868 8869 8870 8871 8872 8873 8874 8875 8876 8877 8878 8879 8880 8881 8882 8883 8884 8885 8886 8887 8888 8889 8890 8891 8892 8893 8894 8895 8896 8897 8898 8899 8900 8901 8902 8903 8904 8905 8906 8907 8908 8909 8910 8911 8912 8913 8914 8915 8916 8917 8918 8919 8920 8921 8922 8923 8924 8925 8926 8927 8928 8929 8930 8931 8932 8933 8934 8935 8936 8937 8938 8939 8940 8941 8942 8943 8944 8945 8946 8947 8948 8949 8950 8951 8952 8953 8954 8955 8956 8957 8958 8959 8960 8961 8962 8963 8964 8965 8966 8967 8968 8969 8970 8971 8972 8973 8974 8975 8976 8977 8978 8979 8980 8981 8982 8983 8984 8985 8986 8987 8988 8989 8990 8991 8992 8993 8994 8995 8996 8997 8998 8999 9000 9001 9002 9003 9004 9005 9006 9007 9008 9009 9010 9011 9012 9013 9014 9015 9016 9017 9018 9019 9020 9021 9022 9023 9024 9025 9026 9027 9028 9029 9030 9031 9032 9033 9034 9035 9036 9037 9038 9039 9040 9041 9042 9043 9044 9045 9046 9047 9048 9049 9050 9051 9052 9053 9054 9055 9056 9057 9058 9059 9060 9061 9062 9063 9064 9065 9066 9067 9068 9069 9070 9071 9072 9073 9074 9075 9076 9077 9078 9079 9080 9081 9082 9083 9084 9085 9086 9087 9088 9089 9090 9091 9092 9093 9094 9095 9096 9097 9098 9099 9100 9101 9102 9103 9104 9105 9106 9107 9108 9109 9110 9111 9112 9113 9114 9115 9116 9117 9118 9119 9120 9121 9122 9123 9124 9125 9126 9127 9128 9129 9130 9131 9132 9133 9134 9135 9136 9137 9138 9139 9140 9141 9142 9143 9144 9145 9146 9147 9148 9149 9150 9151 9152 9153 9154 9155 9156 9157 9158 9159 9160 9161 9162 9163 9164 9165 9166 9167 9168 9169 9170 9171 9172 9173 9174 9175 9176 9177 9178 9179 9180 9181 9182 9183 9184 9185 9186 9187 9188 9189 9190 9191 9192 9193 9194 9195 9196 9197 9198 9199 9200 9201 9202 9203 9204 9205 9206 9207 9208 9209 9210 9211 9212 9213 9214 9215 9216 9217 9218 9219 9220 9221 9222 9223 9224 9225 9226 9227 9228 9229 9230 9231 9232 9233 9234 9235 9236 9237 9238 9239 9240 9241 9242 9243 9244 9245 9246 9247 9248 9249 9250 9251 9252 9253 9254 9255 9256 9257 9258 9259 9260 9261 9262 9263 9264 9265 9266 9267 9268 9269 9270 9271 9272 9273 9274 9275 9276 9277 9278 9279 9280 9281 9282 9283 9284 9285 9286 9287 9288 9289 9290 9291 9292 9293 9294 9295 9296 9297 9298 9299 9300 9301 9302 9303 9304 9305 9306 9307 9308 9309 9310 9311 9312 9313 9314 9315 9316 9317 9318 9319 9320 9321 9322 9323 9324 9325 9326 9327 9328 9329 9330 9331 9332 9333 9334 9335 9336 9337 9338 9339 9340 9341 9342 9343 9344 9345 9346 9347 9348 9349 9350 9351 9352 9353 9354 9355 9356 9357 9358 9359 9360 9361 9362 9363 9364 9365 9366 9367 9368 9369 9370 9371 9372 9373 9374 9375 9376 9377 9378 9379 9380 9381 9382 9383 9384 9385 9386 9387 9388 9389 9390 9391 9392 9393 9394 9395 9396 9397 9398 9399 9400 9401 9402 9403 9404 9405 9406 9407 9408 9409 9410 9411 9412 9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423 9424 9425 9426 9427 9428 9429 9430 9431 9432 9433 9434 9435 9436 9437 9438 9439 9440 9441 9442 9443 9444 9445 9446 9447 9448 9449 9450 9451 9452 9453 9454 9455 9456 9457 9458 9459 9460 9461 9462 9463 9464 9465 9466 9467 9468 9469 9470 9471 9472 9473 9474 9475 9476 9477 9478 9479 9480 9481 9482 9483 9484 9485 9486 9487 9488 9489 9490 9491 9492 9493 9494 9495 9496 9497 9498 9499 9500 9501 9502 9503 9504 9505 9506 9507 9508 9509 9510 9511 9512 9513 9514 9515 9516 9517 9518 9519 9520 9521 9522 9523 9524 9525 9526 9527 9528 9529 9530 9531 9532 9533 9534 9535 9536 9537 9538 9539 9540 9541 9542 9543 9544 9545 9546 9547 9548 9549 9550 9551 9552 9553 9554 9555 9556 9557 9558 9559 9560 9561 9562 9563 9564 9565 9566 9567 9568 9569 9570 9571 9572 9573 9574 9575 9576 9577 9578 9579 9580 9581 9582 9583 9584 9585 9586 9587 9588 9589 9590 9591 9592 9593 9594 9595 9596 9597 9598 9599 9600 9601 9602 9603 9604 9605 9606 9607 9608 9609 9610 9611 9612 9613 9614 9615 9616 9617 9618 9619 9620 9621 9622 9623 9624 9625 9626 9627 9628 9629 9630 9631 9632 9633 9634 9635 9636 9637 9638 9639 9640 9641 9642 9643 9644 9645 9646 9647 9648 9649 9650 9651 9652 9653 9654 9655 9656 9657 9658 9659 9660 9661 9662 9663 9664 9665 9666 9667 9668 9669 9670 9671 9672 9673 9674 9675 9676 9677 9678 9679 9680 9681 9682 9683 9684 9685 9686 9687 9688 9689 9690 9691 9692 9693 9694 9695 9696 9697 9698 9699 9700 9701 9702 9703 9704 9705 9706 9707 9708 9709 9710 9711 9712 9713 9714 9715 9716 9717 9718 9719 9720 9721 9722 9723 9724 9725 9726 9727 9728 9729 9730 9731 9732 9733 9734 9735 9736 9737 9738 9739 9740 9741 9742 9743 9744 9745 9746 9747 9748 9749 9750 9751 9752 9753 9754 9755 9756 9757 9758 9759 9760 9761 9762 9763 9764 9765 9766 9767 9768 9769 9770 9771 9772 9773 9774 9775 9776 9777 9778 9779 9780 9781 9782 9783 9784 9785 9786 9787 9788 9789 9790 9791 9792 9793 9794 9795 9796 9797 9798 9799 9800 9801 9802 9803 9804 9805 9806 9807 9808 9809 9810 9811 9812 9813 9814 9815 9816 9817 9818 9819 9820 9821 9822 9823 9824 9825 9826 9827 9828 9829 9830 9831 9832 9833 9834 9835 9836 9837 9838 9839 9840 9841 9842 9843 9844 9845 9846 9847 9848 9849 9850 9851 9852 9853 9854 9855 9856 9857 9858 9859 9860 9861 9862 9863 9864 9865 9866 9867 9868 9869 9870 9871 9872 9873 9874 9875 9876 9877 9878 9879 9880 9881 9882 9883 9884 9885 9886 9887 9888 9889 9890 9891 9892 9893 9894 9895 9896 9897 9898 9899 9900 9901 9902 9903 9904 9905 9906 9907 9908 9909 9910 9911 9912 9913 9914 9915 9916 9917 9918 9919 9920 9921 9922 9923 9924 9925 9926 9927 9928 9929 9930 9931 9932 9933 9934 9935 9936 9937 9938 9939 9940 9941 9942 9943 9944 9945 9946 9947 9948 9949 9950 9951 9952 9953 9954 9955 9956 9957 9958 9959 9960 9961 9962 9963 9964 9965 9966 9967 9968 9969 9970 9971 9972 9973 9974 9975 9976 9977 9978 9979 9980 9981 9982 9983 9984 9985 9986 9987 9988 9989 9990 9991 9992 9993 9994 9995 9996 9997 9998 9999 10000 10001 10002 10003 10004 10005 10006 10007 10008 10009 10010 10011 10012 10013 10014 10015 10016 10017 10018 10019 10020 10021 10022 10023 10024 10025 10026 10027 10028 10029 10030 10031 10032 10033 10034 10035 10036 10037 10038 10039 10040 10041 10042 10043 10044 10045 10046 10047 10048 10049 10050 10051 10052 10053 10054 10055 10056 10057 10058 10059 10060 10061 10062 10063 10064 10065 10066 10067 10068 10069 10070 10071 10072 10073 10074 10075 10076 10077 10078 10079 10080 10081 10082 10083 10084 10085 10086 10087 10088 10089 10090 10091 10092 10093 10094 10095 10096 10097 10098 10099 10100 10101 10102 10103 10104 10105 10106 10107 10108 10109 10110 10111 10112 10113 10114 10115 10116 10117 10118 10119 10120 10121 10122 10123 10124 10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 10139 10140 10141 10142 10143 10144 10145 10146 10147 10148 10149 10150 10151 10152 10153 10154 10155 10156 10157 10158 10159 10160 10161 10162 10163 10164 10165 10166 10167 10168 10169 10170 10171 10172 10173 10174 10175 10176 10177 10178 10179 10180 10181 10182 10183 10184 10185 10186 10187 10188 10189 10190 10191 10192 10193 10194 10195 10196 10197 10198 10199 10200 10201 10202 10203 10204 10205 10206 10207 10208 10209 10210 10211 10212 10213 10214 10215 10216 10217 10218 10219 10220 10221 10222 10223 10224 10225 10226 10227 10228 10229 10230 10231 10232 10233 10234 10235 10236 10237 10238 10239 10240 10241 10242 10243 10244 10245 10246 10247 10248 10249 10250 10251 10252 10253 10254 10255 10256 10257 10258 10259 10260 10261 10262 10263 10264 10265 10266 10267 10268 10269 10270 10271 10272 10273 10274 10275 10276 10277 10278 10279 10280 10281 10282 10283 10284 10285 10286 10287 10288 10289 10290 10291 10292 10293 10294 10295 10296 10297 10298 10299 10300 10301 10302 10303 10304 10305 10306 10307 10308 10309 10310 10311 10312 10313 10314 10315 10316 10317 10318 10319 10320 10321 10322 10323 10324 10325 10326 10327 10328 10329 10330 10331 10332 10333 10334 10335 10336 10337 10338 10339 10340 10341 10342 10343 10344 10345 10346 10347 10348 10349 10350 10351 10352 10353 10354 10355 10356 10357 10358 10359 10360 10361 10362 10363 10364 10365 10366 10367 10368 10369 10370 10371 10372 10373 10374 10375 10376 10377 10378 10379 10380 10381 10382 10383 10384 10385 10386 10387 10388 10389 10390 10391 10392 10393 10394 10395 10396 10397 10398 10399 10400 10401 10402 10403 10404 10405 10406 10407 10408 10409 10410 10411 10412 10413 10414 10415 10416 10417 10418 10419 10420 10421 10422 10423 10424 10425 10426 10427 10428 10429 10430 10431 10432 10433 10434 10435 10436 10437 10438 10439 10440 10441 10442 10443 10444 10445 10446 10447 10448 10449 10450 10451 10452 10453 10454 10455 10456 10457 10458 10459 10460 10461 10462 10463 10464 10465 10466 10467 10468 10469 10470 10471 10472 10473 10474 10475 10476 10477 10478 10479 10480 10481 10482 10483 10484 10485 10486 10487 10488 10489 10490 10491 10492 10493 10494 10495 10496 10497 10498 10499 10500 10501 10502 10503 10504 10505 10506 10507 10508 10509 10510 10511 10512 10513 10514 10515 10516 10517 10518 10519 10520 10521 10522 10523 10524 10525 10526 10527 10528 10529 10530 10531 10532 10533 10534 10535 10536 10537 10538 10539 10540 10541 10542 10543 10544 10545 10546 10547 10548 10549 10550 10551 10552 10553 10554 10555 10556 10557 10558 10559 10560 10561 10562 10563 10564 10565 10566 10567 10568 10569 10570 10571 10572 10573 10574 10575 10576 10577 10578 10579 10580 10581 10582 10583 10584 10585 10586 10587 10588 10589 10590 10591 10592 10593 10594 10595 10596 10597 10598 10599 10600 10601 10602 10603 10604 10605 10606 10607 10608 10609 10610 10611 10612 10613 10614 10615 10616 10617 10618 10619 10620 10621 10622 10623 10624 10625 10626 10627 10628 10629 10630 10631 10632 10633 10634 10635 10636 10637 10638 10639 10640 10641 10642 10643 10644 10645 10646 10647 10648 10649 10650 10651 10652 10653 10654 10655 10656 10657 10658 10659 10660 10661 10662 10663 10664 10665 10666 10667 10668 10669 10670 10671 10672 10673 10674 10675 10676 10677 10678 10679 10680 10681 10682 10683 10684 10685 10686 10687 10688 10689 10690 10691 10692 10693 10694 10695 10696 10697 10698 10699 10700 10701 10702 10703 10704 10705 10706 10707 10708 10709 10710 10711 10712 10713 10714 10715 10716 10717 10718 10719 10720 10721 10722 10723 10724 10725 10726 10727 10728 10729 10730 10731 10732 10733 10734 10735 10736 10737 10738 10739 10740 10741 10742 10743 10744 10745 10746 10747 10748 10749 10750 10751 10752 10753 10754 10755 10756 10757 10758 10759 10760 10761 10762 10763 10764 10765 10766 10767 10768 10769 10770 10771 10772 10773 10774 10775 10776 10777 10778 10779 10780 10781 10782 10783 10784 10785 10786 10787 10788 10789 10790 10791 10792 10793 10794 10795 10796 10797 10798 10799 10800 10801 10802 10803 10804 10805 10806 10807 10808 10809 10810 10811 10812 10813 10814 10815 10816 10817 10818 10819 10820 10821 10822 10823 10824 10825 10826 10827 10828 10829 10830 10831 10832 10833 10834 10835 10836 10837 10838 10839 10840 10841 10842 10843 10844 10845 10846 10847 10848 10849 10850 10851 10852 10853 10854 10855 10856 10857 10858 10859 10860 10861 10862 10863 10864 10865 10866 10867 10868 10869 10870 10871 10872 10873 10874 10875 10876 10877 10878 10879 10880 10881 10882 10883 10884 10885 10886 10887 10888 10889 10890 10891 10892 10893 10894 10895 10896 10897 10898 10899 10900 10901 10902 10903 10904 10905 10906 10907 10908 10909 10910 10911 10912 10913 10914 10915 10916 10917 10918 10919 10920 10921 10922 10923 10924 10925 10926 10927 10928 10929 10930 10931 10932 10933 10934 10935 10936 10937 10938 10939 10940 10941 10942 10943 10944 10945 10946 10947 10948 10949 10950 10951 10952 10953 10954 10955 10956 10957 10958 10959 10960 10961 10962 10963 10964 10965 10966 10967 10968 10969 10970 10971 10972 10973 10974 10975 10976 10977 10978 10979 10980 10981 10982 10983 10984 10985 10986 10987 10988 10989 10990 10991 10992 10993 10994 10995 10996 10997 10998 10999 11000 11001 11002 11003 11004 11005 11006 11007 11008 11009 11010 11011 11012 11013 11014 11015 11016 11017 11018 11019 11020 11021 11022 11023 11024 11025 11026 11027 11028 11029 11030 11031 11032 11033 11034 11035 11036 11037 11038 11039 11040 11041 11042 11043 11044 11045 11046 11047 11048 11049 11050 11051 11052 11053 11054 11055 11056 11057 11058 11059 11060 11061 11062 11063 11064 11065 11066 11067 11068 11069 11070 11071 11072 11073 11074 11075 11076 11077 11078 11079 11080 11081 11082 11083 11084 11085 11086 11087 11088 11089 11090 11091 11092 11093 11094 11095 11096 11097 11098 11099 11100 11101 11102 11103 11104 11105 11106 11107 11108 11109 11110 11111 11112 11113 11114 11115 11116 11117 11118 11119 11120 11121 11122 11123 11124 11125 11126 11127 11128 11129 11130 11131 11132 11133 11134 11135 11136 11137 11138 11139 11140 11141 11142 11143 11144 11145 11146 11147 11148 11149 11150 11151 11152 11153 11154 11155 11156 11157 11158 11159 11160 11161 11162 11163 11164 11165 11166 11167 11168 11169 11170 11171 11172 11173 11174 11175 11176 11177 11178 11179 11180 11181 11182 11183 11184 11185 11186 11187 11188 11189 11190 11191 11192 11193 11194 11195 11196 11197 11198 11199 11200 11201 11202 11203 11204 11205 11206 11207 11208 11209 11210 11211 11212 11213 11214 11215 11216 11217 11218 11219 11220 11221 11222 11223 11224 11225 11226 11227 11228 11229 11230 11231 11232 11233 11234 11235 11236 11237 11238 11239 11240 11241 11242 11243 11244 11245 11246 11247 11248 11249 11250 11251 11252 11253 11254 11255 11256 11257 11258 11259 11260 11261 11262 11263 11264 11265 11266 11267 11268 11269 11270 11271 11272 11273 11274 11275 11276 11277 11278 11279 11280 11281 11282 11283 11284 11285 11286 11287 11288 11289 11290 11291 11292 11293 11294 11295 11296 11297 11298 11299 11300 11301 11302 11303 11304 11305 11306 11307 11308 11309 11310 11311 11312 11313 11314 11315 11316 11317 11318 11319 11320 11321 11322 11323 11324 11325 11326 11327 11328 11329 11330 11331 11332 11333 11334 11335 11336 11337 11338 11339 11340 11341 11342 11343 11344 11345 11346 11347 11348 11349 11350 11351 11352 11353 11354 11355 11356 11357 11358 11359 11360 11361 11362 11363 11364 11365 11366 11367 11368 11369 11370 11371 11372 11373 11374 11375 11376 11377 11378 11379 11380 11381 11382 11383 11384 11385 11386 11387 11388 11389 11390 11391 11392 11393 11394 11395 11396 11397 11398 11399 11400 11401 11402 11403 11404 11405 11406 11407 11408 11409 11410 11411 11412 11413 11414 11415 11416 11417 11418 11419 11420 11421 11422 11423 11424 11425 11426 11427 11428 11429 11430 11431 11432 11433 11434 11435 11436 11437 11438 11439 11440 11441 11442 11443 11444 11445 11446 11447 11448 11449 11450 11451 11452 11453 11454 11455 11456 11457 11458 11459 11460 11461 11462 11463 11464 11465 11466 11467 11468 11469 11470 11471 11472 11473 11474 11475 11476 11477 11478 11479 11480 11481 11482 11483 11484 11485 11486 11487 11488 11489 11490 11491 11492 11493 11494 11495 11496 11497 11498 11499 11500 11501 11502 11503 11504 11505 11506 11507 11508 11509 11510 11511 11512 11513 11514 11515 11516 11517 11518 11519 11520 11521 11522 11523 11524 11525 11526 11527 11528 11529 11530 11531 11532 11533 11534 11535 11536 11537 11538 11539 11540 11541 11542 11543 11544 11545 11546 11547 11548 11549 11550 11551 11552 11553 11554 11555 11556 11557 11558 11559 11560 11561 11562 11563 11564 11565 11566 11567 11568 11569 11570 11571 11572 11573 11574 11575 11576 11577 11578 11579 11580 11581 11582 11583 11584 11585 11586 11587 11588 11589 11590 11591 11592 11593 11594 11595 11596 11597 11598 11599 11600 11601 11602 11603 11604 11605 11606 11607 11608 11609 11610 11611 11612 11613 11614 11615 11616 11617 11618 11619 11620 11621 11622 11623 11624 11625 11626 11627 11628 11629 11630 11631 11632 11633 11634 11635 11636 11637 11638 11639 11640 11641 11642 11643 11644 11645 11646 11647 11648 11649 11650 11651 11652 11653 11654 11655 11656 11657 11658 11659 11660 11661 11662 11663 11664 11665 11666 11667 11668 11669 11670 11671 11672 11673 11674 11675 11676 11677 11678 11679 11680 11681 11682 11683 11684 11685 11686 11687 11688 11689 11690 11691 11692 11693 11694 11695 11696 11697 11698 11699 11700 11701 11702 11703 11704 11705 11706 11707 11708 11709 11710 11711 11712 11713 11714 11715 11716 11717 11718 11719 11720 11721 11722 11723 11724 11725 11726 11727 11728 11729 11730 11731 11732 11733 11734 11735 11736 11737 11738 11739 11740 11741 11742 11743 11744 11745 11746 11747 11748 11749 11750 11751 11752 11753 11754 11755 11756 11757 11758 11759 11760 11761 11762 11763 11764 11765 11766 11767 11768 11769 11770 11771 11772 11773 11774 11775 11776 11777 11778 11779 11780 11781 11782 11783 11784 11785 11786 11787 11788 11789 11790 11791 11792 11793 11794 11795 11796 11797 11798 11799 11800 11801 11802 11803 11804 11805 11806 11807 11808 11809 11810 11811 11812 11813 11814 11815 11816 11817 11818 11819 11820 11821 11822 11823 11824 11825 11826 11827 11828 11829 11830 11831 11832 11833 11834 11835 11836 11837 11838 11839 11840 11841 11842 11843 11844 11845 11846 11847 11848 11849 11850 11851 11852 11853 11854 11855 11856 11857 11858 11859 11860 11861 11862 11863 11864 11865 11866 11867 11868 11869 11870 11871 11872 11873 11874 11875 11876 11877 11878 11879 11880 11881 11882 11883 11884 11885 11886 11887 11888 11889 11890 11891 11892 11893 11894 11895 11896 11897 11898 11899 11900 11901 11902 11903 11904 11905 11906 11907 11908 11909 11910 11911 11912 11913 11914 11915 11916 11917 11918 11919 11920 11921 11922 11923 11924 11925 11926 11927 11928 11929 11930 11931 11932 11933 11934 11935 11936 11937 11938 11939 11940 11941 11942 11943 11944 11945 11946 11947 11948 11949 11950 11951 11952 11953 11954 11955 11956 11957 11958 11959 11960 11961 11962 11963 11964 11965 11966 11967 11968 11969 11970 11971 11972 11973 11974 11975 11976 11977 11978 11979 11980 11981 11982 11983 11984 11985 11986 11987 11988 11989 11990 11991 11992 11993 11994 11995 11996 11997 11998 11999 12000 12001 12002 12003 12004 12005 12006 12007 12008 12009 12010 12011 12012 12013 12014 12015 12016 12017 12018 12019 12020 12021 12022 12023 12024 12025 12026 12027 12028 12029 12030 12031 12032 12033 12034 12035 12036 12037 12038 12039 12040 12041 12042 12043 12044 12045 12046 12047 12048 12049 12050 12051 12052 12053 12054 12055 12056 12057 12058 12059 12060 12061 12062 12063 12064 12065 12066 12067 12068 12069 12070 12071 12072 12073 12074 12075 12076 12077 12078 12079 12080 12081 12082 12083 12084 12085 12086 12087 12088 12089 12090 12091 12092 12093 12094 12095 12096 12097 12098 12099 12100 12101 12102 12103 12104 12105 12106 12107 12108 12109 12110 12111 12112 12113 12114 12115 12116 12117 12118 12119 12120 12121 12122 12123 12124 12125 12126 12127 12128 12129 12130 12131 12132 12133 12134 12135 12136 12137 12138 12139 12140 12141 12142 12143 12144 12145 12146 12147 12148 12149 12150 12151 12152 12153 12154 12155 12156 12157 12158 12159 12160 12161 12162 12163 12164 12165 12166 12167 12168 12169 12170 12171 12172 12173 12174 12175 12176 12177 12178 12179 12180 12181 12182 12183 12184 12185 12186 12187 12188 12189 12190 12191 12192 12193 12194 12195 12196 12197 12198 12199 12200 12201 12202 12203 12204 12205 12206 12207 12208 12209 12210 12211 12212 12213 12214 12215 12216 12217 12218 12219 12220 12221 12222 12223 12224 12225 12226 12227 12228 12229 12230 12231 12232 12233 12234 12235 12236 12237 12238 12239 12240 12241 12242 12243 12244 12245 12246 12247 12248 12249 12250 12251 12252 12253 12254 12255 12256 12257 12258 12259 12260 12261 12262 12263 12264 12265 12266 12267 12268 12269 12270 12271 12272 12273 12274 12275 12276 12277 12278 12279 12280 12281 12282 12283 12284 12285 12286 12287 12288 12289 12290 12291 12292 12293 12294 12295 12296 12297 12298 12299 12300 12301 12302 12303 12304 12305 12306 12307 12308 12309 12310 12311 12312 12313 12314 12315 12316 12317 12318 12319 12320 12321 12322 12323 12324 12325 12326 12327 12328 12329 12330 12331 12332 12333 12334 12335 12336 12337 12338 12339 12340 12341 12342 12343 12344 12345 12346 12347 12348 12349 12350 12351 12352 12353 12354 12355 12356 12357 12358 12359 12360 12361 12362 12363 12364 12365 12366 12367 12368 12369 12370 12371 12372 12373 12374 12375 12376 12377 12378 12379 12380 12381 12382 12383 12384 12385 12386 12387 12388 12389 12390 12391 12392 12393 12394 12395 12396 12397 12398 12399 12400 12401 12402 12403 12404 12405 12406 12407 12408 12409 12410 12411 12412 12413 12414 12415 12416 12417 12418 12419 12420 12421 12422 12423 12424 12425 12426 12427 12428 12429 12430 12431 12432 12433 12434 12435 12436 12437 12438 12439 12440 12441 12442 12443 12444 12445 12446 12447 12448 12449 12450 12451 12452 12453 12454 12455 12456 12457 12458 12459 12460 12461 12462 12463 12464 12465 12466 12467 12468 12469 12470 12471 12472 12473 12474 12475 12476 12477 12478 12479 12480 12481 12482 12483 12484 12485 12486 12487 12488 12489 12490 12491 12492 12493 12494 12495 12496 12497 12498 12499 12500 12501 12502 12503 12504 12505 12506 12507 12508 12509 12510 12511 12512 12513 12514 12515 12516 12517 12518 12519 12520 12521 12522 12523 12524 12525 12526 12527 12528 12529 12530 12531 12532 12533 12534 12535 12536 12537 12538 12539 12540 12541 12542 12543 12544 12545 12546 12547 12548 12549 12550 12551 12552 12553 12554 12555 12556 12557 12558 12559 12560 12561 12562 12563 12564 12565 12566 12567 12568 12569 12570 12571 12572 12573 12574 12575 12576 12577 12578 12579 12580 12581 12582 12583 12584 12585 12586 12587 12588 12589 12590 12591 12592 12593 12594 12595 12596 12597 12598 12599 12600 12601 12602 12603 12604 12605 12606 12607 12608 12609 12610 12611 12612 12613 12614 12615 12616 12617 12618 12619 12620 12621 12622 12623 12624 12625 12626 12627 12628 12629 12630 12631 12632 12633 12634 12635 12636 12637 12638 12639 12640 12641 12642 12643 12644 12645 12646 12647 12648 12649 12650 12651 12652 12653 12654 12655 12656 12657 12658 12659 12660 12661 12662 12663 12664 12665 12666 12667 12668 12669 12670 12671 12672 12673 12674 12675 12676 12677 12678 12679 12680 12681 12682 12683 12684 12685 12686 12687 12688 12689 12690 12691 12692 12693 12694 12695 12696 12697 12698 12699 12700 12701 12702 12703 12704 12705 12706 12707 12708 12709 12710 12711 12712 12713 12714 12715 12716 12717 12718 12719 12720 12721 12722 12723 12724 12725 12726 12727 12728 12729 12730 12731 12732 12733 12734 12735 12736 12737 12738 12739 12740 12741 12742 12743 12744 12745 12746 12747 12748 12749 12750 12751 12752 12753 12754 12755 12756 12757 12758 12759 12760 12761 12762 12763 12764 12765 12766 12767 12768 12769 12770 12771 12772 12773 12774 12775 12776 12777 12778 12779 12780 12781 12782 12783 12784 12785 12786 12787 12788 12789 12790 12791 12792 12793 12794 12795 12796 12797 12798 12799 12800 12801 12802 12803 12804 12805 12806 12807 12808 12809 12810 12811 12812 12813 12814 12815 12816 12817 12818 12819 12820 12821 12822 12823 12824 12825 12826 12827 12828 12829 12830 12831 12832 12833 12834 12835 12836 12837 12838 12839 12840 12841 12842 12843 12844 12845 12846 12847 12848 12849 12850 12851 12852 12853 12854 12855 12856 12857 12858 12859 12860 12861 12862 12863 12864 12865 12866 12867 12868 12869 12870 12871 12872 12873 12874 12875 12876 12877 12878 12879 12880 12881 12882 12883 12884 12885 12886 12887 12888 12889 12890 12891 12892 12893 12894 12895 12896 12897 12898 12899 12900 12901 12902 12903 12904 12905 12906 12907 12908 12909 12910 12911 12912 12913 12914 12915 12916 12917 12918 12919 12920 12921 12922 12923 12924 12925 12926 12927 12928 12929 12930 12931 12932 12933 12934 12935 12936 12937 12938 12939 12940 12941 12942 12943 12944 12945 12946 12947 12948 12949 12950 12951 12952 12953 12954 12955 12956 12957 12958 12959 12960 12961 12962 12963 12964 12965 12966 12967 12968 12969 12970 12971 12972 12973 12974 12975 12976 12977 12978 12979 12980 12981 12982 12983 12984 12985 12986 12987 12988 12989 12990 12991 12992 12993 12994 12995 12996 12997 12998 12999 13000 13001 13002 13003 13004 13005 13006 13007 13008 13009 13010 13011 13012 13013 13014 13015 13016 13017 13018 13019 13020 13021 13022 13023 13024 13025 13026 13027 13028 13029 13030 13031 13032 13033 13034 13035 13036 13037 13038 13039 13040 13041 13042 13043 13044 13045 13046 13047 13048 13049 13050 13051 13052 13053 13054 13055 13056 13057 13058 13059 13060 13061 13062 13063 13064 13065 13066 13067 13068 13069 13070 13071 13072 13073 13074 13075 13076 13077 13078 13079 13080 13081 13082 13083 13084 13085 13086 13087 13088 13089 13090 13091 13092 13093 13094 13095 13096 13097 13098 13099 13100 13101 13102 13103 13104 13105 13106 13107 13108 13109 13110 13111 13112 13113 13114 13115 13116 13117 13118 13119 13120 13121 13122 13123 13124 13125 13126 13127 13128 13129 13130 13131 13132 13133 13134 13135 13136 13137 13138 13139 13140 13141 13142 13143 13144 13145 13146 13147 13148 13149 13150 13151 13152 13153 13154 13155 13156 13157 13158 13159 13160 13161 13162 13163 13164 13165 13166 13167 13168 13169 13170 13171 13172 13173 13174 13175 13176 13177 13178 13179 13180 13181 13182 13183 13184 13185 13186 13187 13188 13189 13190 13191 13192 13193 13194 13195 13196 13197 13198 13199 13200 13201 13202 13203 13204 13205 13206 13207 13208 13209 13210 13211 13212 13213 13214 13215 13216 13217 13218 13219 13220 13221 13222 13223 13224 13225 13226 13227 13228 13229 13230 13231 13232 13233 13234 13235 13236 13237 13238 13239 13240 13241 13242 13243 13244 13245 13246 13247 13248 13249 13250 13251 13252 13253 13254 13255 13256 13257 13258 13259 13260 13261 13262 13263 13264 13265 13266 13267 13268 13269 13270 13271 13272 13273 13274 13275 13276 13277 13278 13279 13280 13281 13282 13283 13284 13285 13286 13287 13288 13289 13290 13291 13292 13293 13294 13295 13296 13297 13298 13299 13300 13301 13302 13303 13304 13305 13306 13307 13308 13309 13310 13311 13312 13313 13314 13315 13316 13317 13318 13319 13320 13321 13322 13323 13324 13325 13326 13327 13328 13329 13330 13331 13332 13333 13334 13335 13336 13337 13338 13339 13340 13341 13342 13343 13344 13345 13346 13347 13348 13349 13350 13351 13352 13353 13354 13355 13356 13357 13358 13359 13360 13361 13362 13363 13364 13365 13366 13367 13368 13369 13370 13371 13372 13373 13374 13375 13376 13377 13378 13379 13380 13381 13382 13383 13384 13385 13386 13387 13388 13389 13390 13391 13392 13393 13394 13395 13396 13397 13398 13399 13400 13401 13402 13403 13404 13405 13406 13407 13408 13409 13410 13411 13412 13413 13414 13415 13416 13417 13418 13419 13420 13421 13422 13423 13424 13425 13426 13427 13428 13429 13430 13431 13432 13433 13434 13435 13436 13437 13438 13439 13440 13441 13442 13443 13444 13445 13446 13447 13448 13449 13450 13451 13452 13453 13454 13455 13456 13457 13458 13459 13460 13461 13462 13463 13464 13465 13466 13467 13468 13469 13470 13471 13472 13473 13474 13475 13476 13477 13478 13479 13480 13481 13482 13483 13484 13485 13486 13487 13488 13489 13490 13491 13492 13493 13494 13495 13496 13497 13498 13499 13500 13501 13502 13503 13504 13505 13506 13507 13508 13509 13510 13511 13512 13513 13514 13515 13516 13517 13518 13519 13520 13521 13522 13523 13524 13525 13526 13527 13528 13529 13530 13531 13532 13533 13534 13535 13536 13537 13538 13539 13540 13541 13542 13543 13544 13545 13546 13547 13548 13549 13550 13551 13552 13553 13554 13555 13556 13557 13558 13559 13560 13561 13562 13563 13564 13565 13566 13567 13568 13569 13570 13571 13572 13573 13574 13575 13576 13577 13578 13579 13580 13581 13582 13583 13584 13585 13586 13587 13588 13589 13590 13591 13592 13593 13594 13595 13596 13597 13598 13599 13600 13601 13602 13603 13604 13605 13606 13607 13608 13609 13610 13611 13612 13613 13614 13615 13616 13617 13618 13619 13620 13621 13622 13623 13624 13625 13626 13627 13628 13629 13630 13631 13632 13633 13634 13635 13636 13637 13638 13639 13640 13641 13642 13643 13644 13645 13646 13647 13648 13649 13650 13651 13652 13653 13654 13655 13656 13657 13658 13659 13660 13661 13662 13663 13664 13665 13666 13667 13668 13669 13670 13671 13672 13673 13674 13675 13676 13677 13678 13679 13680 13681 13682 13683 13684 13685 13686 13687 13688 13689 13690 13691 13692 13693 13694 13695 13696 13697 13698 13699 13700 13701 13702 13703 13704 13705 13706 13707 13708 13709 13710 13711 13712 13713 13714 13715 13716 13717 13718 13719 13720 13721 13722 13723 13724 13725 13726 13727 13728 13729 13730 13731 13732 13733 13734 13735 13736 13737 13738 13739 13740 13741 13742 13743 13744 13745 13746 13747 13748 13749 13750 13751 13752 13753 13754 13755 13756 13757 13758 13759 13760 13761 13762 13763 13764 13765 13766 13767 13768 13769 13770 13771 13772 13773 13774 13775 13776 13777 13778 13779 13780 13781 13782 13783 13784 13785 13786 13787 13788 13789 13790 13791 13792 13793 13794 13795 13796 13797 13798 13799 13800 13801 13802 13803 13804 13805 13806 13807 13808 13809 13810 13811 13812 13813 13814 13815 13816 13817 13818 13819 13820 13821 13822 13823 13824 13825 13826 13827 13828 13829 13830 13831 13832 13833 13834 13835 13836 13837 13838 13839 13840 13841 13842 13843 13844 13845 13846 13847 13848 13849 13850 13851 13852 13853 13854 13855 13856 13857 13858 13859 13860 13861 13862 13863 13864 13865 13866 13867 13868 13869 13870 13871 13872 13873 13874 13875 13876 13877 13878 13879 13880 13881 13882 13883 13884 13885 13886 13887 13888 13889 13890 13891 13892 13893 13894 13895 13896 13897 13898 13899 13900 13901 13902 13903 13904 13905 13906 13907 13908 13909 13910 13911 13912 13913 13914 13915 13916 13917 13918 13919 13920 13921 13922 13923 13924 13925 13926 13927 13928 13929 13930 13931 13932 13933 13934 13935 13936 13937 13938 13939 13940 13941 13942 13943 13944 13945 13946 13947 13948 13949 13950 13951 13952 13953 13954 13955 13956 13957 13958 13959 13960 13961 13962 13963 13964 13965 13966 13967 13968 13969 13970 13971 13972 13973 13974 13975 13976 13977 13978 13979 13980 13981 13982 13983 13984 13985 13986 13987 13988 13989 13990 13991 13992 13993 13994 13995 13996 13997 13998 13999 14000 14001 14002 14003 14004 14005 14006 14007 14008 14009 14010 14011 14012 14013 14014 14015 14016 14017 14018 14019 14020 14021 14022 14023 14024 14025 14026 14027 14028 14029 14030 14031 14032 14033 14034 14035 14036 14037 14038 14039 14040 14041 14042 14043 14044 14045 14046 14047 14048 14049 14050 14051 14052 14053 14054 14055 14056 14057 14058 14059 14060 14061 14062 14063 14064 14065 14066 14067 14068 14069 14070 14071 14072 14073 14074 14075 14076 14077 14078 14079 14080 14081 14082 14083 14084 14085 14086 14087 14088 14089 14090 14091 14092 14093 14094 14095 14096 14097 14098 14099 14100 14101 14102 14103 14104 14105 14106 14107 14108 14109 14110 14111 14112 14113 14114 14115 14116 14117 14118 14119 14120 14121 14122 14123 14124 14125 14126 14127 14128 14129 14130 14131 14132 14133 14134 14135 14136 14137 14138 14139 14140 14141 14142 14143 14144 14145 14146 14147 14148 14149 14150 14151 14152 14153 14154 14155 14156 14157 14158 14159 14160 14161 14162 14163 14164 14165 14166 14167 14168 14169 14170 14171 14172 14173 14174 14175 14176 14177 14178 14179 14180 14181 14182 14183 14184 14185 14186 14187 14188 14189 14190 14191 14192 14193 14194 14195 14196 14197 14198 14199 14200 14201 14202 14203 14204 14205 14206 14207 14208 14209 14210 14211 14212 14213 14214 14215 14216 14217 14218 14219 14220 14221 14222 14223 14224 14225 14226 14227 14228 14229 14230 14231 14232 14233 14234 14235 14236 14237 14238 14239 14240 14241 14242 14243 14244 14245 14246 14247 14248 14249 14250 14251 14252 14253 14254 14255 14256 14257 14258 14259 14260 14261 14262 14263 14264 14265 14266 14267 14268 14269 14270 14271 14272 14273 14274 14275 14276 14277 14278 14279 14280 14281 14282 14283 14284 14285 14286 14287 14288 14289 14290 14291 14292 14293 14294 14295 14296 14297 14298 14299 14300 14301 14302 14303 14304 14305 14306 14307 14308 14309 14310 14311 14312 14313 14314 14315 14316 14317 14318 14319 14320 14321 14322 14323 14324 14325 14326 14327 14328 14329 14330 14331 14332 14333 14334 14335 14336 14337 14338 14339 14340 14341 14342 14343 14344 14345 14346 14347 14348 14349 14350 14351 14352 14353 14354 14355 14356 14357 14358 14359 14360 14361 14362 14363 14364 14365 14366 14367 14368 14369 14370 14371 14372 14373 14374 14375 14376 14377 14378 14379 14380 14381 14382 14383 14384 14385 14386 14387 14388 14389 14390 14391 14392 14393 14394 14395 14396 14397 14398 14399 14400 14401 14402 14403 14404 14405 14406 14407 14408 14409 14410 14411 14412 14413 14414 14415 14416 14417 14418 14419 14420 14421 14422 14423 14424 14425 14426 14427 14428 14429 14430 14431 14432 14433 14434 14435 14436 14437 14438 14439 14440 14441 14442 14443 14444 14445 14446 14447 14448 14449 14450 14451 14452 14453 14454 14455 14456 14457 14458 14459 14460 14461 14462 14463 14464 14465 14466 14467 14468 14469 14470 14471 14472 14473 14474 14475 14476 14477 14478 14479 14480 14481 14482 14483 14484 14485 14486 14487 14488 14489 14490 14491 14492 14493 14494 14495 14496 14497 14498 14499 14500 14501 14502 14503 14504 14505 14506 14507 14508 14509 14510 14511 14512 14513 14514 14515 14516 14517 14518 14519 14520 14521 14522 14523 14524 14525 14526 14527 14528 14529 14530 14531 14532 14533 14534 14535 14536 14537 14538 14539 14540 14541 14542 14543 14544 14545 14546 14547 14548 14549 14550 14551 14552 14553 14554 14555 14556 14557 14558 14559 14560 14561 14562 14563 14564 14565 14566 14567 14568 14569 14570 14571 14572 14573 14574 14575 14576 14577 14578 14579 14580 14581 14582 14583 14584 14585 14586 14587 14588 14589 14590 14591 14592 14593 14594 14595 14596 14597 14598 14599 14600 14601 14602 14603 14604 14605 14606 14607 14608 14609 14610 14611 14612 14613 14614 14615 14616 14617 14618 14619 14620 14621 14622 14623 14624 14625 14626 14627 14628 14629 14630 14631 14632 14633 14634 14635 14636 14637 14638 14639 14640 14641 14642 14643 14644 14645 14646 14647 14648 14649 14650 14651 14652 14653 14654 14655 14656 14657 14658 14659 14660 14661 14662 14663 14664 14665 14666 14667 14668 14669 14670 14671 14672 14673 14674 14675 14676 14677 14678 14679 14680 14681 14682 14683 14684 14685 14686 14687 14688 14689 14690 14691 14692 14693 14694 14695 14696 14697 14698 14699 14700 14701 14702 14703 14704 14705 14706 14707 14708 14709 14710 14711 14712 14713 14714 14715 14716 14717 14718 14719 14720 14721 14722 14723 14724 14725 14726 14727 14728 14729 14730 14731 14732 14733 14734 14735 14736 14737 14738 14739 14740 14741 14742 14743 14744 14745 14746 14747 14748 14749 14750 14751 14752 14753 14754 14755 14756 14757 14758 14759 14760 14761 14762 14763 14764 14765 14766 14767 14768 14769 14770 14771 14772 14773 14774 14775 14776 14777 14778 14779 14780 14781 14782 14783 14784 14785 14786 14787 14788 14789 14790 14791 14792 14793 14794 14795 14796 14797 14798 14799 14800 14801 14802 14803 14804 14805 14806 14807 14808 14809 14810 14811 14812 14813 14814 14815 14816 14817 14818 14819 14820 14821 14822 14823 14824 14825 14826 14827 14828 14829 14830 14831 14832 14833 14834 14835 14836 14837 14838 14839 14840 14841 14842 14843 14844 14845 14846 14847 14848 14849 14850 14851 14852 14853 14854 14855 14856 14857 14858 14859 14860 14861 14862 14863 14864 14865 14866 14867 14868 14869 14870 14871 14872 14873 14874 14875 14876 14877 14878 14879 14880 14881 14882 14883 14884 14885 14886 14887 14888 14889 14890 14891 14892 14893 14894 14895 14896 14897 14898 14899 14900 14901 14902 14903 14904 14905 14906 14907 14908 14909 14910 14911 14912 14913 14914 14915 14916 14917 14918 14919 14920 14921 14922 14923 14924 14925 14926 14927 14928 14929 14930 14931 14932 14933 14934 14935 14936 14937 14938 14939 14940 14941 14942 14943 14944 14945 14946 14947 14948 14949 14950 14951 14952 14953 14954 14955 14956 14957 14958 14959 14960 14961 14962 14963 14964 14965 14966 14967 14968 14969 14970 14971 14972 14973 14974 14975 14976 14977 14978 14979 14980 14981 14982 14983 14984 14985 14986 14987 14988 14989 14990 14991 14992 14993 14994 14995 14996 14997 14998 14999 15000 15001 15002 15003 15004 15005 15006 15007 15008 15009 15010 15011 15012 15013 15014 15015 15016 15017 15018 15019 15020 15021 15022 15023 15024 15025 15026 15027 15028 15029 15030 15031 15032 15033 15034 15035 15036 15037 15038 15039 15040 15041 15042 15043 15044 15045 15046 15047 15048 15049 15050 15051 15052 15053 15054 15055 15056 15057 15058 15059 15060 15061 15062 15063 15064 15065 15066 15067 15068 15069 15070 15071 15072 15073 15074 15075 15076 15077 15078 15079 15080 15081 15082 15083 15084 15085 15086 15087 15088 15089 15090 15091 15092 15093 15094 15095 15096 15097 15098 15099 15100 15101 15102 15103 15104 15105 15106 15107 15108 15109 15110 15111 15112 15113 15114 15115 15116 15117 15118 15119 15120 15121 15122 15123 15124 15125 15126 15127 15128 15129 15130 15131 15132 15133 15134 15135 15136 15137 15138 15139 15140 15141 15142 15143 15144 15145 15146 15147 15148 15149 15150 15151 15152 15153 15154 15155 15156 15157 15158 15159 15160 15161 15162 15163 15164 15165 15166 15167 15168 15169 15170 15171 15172 15173 15174 15175 15176 15177 15178 15179 15180 15181 15182 15183 15184 15185 15186 15187 15188 15189 15190 15191 15192 15193 15194 15195 15196 15197 15198 15199 15200 15201 15202 15203 15204 15205 15206 15207 15208 15209 15210 15211 15212 15213 15214 15215 15216 15217 15218 15219 15220 15221 15222 15223 15224 15225 15226 15227 15228 15229 15230 15231 15232 15233 15234 15235 15236 15237 15238 15239 15240 15241 15242 15243 15244 15245 15246 15247 15248 15249 15250 15251 15252 15253 15254 15255 15256 15257 15258 15259 15260 15261 15262 15263 15264 15265 15266 15267 15268 15269 15270 15271 15272 15273 15274 15275 15276 15277 15278 15279 15280 15281 15282 15283 15284 15285 15286 15287 15288 15289 15290 15291 15292 15293 15294 15295 15296 15297 15298 15299 15300 15301 15302 15303 15304 15305 15306 15307 15308 15309 15310 15311 15312 15313 15314 15315 15316 15317 15318 15319 15320 15321 15322 15323 15324 15325 15326 15327 15328 15329 15330 15331 15332 15333 15334 15335 15336 15337 15338 15339 15340 15341 15342 15343 15344 15345 15346 15347 15348 15349 15350 15351 15352 15353 15354 15355 15356 15357 15358 15359 15360 15361 15362 15363 15364 15365 15366 15367 15368 15369 15370 15371 15372 15373 15374 15375 15376 15377 15378 15379 15380 15381 15382 15383 15384 15385 15386 15387 15388 15389 15390 15391 15392 15393 15394 15395 15396 15397 15398 15399 15400 15401 15402 15403 15404 15405 15406 15407 15408 15409 15410 15411 15412 15413 15414 15415 15416 15417 15418 15419 15420 15421 15422 15423 15424 15425 15426 15427 15428 15429 15430 15431 15432 15433 15434 15435 15436 15437 15438 15439 15440 15441 15442 15443 15444 15445 15446 15447 15448 15449 15450 15451 15452 15453 15454 15455 15456 15457 15458 15459 15460 15461 15462 15463 15464 15465 15466 15467 15468 15469 15470 15471 15472 15473 15474 15475 15476 15477 15478 15479 15480 15481 15482 15483 15484 15485 15486 15487 15488 15489 15490 15491 15492 15493 15494 15495 15496 15497 15498 15499 15500 15501 15502 15503 15504 15505 15506 15507 15508 15509 15510 15511 15512 15513 15514 15515 15516 15517 15518 15519 15520 15521 15522 15523 15524 15525 15526 15527 15528 15529 15530 15531 15532 15533 15534 15535 15536 15537 15538 15539 15540 15541 15542 15543 15544 15545 15546 15547 15548 15549 15550 15551 15552 15553 15554 15555 15556 15557 15558 15559 15560 15561 15562 15563 15564 15565 15566 15567 15568 15569 15570 15571 15572 15573 15574 15575 15576 15577 15578 15579 15580 15581 15582 15583 15584 15585 15586 15587 15588 15589 15590 15591 15592 15593 15594 15595 15596 15597 15598 15599 15600 15601 15602 15603 15604 15605 15606 15607 15608 15609 15610 15611 15612 15613 15614 15615 15616 15617 15618 15619 15620 15621 15622 15623 15624 15625 15626 15627 15628 15629 15630 15631 15632 15633 15634 15635 15636 15637 15638 15639 15640 15641 15642 15643 15644 15645 15646 15647 15648 15649 15650 15651 15652 15653 15654 15655 15656 15657 15658 15659 15660 15661 15662 15663 15664 15665 15666 15667 15668 15669 15670 15671 15672 15673 15674 15675 15676 15677 15678 15679 15680 15681 15682 15683 15684 15685 15686 15687 15688 15689 15690 15691 15692 15693 15694 15695 15696 15697 15698 15699 15700 15701 15702 15703 15704 15705 15706 15707 15708 15709 15710 15711 15712 15713 15714 15715 15716 15717 15718 15719 15720 15721 15722 15723 15724 15725 15726 15727 15728 15729 15730 15731 15732 15733 15734 15735 15736 15737 15738 15739 15740 15741 15742 15743 15744 15745 15746 15747 15748 15749 15750 15751 15752 15753 15754 15755 15756 15757 15758 15759 15760 15761 15762 15763 15764 15765 15766 15767 15768 15769 15770 15771 15772 15773 15774 15775 15776 15777 15778 15779 15780 15781 15782 15783 15784 15785 15786 15787 15788 15789 15790 15791 15792 15793 15794 15795 15796 15797 15798 15799 15800 15801 15802 15803 15804 15805 15806 15807 15808 15809 15810 15811 15812 15813 15814 15815 15816 15817 15818 15819 15820 15821 15822 15823 15824 15825 15826 15827 15828 15829 15830 15831 15832 15833 15834 15835 15836 15837 15838 15839 15840 15841 15842 15843 15844 15845 15846 15847 15848 15849 15850 15851 15852 15853 15854 15855 15856 15857 15858 15859 15860 15861 15862 15863 15864 15865 15866 15867 15868 15869 15870 15871 15872 15873 15874 15875 15876 15877 15878 15879 15880 15881 15882 15883 15884 15885 15886 15887 15888 15889 15890 15891 15892 15893 15894 15895 15896 15897 15898 15899 15900 15901 15902 15903 15904 15905 15906 15907 15908 15909 15910 15911 15912 15913 15914 15915 15916 15917 15918 15919 15920 15921 15922 15923 15924 15925 15926 15927 15928 15929 15930 15931 15932 15933 15934 15935 15936 15937 15938 15939 15940 15941 15942 15943 15944 15945 15946 15947 15948 15949 15950 15951 15952 15953 15954 15955 15956 15957 15958 15959 15960 15961 15962 15963 15964 15965 15966 15967 15968 15969 15970 15971 15972 15973 15974 15975 15976 15977 15978 15979 15980 15981 15982 15983 15984 15985 15986 15987 15988 15989 15990 15991 15992 15993 15994 15995 15996 15997 15998 15999 16000 16001 16002 16003 16004 16005 16006 16007 16008 16009 16010 16011 16012 16013 16014 16015 16016 16017 16018 16019 16020 16021 16022 16023 16024 16025 16026 16027 16028 16029 16030 16031 16032 16033 16034 16035 16036 16037 16038 16039 16040 16041 16042 16043 16044 16045 16046 16047 16048 16049 16050 16051 16052 16053 16054 16055 16056 16057 16058 16059 16060 16061 16062 16063 16064 16065 16066 16067 16068 16069 16070 16071 16072 16073 16074 16075 16076 16077 16078 16079 16080 16081 16082 16083 16084 16085 16086 16087 16088 16089 16090 16091 16092 16093 16094 16095 16096 16097 16098 16099 16100 16101 16102 16103 16104 16105 16106 16107 16108 16109 16110 16111 16112 16113 16114 16115 16116 16117 16118 16119 16120 16121 16122 16123 16124 16125 16126 16127 16128 16129 16130 16131 16132 16133 16134 16135 16136 16137 16138 16139 16140 16141 16142 16143 16144 16145 16146 16147 16148 16149 16150 16151 16152 16153 16154 16155 16156 16157 16158 16159 16160 16161 16162 16163 16164 16165 16166 16167 16168 16169 16170 16171 16172 16173 16174 16175 16176 16177 16178 16179 16180 16181 16182 16183 16184 16185 16186 16187 16188 16189 16190 16191 16192 16193 16194 16195 16196 16197 16198 16199 16200 16201 16202 16203 16204 16205 16206 16207 16208 16209 16210 16211 16212 16213 16214 16215 16216 16217 16218 16219 16220 16221 16222 16223 16224 16225 16226 16227 16228 16229 16230 16231 16232 16233 16234 16235 16236 16237 16238 16239 16240 16241 16242 16243 16244 16245 16246 16247 16248 16249 16250 16251 16252 16253 16254 16255 16256 16257 16258 16259 16260 16261 16262 16263 16264 16265 16266 16267 16268 16269 16270 16271 16272 16273 16274 16275 16276 16277 16278 16279 16280 16281 16282 16283 16284 16285 16286 16287 16288 16289 16290 16291 16292 16293 16294 16295 16296 16297 16298 16299 16300 16301 16302 16303 16304 16305 16306 16307 16308 16309 16310 16311 16312 16313 16314 16315 16316 16317 16318 16319 16320 16321 16322 16323 16324 16325 16326 16327 16328 16329 16330 16331 16332 16333 16334 16335 16336 16337 16338 16339 16340 16341 16342 16343 16344 16345 16346 16347 16348 16349 16350 16351 16352 16353 16354 16355 16356 16357 16358 16359 16360 16361 16362 16363 16364 16365 16366 16367 16368 16369 16370 16371 16372 16373 16374 16375 16376 16377 16378 16379 16380 16381 16382 16383 16384 16385 16386 16387 16388 16389 16390 16391 16392 16393 16394 16395 16396 16397 16398 16399 16400 16401 16402 16403 16404 16405 16406 16407 16408 16409 16410 16411 16412 16413 16414 16415 16416 16417 16418 16419 16420 16421 16422 16423 16424 16425 16426 16427 16428 16429 16430 16431 16432 16433 16434 16435 16436 16437 16438 16439 16440 16441 16442 16443 16444 16445 16446 16447 16448 16449 16450 16451 16452 16453 16454 16455 16456 16457 16458 16459 16460 16461 16462 16463 16464 16465 16466 16467 16468 16469 16470 16471 16472 16473 16474 16475 16476 16477 16478 16479 16480 16481 16482 16483 16484 16485 16486 16487 16488 16489 16490 16491 16492 16493 16494 16495 16496 16497 16498 16499 16500 16501 16502 16503 16504 16505 16506 16507 16508 16509 16510 16511 16512 16513 16514 16515 16516 16517 16518 16519 16520 16521 16522 16523 16524 16525 16526 16527 16528 16529 16530 16531 16532 16533 16534 16535 16536 16537 16538 16539 16540 16541 16542 16543 16544 16545 16546 16547 16548 16549 16550 16551 16552 16553 16554 16555 16556 16557 16558 16559 16560 16561 16562 16563 16564 16565 16566 16567 16568 16569 16570 16571 16572 16573 16574 16575 16576 16577 16578 16579 16580 16581 16582 16583 16584 16585 16586 16587 16588 16589 16590 16591 16592 16593 16594 16595 16596 16597 16598 16599 16600 16601 16602 16603 16604 16605 16606 16607 16608 16609 16610 16611 16612 16613 16614 16615 16616 16617 16618 16619 16620 16621 16622 16623 16624 16625 16626 16627 16628 16629 16630 16631 16632 16633 16634 16635 16636 16637 16638 16639 16640 16641 16642 16643 16644 16645 16646 16647 16648 16649 16650 16651 16652 16653 16654 16655 16656 16657 16658 16659 16660 16661 16662 16663 16664 16665 16666 16667 16668 16669 16670 16671 16672 16673 16674 16675 16676 16677 16678 16679 16680 16681 16682 16683 16684 16685 16686 16687 16688 16689 16690 16691 16692 16693 16694 16695 16696 16697 16698 16699 16700 16701 16702 16703 16704 16705 16706 16707 16708 16709 16710 16711 16712 16713 16714 16715 16716 16717 16718 16719 16720 16721 16722 16723 16724 16725 16726 16727 16728 16729 16730 16731 16732 16733 16734 16735 16736 16737 16738 16739 16740 16741 16742 16743 16744 16745 16746 16747 16748 16749 16750 16751 16752 16753 16754 16755 16756 16757 16758 16759 16760 16761 16762 16763 16764 16765 16766 16767 16768 16769 16770 16771 16772 16773 16774 16775 16776 16777 16778 16779 16780 16781 16782 16783 16784 16785 16786 16787 16788 16789 16790 16791 16792 16793 16794 16795 16796 16797 16798 16799 16800 16801 16802 16803 16804 16805 16806 16807 16808 16809 16810 16811 16812 16813 16814 16815 16816 16817 16818 16819 16820 16821 16822 16823 16824 16825 16826 16827 16828 16829 16830 16831 16832 16833 16834 16835 16836 16837 16838 16839 16840 16841 16842 16843 16844 16845 16846 16847 16848 16849 16850 16851 16852 16853 16854 16855 16856 16857 16858 16859 16860 16861 16862 16863 16864 16865 16866 16867 16868 16869 16870 16871 16872 16873 16874 16875 16876 16877 16878 16879 16880 16881 16882 16883 16884 16885 16886 16887 16888 16889 16890 16891 16892 16893 16894 16895 16896 16897 16898 16899 16900 16901 16902 16903 16904 16905 16906 16907 16908 16909 16910 16911 16912 16913 16914 16915 16916 16917 16918 16919 16920 16921 16922 16923 16924 16925 16926 16927 16928 16929 16930 16931 16932 16933 16934 16935 16936 16937 16938 16939 16940 16941 16942 16943 16944 16945 16946 16947 16948 16949 16950 16951 16952 16953 16954 16955 16956 16957 16958 16959 16960 16961 16962 16963 16964 16965 16966 16967 16968 16969 16970 16971 16972 16973 16974 16975 16976 16977 16978 16979 16980 16981 16982 16983 16984 16985 16986 16987 16988 16989 16990 16991 16992 16993 16994 16995 16996 16997 16998 16999 17000 17001 17002 17003 17004 17005 17006 17007 17008 17009 17010 17011 17012 17013 17014 17015 17016 17017 17018 17019 17020 17021 17022 17023 17024 17025 17026 17027 17028 17029 17030 17031 17032 17033 17034 17035 17036 17037 17038 17039 17040 17041 17042 17043 17044 17045 17046 17047 17048 17049 17050 17051 17052 17053 17054 17055 17056 17057 17058 17059 17060 17061 17062 17063 17064 17065 17066 17067 17068 17069 17070 17071 17072 17073 17074 17075 17076 17077 17078 17079 17080 17081 17082 17083 17084 17085 17086 17087 17088 17089 17090 17091 17092 17093 17094 17095 17096 17097 17098 17099 17100 17101 17102 17103 17104 17105 17106 17107 17108 17109 17110 17111 17112 17113 17114 17115 17116 17117 17118 17119 17120 17121 17122 17123 17124 17125 17126 17127 17128 17129 17130 17131 17132 17133 17134 17135 17136 17137 17138 17139 17140 17141 17142 17143 17144 17145 17146 17147 17148 17149 17150 17151 17152 17153 17154 17155 17156 17157 17158 17159 17160 17161 17162 17163 17164 17165 17166 17167 17168 17169 17170 17171 17172 17173 17174 17175 17176 17177 17178 17179 17180 17181 17182 17183 17184 17185 17186 17187 17188 17189 17190 17191 17192 17193 17194 17195 17196 17197 17198 17199 17200 17201 17202 17203 17204 17205 17206 17207 17208 17209 17210 17211 17212 17213 17214 17215 17216 17217 17218 17219 17220 17221 17222 17223 17224 17225 17226 17227 17228 17229 17230 17231 17232 17233 17234 17235 17236 17237 17238 17239 17240 17241 17242 17243 17244 17245 17246 17247 17248 17249 17250 17251 17252 17253 17254 17255 17256 17257 17258 17259 17260 17261 17262 17263 17264 17265 17266 17267 17268 17269 17270 17271 17272 17273 17274 17275 17276 17277 17278 17279 17280 17281 17282 17283 17284 17285 17286 17287 17288 17289 17290 17291 17292 17293 17294 17295 17296 17297 17298 17299 17300 17301 17302 17303 17304 17305 17306 17307 17308 17309 17310 17311 17312 17313 17314 17315 17316 17317 17318 17319 17320 17321 17322 17323 17324 17325 17326 17327 17328 17329 17330 17331 17332 17333 17334 17335 17336 17337 17338 17339 17340 17341 17342 17343 17344 17345 17346 17347 17348 17349 17350 17351 17352 17353 17354 17355 17356 17357 17358 17359 17360 17361 17362 17363 17364 17365 17366 17367 17368 17369 17370 17371 17372 17373 17374 17375 17376 17377 17378 17379 17380 17381 17382 17383 17384 17385 17386 17387 17388 17389 17390 17391 17392 17393 17394 17395 17396 17397 17398 17399 17400 17401 17402 17403 17404 17405 17406 17407 17408 17409 17410 17411 17412 17413 17414 17415 17416 17417 17418 17419 17420 17421 17422 17423 17424 17425 17426 17427 17428 17429 17430 17431 17432 17433 17434 17435 17436 17437 17438 17439 17440 17441 17442 17443 17444 17445 17446 17447 17448 17449 17450 17451 17452 17453 17454 17455 17456 17457 17458 17459 17460 17461 17462 17463 17464 17465 17466 17467 17468 17469 17470 17471 17472 17473 17474 17475 17476 17477 17478 17479 17480 17481 17482 17483 17484 17485 17486 17487 17488 17489 17490 17491 17492 17493 17494 17495 17496 17497 17498 17499 17500 17501 17502 17503 17504 17505 17506 17507 17508 17509 17510 17511 17512 17513 17514 17515 17516 17517 17518 17519 17520 17521 17522 17523 17524 17525 17526 17527 17528 17529 17530 17531 17532 17533 17534 17535 17536 17537 17538 17539 17540 17541 17542 17543 17544 17545 17546 17547 17548 17549 17550 17551 17552 17553 17554 17555 17556 17557 17558 17559 17560 17561 17562 17563 17564 17565 17566 17567 17568 17569 17570 17571 17572 17573 17574 17575 17576 17577 17578 17579 17580 17581 17582 17583 17584 17585 17586 17587 17588 17589 17590 17591 17592 17593 17594 17595 17596 17597 17598 17599 17600 17601 17602 17603 17604 17605 17606 17607 17608 17609 17610 17611 17612 17613 17614 17615 17616 17617 17618 17619 17620 17621 17622 17623 17624 17625 17626 17627 17628 17629 17630 17631 17632 17633 17634 17635 17636 17637 17638 17639 17640 17641 17642 17643 17644 17645 17646 17647 17648 17649 17650 17651 17652 17653 17654 17655 17656 17657 17658 17659 17660 17661 17662 17663 17664 17665 17666 17667 17668 17669 17670 17671 17672 17673 17674 17675 17676 17677 17678 17679 17680 17681 17682 17683 17684 17685 17686 17687 17688 17689 17690 17691 17692 17693 17694 17695 17696 17697 17698 17699 17700 17701 17702 17703 17704 17705 17706 17707 17708 17709 17710 17711 17712 17713 17714 17715 17716 17717 17718 17719 17720 17721 17722 17723 17724 17725 17726 17727 17728 17729 17730 17731 17732 17733 17734 17735 17736 17737 17738 17739 17740 17741 17742 17743 17744 17745 17746 17747 17748 17749 17750 17751 17752 17753 17754 17755 17756 17757 17758 17759 17760 17761 17762 17763 17764 17765 17766 17767 17768 17769 17770 17771 17772 17773 17774 17775 17776 17777 17778 17779 17780 17781 17782 17783 17784 17785 17786 17787 17788 17789 17790 17791 17792 17793 17794 17795 17796 17797 17798 17799 17800 17801 17802 17803 17804 17805 17806 17807 17808 17809 17810 17811 17812 17813 17814 17815 17816 17817 17818 17819 17820 17821 17822 17823 17824 17825 17826 17827 17828 17829 17830 17831 17832 17833 17834 17835 17836 17837 17838 17839 17840 17841 17842 17843 17844 17845 17846 17847 17848 17849 17850 17851 17852 17853 17854 17855 17856 17857 17858 17859 17860 17861 17862 17863 17864 17865 17866 17867 17868 17869 17870 17871 17872 17873 17874 17875 17876 17877 17878 17879 17880 17881 17882 17883 17884 17885 17886 17887 17888 17889 17890 17891 17892 17893 17894 17895 17896 17897 17898 17899 17900 17901 17902 17903 17904 17905 17906 17907 17908 17909 17910 17911 17912 17913 17914 17915 17916 17917 17918 17919 17920 17921 17922 17923 17924 17925 17926 17927 17928 17929 17930 17931 17932 17933 17934 17935 17936 17937 17938 17939 17940 17941 17942 17943 17944 17945 17946 17947 17948 17949 17950 17951 17952 17953 17954 17955 17956 17957 17958 17959 17960 17961 17962 17963 17964 17965 17966 17967 17968 17969 17970 17971 17972 17973 17974 17975 17976 17977 17978 17979 17980 17981 17982 17983 17984 17985 17986 17987 17988 17989 17990 17991 17992 17993 17994 17995 17996 17997 17998 17999 18000 18001 18002 18003 18004 18005 18006 18007 18008 18009 18010 18011 18012 18013 18014 18015 18016 18017 18018 18019 18020 18021 18022 18023 18024 18025 18026 18027 18028 18029 18030 18031 18032 18033 18034 18035 18036 18037 18038 18039 18040 18041 18042 18043 18044 18045 18046 18047 18048 18049 18050 18051 18052 18053 18054 18055 18056 18057 18058 18059 18060 18061 18062 18063 18064 18065 18066 18067 18068 18069 18070 18071 18072 18073 18074 18075 18076 18077 18078 18079 18080 18081 18082 18083 18084 18085 18086 18087 18088 18089 18090 18091 18092 18093 18094 18095 18096 18097 18098 18099 18100 18101 18102 18103 18104 18105 18106 18107 18108 18109 18110 18111 18112 18113 18114 18115 18116 18117 18118 18119 18120 18121 18122 18123 18124 18125 18126 18127 18128 18129 18130 18131 18132 18133 18134 18135 18136 18137 18138 18139 18140 18141 18142 18143 18144 18145 18146 18147 18148 18149 18150 18151 18152 18153 18154 18155 18156 18157 18158 18159 18160 18161 18162 18163 18164 18165 18166 18167 18168 18169 18170 18171 18172 18173 18174 18175 18176 18177 18178 18179 18180 18181 18182 18183 18184 18185 18186 18187 18188 18189 18190 18191 18192 18193 18194 18195 18196 18197 18198 18199 18200 18201 18202 18203 18204 18205 18206 18207 18208 18209 18210 18211 18212 18213 18214 18215 18216 18217 18218 18219 18220 18221 18222 18223 18224 18225 18226 18227 18228 18229 18230 18231 18232 18233 18234 18235 18236 18237 18238 18239 18240 18241 18242 18243 18244 18245 18246 18247 18248 18249 18250 18251 18252 18253 18254 18255 18256 18257 18258 18259 18260 18261 18262 18263 18264 18265 18266 18267 18268 18269 18270 18271 18272 18273 18274 18275 18276 18277 18278 18279 18280 18281 18282 18283 18284 18285 18286 18287 18288 18289 18290 18291 18292 18293 18294 18295 18296 18297 18298 18299 18300 18301 18302 18303 18304 18305 18306 18307 18308 18309 18310 18311 18312 18313 18314 18315 18316 18317 18318 18319 18320 18321 18322 18323 18324 18325 18326 18327 18328 18329 18330 18331 18332 18333 18334 18335 18336 18337 18338 18339 18340 18341 18342 18343 18344 18345 18346 18347 18348 18349 18350 18351 18352 18353 18354 18355 18356 18357 18358 18359 18360 18361 18362 18363 18364 18365 18366 18367 18368 18369 18370 18371 18372 18373 18374 18375 18376 18377 18378 18379 18380 18381 18382 18383 18384 18385 18386 18387 18388 18389 18390 18391 18392 18393 18394 18395 18396 18397 18398 18399 18400 18401 18402 18403 18404 18405 18406 18407 18408 18409 18410 18411 18412 18413 18414 18415 18416 18417 18418 18419 18420 18421 18422 18423 18424 18425 18426 18427 18428 18429 18430 18431 18432 18433 18434 18435 18436 18437 18438 18439 18440 18441 18442 18443 18444 18445 18446 18447 18448 18449 18450 18451 18452 18453 18454 18455 18456 18457 18458 18459 18460 18461 18462 18463 18464 18465 18466 18467 18468 18469 18470 18471 18472 18473 18474 18475 18476 18477 18478 18479 18480 18481 18482 18483 18484 18485 18486 18487 18488 18489 18490 18491 18492 18493 18494 18495 18496 18497 18498 18499 18500 18501 18502 18503 18504 18505 18506 18507 18508 18509 18510 18511 18512 18513 18514 18515 18516 18517 18518 18519 18520 18521 18522 18523 18524 18525 18526 18527 18528 18529 18530 18531 18532 18533 18534 18535 18536 18537 18538 18539 18540 18541 18542 18543 18544 18545 18546 18547 18548 18549 18550 18551 18552 18553 18554 18555 18556 18557 18558 18559 18560 18561 18562 18563 18564 18565 18566 18567 18568 18569 18570 18571 18572 18573 18574 18575 18576 18577 18578 18579 18580 18581 18582 18583 18584 18585 18586 18587 18588 18589 18590 18591 18592 18593 18594 18595 18596 18597 18598 18599 18600 18601 18602 18603 18604 18605 18606 18607 18608 18609 18610 18611 18612 18613 18614 18615 18616 18617 18618 18619 18620 18621 18622 18623 18624 18625 18626 18627 18628 18629 18630 18631 18632 18633 18634 18635 18636 18637 18638 18639 18640 18641 18642 18643 18644 18645 18646 18647 18648 18649 18650 18651 18652 18653 18654 18655 18656 18657 18658 18659 18660 18661 18662 18663 18664 18665 18666 18667 18668 18669 18670 18671 18672 18673 18674 18675 18676 18677 18678 18679 18680 18681 18682 18683 18684 18685 18686 18687 18688 18689 18690 18691 18692 18693 18694 18695 18696 18697 18698 18699 18700 18701 18702 18703 18704 18705 18706 18707 18708 18709 18710 18711 18712 18713 18714 18715 18716 18717 18718 18719 18720 18721 18722 18723 18724 18725 18726 18727 18728 18729 18730 18731 18732 18733 18734 18735 18736 18737 18738 18739 18740 18741 18742 18743 18744 18745 18746 18747 18748 18749 18750 18751 18752 18753 18754 18755 18756 18757 18758 18759 18760 18761 18762 18763 18764 18765 18766 18767 18768 18769 18770 18771 18772 18773 18774 18775 18776 18777 18778 18779 18780 18781 18782 18783 18784 18785 18786 18787 18788 18789 18790 18791 18792 18793 18794 18795 18796 18797 18798 18799 18800 18801 18802 18803 18804 18805 18806 18807 18808 18809 18810 18811 18812 18813 18814 18815 18816 18817 18818 18819 18820 18821 18822 18823 18824 18825 18826 18827 18828 18829 18830 18831 18832 18833 18834 18835 18836 18837 18838 18839 18840 18841 18842 18843 18844 18845 18846 18847 18848 18849 18850 18851 18852 18853 18854 18855 18856 18857 18858 18859 18860 18861 18862 18863 18864 18865 18866 18867 18868 18869 18870 18871 18872 18873 18874 18875 18876 18877 18878 18879 18880 18881 18882 18883 18884 18885 18886 18887 18888 18889 18890 18891 18892 18893 18894 18895 18896 18897 18898 18899 18900 18901 18902 18903 18904 18905 18906 18907 18908 18909 18910 18911 18912 18913 18914 18915 18916 18917 18918 18919 18920 18921 18922 18923 18924 18925 18926 18927 18928 18929 18930 18931 18932 18933 18934 18935 18936 18937 18938 18939 18940 18941 18942 18943 18944 18945 18946 18947 18948 18949 18950 18951 18952 18953 18954 18955 18956 18957 18958 18959 18960 18961 18962 18963 18964 18965 18966 18967 18968 18969 18970 18971 18972 18973 18974 18975 18976 18977 18978 18979 18980 18981 18982 18983 18984 18985 18986 18987 18988 18989 18990 18991 18992 18993 18994 18995 18996 18997 18998 18999 19000 19001 19002 19003 19004 19005 19006 19007 19008 19009 19010 19011 19012 19013 19014 19015 19016 19017 19018 19019 19020 19021 19022 19023 19024 19025 19026 19027 19028 19029 19030 19031 19032 19033 19034 19035 19036 19037 19038 19039 19040 19041 19042 19043 19044 19045 19046 19047 19048 19049 19050 19051 19052 19053 19054 19055 19056 19057 19058 19059 19060 19061 19062 19063 19064 19065 19066 19067 19068 19069 19070 19071 19072 19073 19074 19075 19076 19077 19078 19079 19080 19081 19082 19083 19084 19085 19086 19087 19088 19089 19090 19091 19092 19093 19094 19095 19096 19097 19098 19099 19100 19101 19102 19103 19104 19105 19106 19107 19108 19109 19110 19111 19112 19113 19114 19115 19116 19117 19118 19119 19120 19121 19122 19123 19124 19125 19126 19127 19128 19129 19130 19131 19132 19133 19134 19135 19136 19137 19138 19139 19140 19141 19142 19143 19144 19145 19146 19147 19148 19149 19150 19151 19152 19153 19154 19155 19156 19157 19158 19159 19160 19161 19162 19163 19164 19165 19166 19167 19168 19169 19170 19171 19172 19173 19174 19175 19176 19177 19178 19179 19180 19181 19182 19183 19184 19185 19186 19187 19188 19189 19190 19191 19192 19193 19194 19195 19196 19197 19198 19199 19200 19201 19202 19203 19204 19205 19206 19207 19208 19209 19210 19211 19212 19213 19214 19215 19216 19217 19218 19219 19220 19221 19222 19223 19224 19225 19226 19227 19228 19229 19230 19231 19232 19233 19234 19235 19236 19237 19238 19239 19240 19241 19242 19243 19244 19245 19246 19247 19248 19249 19250 19251 19252 19253 19254 19255 19256 19257 19258 19259 19260 19261 19262 19263 19264 19265 19266 19267 19268 19269 19270 19271 19272 19273 19274 19275 19276 19277 19278 19279 19280 19281 19282 19283 19284 19285 19286 19287 19288 19289 19290 19291 19292 19293 19294 19295 19296 19297 19298 19299 19300 19301 19302 19303 19304 19305 19306 19307 19308 19309 19310 19311 19312 19313 19314 19315 19316 19317 19318 19319 19320 19321 19322 19323 19324 19325 19326 19327 19328 19329 19330 19331 19332 19333 19334 19335 19336 19337 19338 19339 19340 19341 19342 19343 19344 19345 19346 19347 19348 19349 19350 19351 19352 19353 19354 19355 19356 19357 19358 19359 19360 19361 19362 19363 19364 19365 19366 19367 19368 19369 19370 19371 19372 19373 19374 19375 19376 19377 19378 19379 19380 19381 19382 19383 19384 19385 19386 19387 19388 19389 19390 19391 19392 19393 19394 19395 19396 19397 19398 19399 19400 19401 19402 19403 19404 19405 19406 19407 19408 19409 19410 19411 19412 19413 19414 19415 19416 19417 19418 19419 19420 19421 19422 19423 19424 19425 19426 19427 19428 19429 19430 19431 19432 19433 19434 19435 19436 19437 19438 19439 19440 19441 19442 19443 19444 19445 19446 19447 19448 19449 19450 19451 19452 19453 19454 19455 19456 19457 19458 19459 19460 19461 19462 19463 19464 19465 19466 19467 19468 19469 19470 19471 19472 19473 19474 19475 19476 19477 19478 19479 19480 19481 19482 19483 19484 19485 19486 19487 19488 19489 19490 19491 19492 19493 19494 19495 19496 19497 19498 19499 19500 19501 19502 19503 19504 19505 19506 19507 19508 19509 19510 19511 19512 19513 19514 19515 19516 19517 19518 19519 19520 19521 19522 19523 19524 19525 19526 19527 19528 19529 19530 19531 19532 19533 19534 19535 19536 19537 19538 19539 19540 19541 19542 19543 19544 19545 19546 19547 19548 19549 19550 19551 19552 19553 19554 19555 19556 19557 19558 19559 19560 19561 19562 19563 19564 19565 19566 19567 19568 19569 19570 19571 19572 19573 19574 19575 19576 19577 19578 19579 19580 19581 19582 19583 19584 19585 19586 19587 19588 19589 19590 19591 19592 19593 19594 19595 19596 19597 19598 19599 19600 19601 19602 19603 19604 19605 19606 19607 19608 19609 19610 19611 19612 19613 19614 19615 19616 19617 19618 19619 19620 19621 19622 19623 19624 19625 19626 19627 19628 19629 19630 19631 19632 19633 19634 19635 19636 19637 19638 19639 19640 19641 19642 19643 19644 19645 19646 19647 19648 19649 19650 19651 19652 19653 19654 19655 19656 19657 19658 19659 19660 19661 19662 19663 19664 19665 19666 19667 19668 19669 19670 19671 19672 19673 19674 19675 19676 19677 19678 19679 19680 19681 19682 19683 19684 19685 19686 19687 19688 19689 19690 19691 19692 19693 19694 19695 19696 19697 19698 19699 19700 19701 19702 19703 19704 19705 19706 19707 19708 19709 19710 19711 19712 19713 19714 19715 19716 19717 19718 19719 19720 19721 19722 19723 19724 19725 19726 19727 19728 19729 19730 19731 19732 19733 19734 19735 19736 19737 19738 19739 19740 19741 19742 19743 19744 19745 19746 19747 19748 19749 19750 19751 19752 19753 19754 19755 19756 19757 19758 19759 19760 19761 19762 19763 19764 19765 19766 19767 19768 19769 19770 19771 19772 19773 19774 19775 19776 19777 19778 19779 19780 19781 19782 19783 19784 19785 19786 19787 19788 19789 19790 19791 19792 19793 19794 19795 19796 19797 19798 19799 19800 19801 19802 19803 19804 19805 19806 19807 19808 19809 19810 19811 19812 19813 19814 19815 19816 19817 19818 19819 19820 19821 19822 19823 19824 19825 19826 19827 19828 19829 19830 19831 19832 19833 19834 19835 19836 19837 19838 19839 19840 19841 19842 19843 19844 19845 19846 19847 19848 19849 19850 19851 19852 19853 19854 19855 19856 19857 19858 19859 19860 19861 19862 19863 19864 19865 19866 19867 19868 19869 19870 19871 19872 19873 19874 19875 19876 19877 19878 19879 19880 19881 19882 19883 19884 19885 19886 19887 19888 19889 19890 19891 19892 19893 19894 19895 19896 19897 19898 19899 19900 19901 19902 19903 19904 19905 19906 19907 19908 19909 19910 19911 19912 19913 19914 19915 19916 19917 19918 19919 19920 19921 19922 19923 19924 19925 19926 19927 19928 19929 19930 19931 19932 19933 19934 19935 19936 19937 19938 19939 19940 19941 19942 19943 19944 19945 19946 19947 19948 19949 19950 19951 19952 19953 19954 19955 19956 19957 19958 19959 19960 19961 19962 19963 19964 19965 19966 19967 19968 19969 19970 19971 19972 19973 19974 19975 19976 19977 19978 19979 19980 19981 19982 19983 19984 19985 19986 19987 19988 19989 19990 19991 19992 19993 19994 19995 19996 19997 19998 19999 20000 20001 20002 20003 20004 20005 20006 20007 20008 20009 20010 20011 20012 20013 20014 20015 20016 20017 20018 20019 20020 20021 20022 20023 20024 20025 20026 20027 20028 20029 20030 20031 20032 20033 20034 20035 20036 20037 20038 20039 20040 20041 20042 20043 20044 20045 20046 20047 20048 20049 20050 20051 20052 20053 20054 20055 20056 20057 20058 20059 20060 20061 20062 20063 20064 20065 20066 20067 20068 20069 20070 20071 20072 20073 20074 20075 20076 20077 20078 20079 20080 20081 20082 20083 20084 20085 20086 20087 20088 20089 20090 20091 20092 20093 20094 20095 20096 20097 20098 20099 20100 20101 20102 20103 20104 20105 20106 20107 20108 20109 20110 20111 20112 20113 20114 20115 20116 20117 20118 20119 20120 20121 20122 20123 20124 20125 20126 20127 20128 20129 20130 20131 20132 20133 20134 20135 20136 20137 20138 20139 20140 20141 20142 20143 20144 20145 20146 20147 20148 20149 20150 20151 20152 20153 20154 20155 20156 20157 20158 20159 20160 20161 20162 20163 20164 20165 20166 20167 20168 20169 20170 20171 20172 20173 20174 20175 20176 20177 20178 20179 20180 20181 20182 20183 20184 20185 20186 20187 20188 20189 20190 20191 20192 20193 20194 20195 20196 20197 20198 20199 20200 20201 20202 20203 20204 20205 20206 20207 20208 20209 20210 20211 20212 20213 20214 20215 20216 20217 20218 20219 20220 20221 20222 20223 20224 20225 20226 20227 20228 20229 20230 20231 20232 20233 20234 20235 20236 20237 20238 20239 20240 20241 20242 20243 20244 20245 20246 20247 20248 20249 20250 20251 20252 20253 20254 20255 20256 20257 20258 20259 20260 20261 20262 20263 20264 20265 20266 20267 20268 20269 20270 20271 20272 20273 20274 20275 20276 20277 20278 20279 20280 20281 20282 20283 20284 20285 20286 20287 20288 20289 20290 20291 20292 20293 20294 20295 20296 20297 20298 20299 20300 20301 20302 20303 20304 20305 20306 20307 20308 20309 20310 20311 20312 20313 20314 20315 20316 20317 20318 20319 20320 20321 20322 20323 20324 20325 20326 20327 20328 20329 20330 20331 20332 20333 20334 20335 20336 20337 20338 20339 20340 20341 20342 20343 20344 20345 20346 20347 20348 20349 20350 20351 20352 20353 20354 20355 20356 20357 20358 20359 20360 20361 20362 20363 20364 20365 20366 20367 20368 20369 20370 20371 20372 20373 20374 20375 20376 20377 20378 20379 20380 20381 20382 20383 20384 20385 20386 20387 20388 20389 20390 20391 20392 20393 20394 20395 20396 20397 20398 20399 20400 20401 20402 20403 20404 20405 20406 20407 20408 20409 20410 20411 20412 20413 20414 20415 20416 20417 20418 20419 20420 20421 20422 20423 20424 20425 20426 20427 20428 20429 20430 20431 20432 20433 20434 20435 20436 20437 20438 20439 20440 20441 20442 20443 20444 20445 20446 20447 20448 20449 20450 20451 20452 20453 20454 20455 20456 20457 20458 20459 20460 20461 20462 20463 20464 20465 20466 20467 20468 20469 20470 20471 20472 20473 20474 20475 20476 20477 20478 20479 20480 20481 20482 20483 20484 20485 20486 20487 20488 20489 20490 20491 20492 20493 20494 20495 20496 20497 20498 20499 20500 20501 20502 20503 20504 20505 20506 20507 20508 20509 20510 20511 20512 20513 20514 20515 20516 20517 20518 20519 20520 20521 20522 20523 20524 20525 20526 20527 20528 20529 20530 20531 20532 20533 20534 20535 20536 20537 20538 20539 20540 20541 20542 20543 20544 20545 20546 20547 20548 20549 20550 20551 20552 20553 20554 20555 20556 20557 20558 20559 20560 20561 20562 20563 20564 20565 20566 20567 20568 20569 20570 20571 20572 20573 20574 20575 20576 20577 20578 20579 20580 20581 20582 20583 20584 20585 20586 20587 20588 20589 20590 20591 20592 20593 20594 20595 20596 20597 20598 20599 20600 20601 20602 20603 20604 20605 20606 20607 20608 20609 20610 20611 20612 20613 20614 20615 20616 20617 20618 20619 20620 20621 20622 20623 20624 20625 20626 20627 20628 20629 20630 20631 20632 20633 20634 20635 20636 20637 20638 20639 20640 20641 20642 20643 20644 20645 20646 20647 20648 20649 20650 20651 20652 20653 20654 20655 20656 20657 20658 20659 20660 20661 20662 20663 20664 20665 20666 20667 20668 20669 20670 20671 20672 20673 20674 20675 20676 20677 20678 20679 20680 20681 20682 20683 20684 20685 20686 20687 20688 20689 20690 20691 20692 20693 20694 20695 20696 20697 20698 20699 20700 20701 20702 20703 20704 20705 20706 20707 20708 20709 20710 20711 20712 20713 20714 20715 20716 20717 20718 20719 20720 20721 20722 20723 20724 20725 20726 20727 20728 20729 20730 20731 20732 20733 20734 20735 20736 20737 20738 20739 20740 20741 20742 20743 20744 20745 20746 20747 20748 20749 20750 20751 20752 20753 20754 20755 20756 20757 20758 20759 20760 20761 20762 20763 20764 20765 20766 20767 20768 20769 20770 20771 20772 20773 20774 20775 20776 20777 20778 20779 20780 20781 20782 20783 20784 20785 20786 20787 20788 20789 20790 20791 20792 20793 20794 20795 20796 20797 20798 20799 20800 20801 20802 20803 20804 20805 20806 20807 20808 20809 20810 20811 20812 20813 20814 20815 20816 20817 20818 20819 20820 20821 20822 20823 20824 20825 20826 20827 20828 20829 20830 20831 20832 20833 20834 20835 20836 20837 20838 20839 20840 20841 20842 20843 20844 20845 20846 20847 20848 20849 20850 20851 20852 20853 20854 20855 20856 20857 20858 20859 20860 20861 20862 20863 20864 20865 20866 20867 20868 20869 20870 20871 20872 20873 20874 20875 20876 20877 20878 20879 20880 20881 20882 20883 20884 20885 20886 20887 20888 20889 20890 20891 20892 20893 20894 20895 20896 20897 20898 20899 20900 20901 20902 20903 20904 20905 20906 20907 20908 20909 20910 20911 20912 20913 20914 20915 20916 20917 20918 20919 20920 20921 20922 20923 20924 20925 20926 20927 20928 20929 20930 20931 20932 20933 20934 20935 20936 20937 20938 20939 20940 20941 20942 20943 20944 20945 20946 20947 20948 20949 20950 20951 20952 20953 20954 20955 20956 20957 20958 20959 20960 20961 20962 20963 20964 20965 20966 20967 20968 20969 20970 20971 20972 20973 20974 20975 20976 20977 20978 20979 20980 20981 20982 20983 20984 20985 20986 20987 20988 20989 20990 20991 20992 20993 20994 20995 20996 20997 20998 20999 21000 21001 21002 21003 21004 21005 21006 21007 21008 21009 21010 21011 21012 21013 21014 21015 21016 21017 21018 21019 21020 21021 21022 21023 21024 21025 21026 21027 21028 21029 21030 21031 21032 21033 21034 21035 21036 21037 21038 21039 21040 21041 21042 21043 21044 21045 21046 21047 21048 21049 21050 21051 21052 21053 21054 21055 21056 21057 21058 21059 21060 21061 21062 21063 21064 21065 21066 21067 21068 21069 21070 21071 21072 21073 21074 21075 21076 21077 21078 21079 21080 21081 21082 21083 21084 21085 21086 21087 21088 21089 21090 21091 21092 21093 21094 21095 21096 21097 21098 21099 21100 21101 21102 21103 21104 21105 21106 21107 21108 21109 21110 21111 21112 21113 21114 21115 21116 21117 21118 21119 21120 21121 21122 21123 21124 21125 21126 21127 21128 21129 21130 21131 21132 21133 21134 21135 21136 21137 21138 21139 21140 21141 21142 21143 21144 21145 21146 21147 21148 21149 21150 21151 21152 21153 21154 21155 21156 21157 21158 21159 21160 21161 21162 21163 21164 21165 21166 21167 21168 21169 21170 21171 21172 21173 21174 21175 21176 21177 21178 21179 21180 21181 21182 21183 21184 21185 21186 21187 21188 21189 21190 21191 21192 21193 21194 21195 21196 21197 21198 21199 21200 21201 21202 21203 21204 21205 21206 21207 21208 21209 21210 21211 21212 21213 21214 21215 21216 21217 21218 21219 21220 21221 21222 21223 21224 21225 21226 21227 21228 21229 21230 21231 21232 21233 21234 21235 21236 21237 21238 21239 21240 21241 21242 21243 21244 21245 21246 21247 21248 21249 21250 21251 21252 21253 21254 21255 21256 21257 21258 21259 21260 21261 21262 21263 21264 21265 21266 21267 21268 21269 21270 21271 21272 21273 21274 21275 21276 21277 21278 21279 21280 21281 21282 21283 21284 21285 21286 21287 21288 21289 21290 21291 21292 21293 21294 21295 21296 21297 21298 21299 21300 21301 21302 21303 21304 21305 21306 21307 21308 21309 21310 21311 21312 21313 21314 21315 21316 21317 21318 21319 21320 21321 21322 21323 21324 21325 21326 21327 21328 21329 21330 21331 21332 21333 21334 21335 21336 21337 21338 21339 21340 21341 21342 21343 21344 21345 21346 21347 21348 21349 21350 21351 21352 21353 21354 21355 21356 21357 21358 21359 21360 21361 21362 21363 21364 21365 21366 21367 21368 21369 21370 21371 21372 21373 21374 21375 21376 21377 21378 21379 21380 21381 21382 21383 21384 21385 21386 21387 21388 21389 21390 21391 21392 21393 21394 21395 21396 21397 21398 21399 21400 21401 21402 21403 21404 21405 21406 21407 21408 21409 21410 21411 21412 21413 21414 21415 21416 21417 21418 21419 21420 21421 21422 21423 21424 21425 21426 21427 21428 21429 21430 21431 21432 21433 21434 21435 21436 21437 21438 21439 21440 21441 21442 21443 21444 21445 21446 21447 21448 21449 21450 21451 21452 21453 21454 21455 21456 21457 21458 21459 21460 21461 21462 21463 21464 21465 21466 21467 21468 21469 21470 21471 21472 21473 21474 21475 21476 21477 21478 21479 21480 21481 21482 21483 21484 21485 21486 21487 21488 21489 21490 21491 21492 21493 21494 21495 21496 21497 21498 21499 21500 21501 21502 21503 21504 21505 21506 21507 21508 21509 21510 21511 21512 21513 21514 21515 21516 21517 21518 21519 21520 21521 21522 21523 21524 21525 21526 21527 21528 21529 21530 21531 21532 21533 21534 21535 21536 21537 21538 21539 21540 21541 21542 21543 21544 21545 21546 21547 21548 21549 21550 21551 21552 21553 21554 21555 21556 21557 21558 21559 21560 21561 21562 21563 21564 21565 21566 21567 21568 21569 21570 21571 21572 21573 21574 21575 21576 21577 21578 21579 21580 21581 21582 21583 21584 21585 21586 21587 21588 21589 21590 21591 21592 21593 21594 21595 21596 21597 21598 21599 21600 21601 21602 21603 21604 21605 21606 21607 21608 21609 21610 21611 21612 21613 21614 21615 21616 21617 21618 21619 21620 21621 21622 21623 21624 21625 21626 21627 21628 21629 21630 21631 21632 21633 21634 21635 21636 21637 21638 21639 21640 21641 21642 21643 21644 21645 21646 21647 21648 21649 21650 21651 21652 21653 21654 21655 21656 21657 21658 21659 21660 21661 21662 21663 21664 21665 21666 21667 21668 21669 21670 21671 21672 21673 21674 21675 21676 21677 21678 21679 21680 21681 21682 21683 21684 21685 21686 21687 21688 21689 21690 21691 21692 21693 21694 21695 21696 21697 21698 21699 21700 21701 21702 21703 21704 21705 21706 21707 21708 21709 21710 21711 21712 21713 21714 21715 21716 21717 21718 21719 21720 21721 21722 21723 21724 21725 21726 21727 21728 21729 21730 21731 21732 21733 21734 21735 21736 21737 21738 21739 21740 21741 21742 21743 21744 21745 21746 21747 21748 21749 21750 21751 21752 21753 21754 21755 21756 21757 21758 21759 21760 21761 21762 21763 21764 21765 21766 21767 21768 21769 21770 21771 21772 21773 21774 21775 21776 21777 21778 21779 21780 21781 21782 21783 21784 21785 21786 21787 21788 21789 21790 21791 21792 21793 21794 21795 21796 21797 21798 21799 21800 21801 21802 21803 21804 21805 21806 21807 21808 21809 21810 21811 21812 21813 21814 21815 21816 21817 21818 21819 21820 21821 21822 21823 21824 21825 21826 21827 21828 21829 21830 21831 21832 21833 21834 21835 21836 21837 21838 21839 21840 21841 21842 21843 21844 21845 21846 21847 21848 21849 21850 21851 21852 21853 21854 21855 21856 21857 21858 21859 21860 21861 21862 21863 21864 21865 21866 21867 21868 21869 21870 21871 21872 21873 21874 21875 21876 21877 21878 21879 21880 21881 21882 21883 21884 21885 21886 21887 21888 21889 21890 21891 21892 21893 21894 21895 21896 21897 21898 21899 21900 21901 21902 21903 21904 21905 21906 21907 21908 21909 21910 21911 21912 21913 21914 21915 21916 21917 21918 21919 21920 21921 21922 21923 21924 21925 21926 21927 21928 21929 21930 21931 21932 21933 21934 21935 21936 21937 21938 21939 21940 21941 21942 21943 21944 21945 21946 21947 21948 21949 21950 21951 21952 21953 21954 21955 21956 21957 21958 21959 21960 21961 21962 21963 21964 21965 21966 21967 21968 21969 21970 21971 21972 21973 21974 21975 21976 21977 21978 21979 21980 21981 21982 21983 21984 21985 21986 21987 21988 21989 21990 21991 21992 21993 21994 21995 21996 21997 21998 21999 22000 22001 22002 22003 22004 22005 22006 22007 22008 22009 22010 22011 22012 22013 22014 22015 22016 22017 22018 22019 22020 22021 22022 22023 22024 22025 22026 22027 22028 22029 22030 22031 22032 22033 22034 22035 22036 22037 22038 22039 22040 22041 22042 22043 22044 22045 22046 22047 22048 22049 22050 22051 22052 22053 22054 22055 22056 22057 22058 22059 22060 22061 22062 22063 22064 22065 22066 22067 22068 22069 22070 22071 22072 22073 22074 22075 22076 22077 22078 22079 22080 22081 22082 22083 22084 22085 22086 22087 22088 22089 22090 22091 22092 22093 22094 22095 22096 22097 22098 22099 22100 22101 22102 22103 22104 22105 22106 22107 22108 22109 22110 22111 22112 22113 22114 22115 22116 22117 22118 22119 22120 22121 22122 22123 22124 22125 22126 22127 22128 22129 22130 22131 22132 22133 22134 22135 22136 22137 22138 22139 22140 22141 22142 22143 22144 22145 22146 22147 22148 22149 22150 22151 22152 22153 22154 22155 22156 22157 22158 22159 22160 22161 22162 22163 22164 22165 22166 22167 22168 22169 22170 22171 22172 22173 22174 22175 22176 22177 22178 22179 22180 22181 22182 22183 22184 22185 22186 22187 22188 22189 22190 22191 22192 22193 22194 22195 22196 22197 22198 22199 22200 22201 22202 22203 22204 22205 22206 22207 22208 22209 22210 22211 22212 22213 22214 22215 22216 22217 22218 22219 22220 22221 22222 22223 22224 22225 22226 22227 22228 22229 22230 22231 22232 22233 22234 22235 22236 22237 22238 22239 22240 22241 22242 22243 22244 22245 22246 22247 22248 22249 22250 22251 22252 22253 22254 22255 22256 22257 22258 22259 22260 22261 22262 22263 22264 22265 22266 22267 22268 22269 22270 22271 22272 22273 22274 22275 22276 22277 22278 22279 22280 22281 22282 22283 22284 22285 22286 22287 22288 22289 22290 22291 22292 22293 22294 22295 22296 22297 22298 22299 22300 22301 22302 22303 22304 22305 22306 22307 22308 22309 22310 22311 22312 22313 22314 22315 22316 22317 22318 22319 22320 22321 22322 22323 22324 22325 22326 22327 22328 22329 22330 22331 22332 22333 22334 22335 22336 22337 22338 22339 22340 22341 22342 22343 22344 22345 22346 22347 22348 22349 22350 22351 22352 22353 22354 22355 22356 22357 22358 22359 22360 22361 22362 22363 22364 22365 22366 22367 22368 22369 22370 22371 22372 22373 22374 22375 22376 22377 22378 22379 22380 22381 22382 22383 22384 22385 22386 22387 22388 22389 22390 22391 22392 22393 22394 22395 22396 22397 22398 22399 22400 22401 22402 22403 22404 22405 22406 22407 22408 22409 22410 22411 22412 22413 22414 22415 22416 22417 22418 22419 22420 22421 22422 22423 22424 22425 22426 22427 22428 22429 22430 22431 22432 22433 22434 22435 22436 22437 22438 22439 22440 22441 22442 22443 22444 22445 22446 22447 22448 22449 22450 22451 22452 22453 22454 22455 22456 22457 22458 22459 22460 22461 22462 22463 22464 22465 22466 22467 22468 22469 22470 22471 22472 22473 22474 22475 22476 22477 22478 22479 22480 22481 22482 22483 22484 22485 22486 22487 22488 22489 22490 22491 22492 22493 22494 22495 22496 22497 22498 22499 22500 22501 22502 22503 22504 22505 22506 22507 22508 22509 22510 22511 22512 22513 22514 22515 22516 22517 22518 22519 22520 22521 22522 22523 22524 22525 22526 22527 22528 22529 22530 22531 22532 22533 22534 22535 22536 22537 22538 22539 22540 22541 22542 22543 22544 22545 22546 22547 22548 22549 22550 22551 22552 22553 22554 22555 22556 22557 22558 22559 22560 22561 22562 22563 22564 22565 22566 22567 22568 22569 22570 22571 22572 22573 22574 22575 22576 22577 22578 22579 22580 22581 22582 22583 22584 22585 22586 22587 22588 22589 22590 22591 22592 22593 22594 22595 22596 22597 22598 22599 22600 22601 22602 22603 22604 22605 22606 22607 22608 22609 22610 22611 22612 22613 22614 22615 22616 22617 22618 22619 22620 22621 22622 22623 22624 22625 22626 22627 22628 22629 22630 22631 22632 22633 22634 22635 22636 22637 22638 22639 22640 22641 22642 22643 22644 22645 22646 22647 22648 22649 22650 22651 22652 22653 22654 22655 22656 22657 22658 22659 22660 22661 22662 22663 22664 22665 22666 22667 22668 22669 22670 22671 22672 22673 22674 22675 22676 22677 22678 22679 22680 22681 22682 22683 22684 22685 22686 22687 22688 22689 22690 22691 22692 22693 22694 22695 22696 22697 22698 22699 22700 22701 22702 22703 22704 22705 22706 22707 22708 22709 22710 22711 22712 22713 22714 22715 22716 22717 22718 22719 22720 22721 22722 22723 22724 22725 22726 22727 22728 22729 22730 22731 22732 22733 22734 22735 22736 22737 22738 22739 22740 22741 22742 22743 22744 22745 22746 22747 22748 22749 22750 22751 22752 22753 22754 22755 22756 22757 22758 22759 22760 22761 22762 22763 22764 22765 22766 22767 22768 22769 22770 22771 22772 22773 22774 22775 22776 22777 22778 22779 22780 22781 22782 22783 22784 22785 22786 22787 22788 22789 22790 22791 22792 22793 22794 22795 22796 22797 22798 22799 22800 22801 22802 22803 22804 22805 22806 22807 22808 22809 22810 22811 22812 22813 22814 22815 22816 22817 22818 22819 22820 22821 22822 22823 22824 22825 22826 22827 22828 22829 22830 22831 22832 22833 22834 22835 22836 22837 22838 22839 22840 22841 22842 22843 22844 22845 22846 22847 22848 22849 22850 22851 22852 22853 22854 22855 22856 22857 22858 22859 22860 22861 22862 22863 22864 22865 22866 22867 22868 22869 22870 22871 22872 22873 22874 22875 22876 22877 22878 22879 22880 22881 22882 22883 22884 22885 22886 22887 22888 22889 22890 22891 22892 22893 22894 22895 22896 22897 22898 22899 22900 22901 22902 22903 22904 22905 22906 22907 22908 22909 22910 22911 22912 22913 22914 22915 22916 22917 22918 22919 22920 22921 22922 22923 22924 22925 22926 22927 22928 22929 22930 22931 22932 22933 22934 22935 22936 22937 22938 22939 22940 22941 22942 22943 22944 22945 22946 22947 22948 22949 22950 22951 22952 22953 22954 22955 22956 22957 22958 22959 22960 22961 22962 22963 22964 22965 22966 22967 22968 22969 22970 22971 22972 22973 22974 22975 22976 22977 22978 22979 22980 22981 22982 22983 22984 22985 22986 22987 22988 22989 22990 22991 22992 22993 22994 22995 22996 22997 22998 22999 23000 23001 23002 23003 23004 23005 23006 23007 23008 23009 23010 23011 23012 23013 23014 23015 23016 23017 23018 23019 23020 23021 23022 23023 23024 23025 23026 23027 23028 23029 23030 23031 23032 23033 23034 23035 23036 23037 23038 23039 23040 23041 23042 23043 23044 23045 23046 23047 23048 23049 23050 23051 23052 23053 23054 23055 23056 23057 23058 23059 23060 23061 23062 23063 23064 23065 23066 23067 23068 23069 23070 23071 23072 23073 23074 23075 23076 23077 23078 23079 23080 23081 23082 23083 23084 23085 23086 23087 23088 23089 23090 23091 23092 23093 23094 23095 23096 23097 23098 23099 23100 23101 23102 23103 23104 23105 23106 23107 23108 23109 23110 23111 23112 23113 23114 23115 23116 23117 23118 23119 23120 23121 23122 23123 23124 23125 23126 23127 23128 23129 23130 23131 23132 23133 23134 23135 23136 23137 23138 23139 23140 23141 23142 23143 23144 23145 23146 23147 23148 23149 23150 23151 23152 23153 23154 23155 23156 23157 23158 23159 23160 23161 23162 23163 23164 23165 23166 23167 23168 23169 23170 23171 23172 23173 23174 23175 23176 23177 23178 23179 23180 23181 23182 23183 23184 23185 23186 23187 23188 23189 23190 23191 23192 23193 23194 23195 23196 23197 23198 23199 23200 23201 23202 23203 23204 23205 23206 23207 23208 23209 23210 23211 23212 23213 23214 23215 23216 23217 23218 23219 23220 23221 23222 23223 23224 23225 23226 23227 23228 23229 23230 23231 23232 23233 23234 23235 23236 23237 23238 23239 23240 23241 23242 23243 23244 23245 23246 23247 23248 23249 23250 23251 23252 23253 23254 23255 23256 23257 23258 23259 23260 23261 23262 23263 23264 23265 23266 23267 23268 23269 23270 23271 23272 23273 23274 23275 23276 23277 23278 23279 23280 23281 23282 23283 23284 23285 23286 23287 23288 23289 23290 23291 23292 23293 23294 23295 23296 23297 23298 23299 23300 23301 23302 23303 23304 23305 23306 23307 23308 23309 23310 23311 23312 23313 23314 23315 23316 23317 23318 23319 23320 23321 23322 23323 23324 23325 23326 23327 23328 23329 23330 23331 23332 23333 23334 23335 23336 23337 23338 23339 23340 23341 23342 23343 23344 23345 23346 23347 23348 23349 23350 23351 23352 23353 23354 23355 23356 23357 23358 23359 23360 23361 23362 23363 23364 23365 23366 23367 23368 23369 23370 23371 23372 23373 23374 23375 23376 23377 23378 23379 23380 23381 23382 23383 23384 23385 23386 23387 23388 23389 23390 23391 23392 23393 23394 23395 23396 23397 23398 23399 23400 23401 23402 23403 23404 23405 23406 23407 23408 23409 23410 23411 23412 23413 23414 23415 23416 23417 23418 23419 23420 23421 23422 23423 23424 23425 23426 23427 23428 23429 23430 23431 23432 23433 23434 23435 23436 23437 23438 23439 23440 23441 23442 23443 23444 23445 23446 23447 23448 23449 23450 23451 23452 23453 23454 23455 23456 23457 23458 23459 23460 23461 23462 23463 23464 23465 23466 23467 23468 23469 23470 23471 23472 23473 23474 23475 23476 23477 23478 23479 23480 23481 23482 23483 23484 23485 23486 23487 23488 23489 23490 23491 23492 23493 23494 23495 23496 23497 23498 23499 23500 23501 23502 23503 23504 23505 23506 23507 23508 23509 23510 23511 23512 23513 23514 23515 23516 23517 23518 23519 23520 23521 23522 23523 23524 23525 23526 23527 23528 23529 23530 23531 23532 23533 23534 23535 23536 23537 23538 23539 23540 23541 23542 23543 23544 23545 23546 23547 23548 23549 23550 23551 23552 23553 23554 23555 23556 23557 23558 23559 23560 23561 23562 23563 23564 23565 23566 23567 23568 23569 23570 23571 23572 23573 23574 23575 23576 23577 23578 23579 23580 23581 23582 23583 23584 23585 23586 23587 23588 23589 23590 23591 23592 23593 23594 23595 23596 23597 23598 23599 23600 23601 23602 23603 23604 23605 23606 23607 23608 23609 23610 23611 23612 23613 23614 23615 23616 23617 23618 23619 23620 23621 23622 23623 23624 23625 23626 23627 23628 23629 23630 23631 23632 23633 23634 23635 23636 23637 23638 23639 23640 23641 23642 23643 23644 23645 23646 23647 23648 23649 23650 23651 23652 23653 23654 23655 23656 23657 23658 23659 23660 23661 23662 23663 23664 23665 23666 23667 23668 23669 23670 23671 23672 23673 23674 23675 23676 23677 23678 23679 23680 23681 23682 23683 23684 23685 23686 23687 23688 23689 23690 23691 23692 23693 23694 23695 23696 23697 23698 23699 23700 23701 23702 23703 23704 23705 23706 23707 23708 23709 23710 23711 23712 23713 23714 23715 23716 23717 23718 23719 23720 23721 23722 23723 23724 23725 23726 23727 23728 23729 23730 23731 23732 23733 23734 23735 23736 23737 23738 23739 23740 23741 23742 23743 23744 23745 23746 23747 23748 23749 23750 23751 23752 23753 23754 23755 23756 23757 23758 23759 23760 23761 23762 23763 23764 23765 23766 23767 23768 23769 23770 23771 23772 23773 23774 23775 23776 23777 23778 23779 23780 23781 23782 23783 23784 23785 23786 23787 23788 23789 23790 23791 23792 23793 23794 23795 23796 23797 23798 23799 23800 23801 23802 23803 23804 23805 23806 23807 23808 23809 23810 23811 23812 23813 23814 23815 23816 23817 23818 23819 23820 23821 23822 23823 23824 23825 23826 23827 23828 23829 23830 23831 23832 23833 23834 23835 23836 23837 23838 23839 23840 23841 23842 23843 23844 23845 23846 23847 23848 23849 23850 23851 23852 23853 23854 23855 23856 23857 23858 23859 23860 23861 23862 23863 23864 23865 23866 23867 23868 23869 23870 23871 23872 23873 23874 23875 23876 23877 23878 23879 23880 23881 23882 23883 23884 23885 23886 23887 23888 23889 23890 23891 23892 23893 23894 23895 23896 23897 23898 23899 23900 23901 23902 23903 23904 23905 23906 23907 23908 23909 23910 23911 23912 23913 23914 23915 23916 23917 23918 23919 23920 23921 23922 23923 23924 23925 23926 23927 23928 23929 23930 23931 23932 23933 23934 23935 23936 23937 23938 23939 23940 23941 23942 23943 23944 23945 23946 23947 23948 23949 23950 23951 23952 23953 23954 23955 23956 23957 23958 23959 23960 23961 23962 23963 23964 23965 23966 23967 23968 23969 23970 23971 23972 23973 23974 23975 23976 23977 23978 23979 23980 23981 23982 23983 23984 23985 23986 23987 23988 23989 23990 23991 23992 23993 23994 23995 23996 23997 23998 23999 24000 24001 24002 24003 24004 24005 24006 24007 24008 24009 24010 24011 24012 24013 24014 24015 24016 24017 24018 24019 24020 24021 24022 24023 24024 24025 24026 24027 24028 24029 24030 24031 24032 24033 24034 24035 24036 24037 24038 24039 24040 24041 24042 24043 24044 24045 24046 24047 24048 24049 24050 24051 24052 24053 24054 24055 24056 24057 24058 24059 24060 24061 24062 24063 24064 24065 24066 24067 24068 24069 24070 24071 24072 24073 24074 24075 24076 24077 24078 24079 24080 24081 24082 24083 24084 24085 24086 24087 24088 24089 24090 24091 24092 24093 24094 24095 24096 24097 24098 24099 24100 24101 24102 24103 24104 24105 24106 24107 24108 24109 24110 24111 24112 24113 24114 24115 24116 24117 24118 24119 24120 24121 24122 24123 24124 24125 24126 24127 24128 24129 24130 24131 24132 24133 24134 24135 24136 24137 24138 24139 24140 24141 24142 24143 24144 24145 24146 24147 24148 24149 24150 24151 24152 24153 24154 24155 24156 24157 24158 24159 24160 24161 24162 24163 24164 24165 24166 24167 24168 24169 24170 24171 24172 24173 24174 24175 24176 24177 24178 24179 24180 24181 24182 24183 24184 24185 24186 24187 24188 24189 24190 24191 24192 24193 24194 24195 24196 24197 24198 24199 24200 24201 24202 24203 24204 24205 24206 24207 24208 24209 24210 24211 24212 24213 24214 24215 24216 24217 24218 24219 24220 24221 24222 24223 24224 24225 24226 24227 24228 24229 24230 24231 24232 24233 24234 24235 24236 24237 24238 24239 24240 24241 24242 24243 24244 24245 24246 24247 24248 24249 24250 24251 24252 24253 24254 24255 24256 24257 24258 24259 24260 24261 24262 24263 24264 24265 24266 24267 24268 24269 24270 24271 24272 24273 24274 24275 24276 24277 24278 24279 24280 24281 24282 24283 24284 24285 24286 24287 24288 24289 24290 24291 24292 24293 24294 24295 24296 24297 24298 24299 24300 24301 24302 24303 24304 24305 24306 24307 24308 24309 24310 24311 24312 24313 24314 24315 24316 24317 24318 24319 24320 24321 24322 24323 24324 24325 24326 24327 24328 24329 24330 24331 24332 24333 24334 24335 24336 24337 24338 24339 24340 24341 24342 24343 24344 24345 24346 24347 24348 24349 24350 24351 24352 24353 24354 24355 24356 24357 24358 24359 24360 24361 24362 24363 24364 24365 24366 24367 24368 24369 24370 24371 24372 24373 24374 24375 24376 24377 24378 24379 24380 24381 24382 24383 24384 24385 24386 24387 24388 24389 24390 24391 24392 24393 24394 24395 24396 24397 24398 24399 24400 24401 24402 24403 24404 24405 24406 24407 24408 24409 24410 24411 24412 24413 24414 24415 24416 24417 24418 24419 24420 24421 24422 24423 24424 24425 24426 24427 24428 24429 24430 24431 24432 24433 24434 24435 24436 24437 24438 24439 24440 24441 24442 24443 24444 24445 24446 24447 24448 24449 24450 24451 24452 24453 24454 24455 24456 24457 24458 24459 24460 24461 24462 24463 24464 24465 24466 24467 24468 24469 24470 24471 24472 24473 24474 24475 24476 24477 24478 24479 24480 24481 24482 24483 24484 24485 24486 24487 24488 24489 24490 24491 24492 24493 24494 24495 24496 24497 24498 24499 24500 24501 24502 24503 24504 24505 24506 24507 24508 24509 24510 24511 24512 24513 24514 24515 24516 24517 24518 24519 24520 24521 24522 24523 24524 24525 24526 24527 24528 24529 24530 24531 24532 24533 24534 24535 24536 24537 24538 24539 24540 24541 24542 24543 24544 24545 24546 24547 24548 24549 24550 24551 24552 24553 24554 24555 24556 24557 24558 24559 24560 24561 24562 24563 24564 24565 24566 24567 24568 24569 24570 24571 24572 24573 24574 24575 24576 24577 24578 24579 24580 24581 24582 24583 24584 24585 24586 24587 24588 24589 24590 24591 24592 24593 24594 24595 24596 24597 24598 24599 24600 24601 24602 24603 24604 24605 24606 24607 24608 24609 24610 24611 24612 24613 24614 24615 24616 24617 24618 24619 24620 24621 24622 24623 24624 24625 24626 24627 24628 24629 24630 24631 24632 24633 24634 24635 24636 24637 24638 24639 24640 24641 24642 24643 24644 24645 24646 24647 24648 24649 24650 24651 24652 24653 24654 24655 24656 24657 24658 24659 24660 24661 24662 24663 24664 24665 24666 24667 24668 24669 24670 24671 24672 24673 24674 24675 24676 24677 24678 24679 24680 24681 24682 24683 24684 24685 24686 24687 24688 24689 24690 24691 24692 24693 24694 24695 24696 24697 24698 24699 24700 24701 24702 24703 24704 24705 24706 24707 24708 24709 24710 24711 24712 24713 24714 24715 24716 24717 24718 24719 24720 24721 24722 24723 24724 24725 24726 24727 24728 24729 24730 24731 24732 24733 24734 24735 24736 24737 24738 24739 24740 24741 24742 24743 24744 24745 24746 24747 24748 24749 24750 24751 24752 24753 24754 24755 24756 24757 24758 24759 24760 24761 24762 24763 24764 24765 24766 24767 24768 24769 24770 24771 24772 24773 24774 24775 24776 24777 24778 24779 24780 24781 24782 24783 24784 24785 24786 24787 24788 24789 24790 24791 24792 24793 24794 24795 24796 24797 24798 24799 24800 24801 24802 24803 24804 24805 24806 24807 24808 24809 24810 24811 24812 24813 24814 24815 24816 24817 24818 24819 24820 24821 24822 24823 24824 24825 24826 24827 24828 24829 24830 24831 24832 24833 24834 24835 24836 24837 24838 24839 24840 24841 24842 24843 24844 24845 24846 24847 24848 24849 24850 24851 24852 24853 24854 24855 24856 24857 24858 24859 24860 24861 24862 24863 24864 24865 24866 24867 24868 24869 24870 24871 24872 24873 24874 24875 24876 24877 24878 24879 24880 24881 24882 24883 24884 24885 24886 24887 24888 24889 24890 24891 24892 24893 24894 24895 24896 24897 24898 24899 24900 24901 24902 24903 24904 24905 24906 24907 24908 24909 24910 24911 24912 24913 24914 24915 24916 24917 24918 24919 24920 24921 24922 24923 24924 24925 24926 24927 24928 24929 24930 24931 24932 24933 24934 24935 24936 24937 24938 24939 24940 24941 24942 24943 24944 24945 24946 24947 24948 24949 24950 24951 24952 24953 24954 24955 24956 24957 24958 24959 24960 24961 24962 24963 24964 24965 24966 24967 24968 24969 24970 24971 24972 24973 24974 24975 24976 24977 24978 24979 24980 24981 24982 24983 24984 24985 24986 24987 24988 24989 24990 24991 24992 24993 24994 24995 24996 24997 24998 24999 25000 25001 25002 25003 25004 25005 25006 25007 25008 25009 25010 25011 25012 25013 25014 25015 25016 25017 25018 25019 25020 25021 25022 25023 25024 25025 25026 25027 25028 25029 25030 25031 25032 25033 25034 25035 25036 25037 25038 25039 25040 25041 25042 25043 25044 25045 25046 25047 25048 25049 25050 25051 25052 25053 25054 25055 25056 25057 25058 25059 25060 25061 25062 25063 25064 25065 25066 25067 25068 25069 25070 25071 25072 25073 25074 25075 25076 25077 25078 25079 25080 25081 25082 25083 25084 25085 25086 25087 25088 25089 25090 25091 25092 25093 25094 25095 25096 25097 25098 25099 25100 25101 25102 25103 25104 25105 25106 25107 25108 25109 25110 25111 25112 25113 25114 25115 25116 25117 25118 25119 25120 25121 25122 25123 25124 25125 25126 25127 25128 25129 25130 25131 25132 25133 25134 25135 25136 25137 25138 25139 25140 25141 25142 25143 25144 25145 25146 25147 25148 25149 25150 25151 25152 25153 25154 25155 25156 25157 25158 25159 25160 25161 25162 25163 25164 25165 25166 25167 25168 25169 25170 25171 25172 25173 25174 25175 25176 25177 25178 25179 25180 25181 25182 25183 25184 25185 25186 25187 25188 25189 25190 25191 25192 25193 25194 25195 25196 25197 25198 25199 25200 25201 25202 25203 25204 25205 25206 25207 25208 25209 25210 25211 25212 25213 25214 25215 25216 25217 25218 25219 25220 25221 25222 25223 25224 25225 25226 25227 25228 25229 25230 25231 25232 25233 25234 25235 25236 25237 25238 25239 25240 25241 25242 25243 25244 25245 25246 25247 25248 25249 25250 25251 25252 25253 25254 25255 25256 25257 25258 25259 25260 25261 25262 25263 25264 25265 25266 25267 25268 25269 25270 25271 25272 25273 25274 25275 25276 25277 25278 25279 25280 25281 25282 25283 25284 25285 25286 25287 25288 25289 25290 25291 25292 25293 25294 25295 25296 25297 25298 25299 25300 25301 25302 25303 25304 25305 25306 25307 25308 25309 25310 25311 25312 25313 25314 25315 25316 25317 25318 25319 25320 25321 25322 25323 25324 25325 25326 25327 25328 25329 25330 25331 25332 25333 25334 25335 25336 25337 25338 25339 25340 25341 25342 25343 25344 25345 25346 25347 25348 25349 25350 25351 25352 25353 25354 25355 25356 25357 25358 25359 25360 25361 25362 25363 25364 25365 25366 25367 25368 25369 25370 25371 25372 25373 25374 25375 25376 25377 25378 25379 25380 25381 25382 25383 25384 25385 25386 25387 25388 25389 25390 25391 25392 25393 25394 25395 25396 25397 25398 25399 25400 25401 25402 25403 25404 25405 25406 25407 25408 25409 25410 25411 25412 25413 25414 25415 25416 25417 25418 25419 25420 25421 25422 25423 25424 25425 25426 25427 25428 25429 25430 25431 25432 25433 25434 25435 25436 25437 25438 25439 25440 25441 25442 25443 25444 25445 25446 25447 25448 25449 25450 25451 25452 25453 25454 25455 25456 25457 25458 25459 25460 25461 25462 25463 25464 25465 25466 25467 25468 25469 25470 25471 25472 25473 25474 25475 25476 25477 25478 25479 25480 25481 25482 25483 25484 25485 25486 25487 25488 25489 25490 25491 25492 25493 25494 25495 25496 25497 25498 25499 25500 25501 25502 25503 25504 25505 25506 25507 25508 25509 25510 25511 25512 25513 25514 25515 25516 25517 25518 25519 25520 25521 25522 25523 25524 25525 25526 25527 25528 25529 25530 25531 25532 25533 25534 25535 25536 25537 25538 25539 25540 25541 25542 25543 25544 25545 25546 25547 25548 25549 25550 25551 25552 25553 25554 25555 25556 25557 25558 25559 25560 25561 25562 25563 25564 25565 25566 25567 25568 25569 25570 25571 25572 25573 25574 25575 25576 25577 25578 25579 25580 25581 25582 25583 25584 25585 25586 25587 25588 25589 25590 25591 25592 25593 25594 25595 25596 25597 25598 25599 25600 25601 25602 25603 25604 25605 25606 25607 25608 25609 25610 25611 25612 25613 25614 25615 25616 25617 25618 25619 25620 25621 25622 25623 25624 25625 25626 25627 25628 25629 25630 25631 25632 25633 25634 25635 25636 25637 25638 25639 25640 25641 25642 25643 25644 25645 25646 25647 25648 25649 25650 25651 25652 25653 25654 25655 25656 25657 25658 25659 25660 25661 25662 25663 25664 25665 25666 25667 25668 25669 25670 25671 25672 25673 25674 25675 25676 25677 25678 25679 25680 25681 25682 25683 25684 25685 25686 25687 25688 25689 25690 25691 25692 25693 25694 25695 25696 25697 25698 25699 25700 25701 25702 25703 25704 25705 25706 25707 25708 25709 25710 25711 25712 25713 25714 25715 25716 25717 25718 25719 25720 25721 25722 25723 25724 25725 25726 25727 25728 25729 25730 25731 25732 25733 25734 25735 25736 25737 25738 25739 25740 25741 25742 25743 25744 25745 25746 25747 25748 25749 25750 25751 25752 25753 25754 25755 25756 25757 25758 25759 25760 25761 25762 25763 25764 25765 25766 25767 25768 25769 25770 25771 25772 25773 25774 25775 25776 25777 25778 25779 25780 25781 25782 25783 25784 25785 25786 25787 25788 25789 25790 25791 25792 25793 25794 25795 25796 25797 25798 25799 25800 25801 25802 25803 25804 25805 25806 25807 25808 25809 25810 25811 25812 25813 25814 25815 25816 25817 25818 25819 25820 25821 25822 25823 25824 25825 25826 25827 25828 25829 25830 25831 25832 25833 25834 25835 25836 25837 25838 25839 25840 25841 25842 25843 25844 25845 25846 25847 25848 25849 25850 25851 25852 25853 25854 25855 25856 25857 25858 25859 25860 25861 25862 25863 25864 25865 25866 25867 25868 25869 25870 25871 25872 25873 25874 25875 25876 25877 25878 25879 25880 25881 25882 25883 25884 25885 25886 25887 25888 25889 25890 25891 25892 25893 25894 25895 25896 25897 25898 25899 25900 25901 25902 25903 25904 25905 25906 25907 25908 25909 25910 25911 25912 25913 25914 25915 25916 25917 25918 25919 25920 25921 25922 25923 25924 25925 25926 25927 25928 25929 25930 25931 25932 25933 25934 25935 25936 25937 25938 25939 25940 25941 25942 25943 25944 25945 25946 25947 25948 25949 25950 25951 25952 25953 25954 25955 25956 25957 25958 25959 25960 25961 25962 25963 25964 25965 25966 25967 25968 25969 25970 25971 25972 25973 25974 25975 25976 25977 25978 25979 25980 25981 25982 25983 25984 25985 25986 25987 25988 25989 25990 25991 25992 25993 25994 25995 25996 25997 25998 25999 26000 26001 26002 26003 26004 26005 26006 26007 26008 26009 26010 26011 26012 26013 26014 26015 26016 26017 26018 26019 26020 26021 26022 26023 26024 26025 26026 26027 26028 26029 26030 26031 26032 26033 26034 26035 26036 26037 26038 26039 26040 26041 26042 26043 26044 26045 26046 26047 26048 26049 26050 26051 26052 26053 26054 26055 26056 26057 26058 26059 26060 26061 26062 26063 26064 26065 26066 26067 26068 26069 26070 26071 26072 26073 26074 26075 26076 26077 26078 26079 26080 26081 26082 26083 26084 26085 26086 26087 26088 26089 26090 26091 26092 26093 26094 26095 26096 26097 26098 26099 26100 26101 26102 26103 26104 26105 26106 26107 26108 26109 26110 26111 26112 26113 26114 26115 26116 26117 26118 26119 26120 26121 26122 26123 26124 26125 26126 26127 26128 26129 26130 26131 26132 26133 26134 26135 26136 26137 26138 26139 26140 26141 26142 26143 26144 26145 26146 26147 26148 26149 26150 26151 26152 26153 26154 26155 26156 26157 26158 26159 26160 26161 26162 26163 26164 26165 26166 26167 26168 26169 26170 26171 26172 26173 26174 26175 26176 26177 26178 26179 26180 26181 26182 26183 26184 26185 26186 26187 26188 26189 26190 26191 26192 26193 26194 26195 26196 26197 26198 26199 26200 26201 26202 26203 26204 26205 26206 26207 26208 26209 26210 26211 26212 26213 26214 26215 26216 26217 26218 26219 26220 26221 26222 26223 26224 26225 26226 26227 26228 26229 26230 26231 26232 26233 26234 26235 26236 26237 26238 26239 26240 26241 26242 26243 26244 26245 26246 26247 26248 26249 26250 26251 26252 26253 26254 26255 26256 26257 26258 26259 26260 26261 26262 26263 26264 26265 26266 26267 26268 26269 26270 26271 26272 26273 26274 26275 26276 26277 26278 26279 26280 26281 26282 26283 26284 26285 26286 26287 26288 26289 26290 26291 26292 26293 26294 26295 26296 26297 26298 26299 26300 26301 26302 26303 26304 26305 26306 26307 26308 26309 26310 26311 26312 26313 26314 26315 26316 26317 26318 26319 26320 26321 26322 26323 26324 26325 26326 26327 26328 26329 26330 26331 26332 26333 26334 26335 26336 26337 26338 26339 26340 26341 26342 26343 26344 26345 26346 26347 26348 26349 26350 26351 26352 26353 26354 26355 26356 26357 26358 26359 26360 26361 26362 26363 26364 26365 26366 26367 26368 26369 26370 26371 26372 26373 26374 26375 26376 26377 26378 26379 26380 26381 26382 26383 26384 26385 26386 26387 26388 26389 26390 26391 26392 26393 26394 26395 26396 26397 26398 26399 26400 26401 26402 26403 26404 26405 26406 26407 26408 26409 26410 26411 26412 26413 26414 26415 26416 26417 26418 26419 26420 26421 26422 26423 26424 26425 26426 26427 26428 26429 26430 26431 26432 26433 26434 26435 26436 26437 26438 26439 26440 26441 26442 26443 26444 26445 26446 26447 26448 26449 26450 26451 26452 26453 26454 26455 26456 26457 26458 26459 26460 26461 26462 26463 26464 26465 26466 26467 26468 26469 26470 26471 26472 26473 26474 26475 26476 26477 26478 26479 26480 26481 26482 26483 26484 26485 26486 26487 26488 26489 26490 26491 26492 26493 26494 26495 26496 26497 26498 26499 26500 26501 26502 26503 26504 26505 26506 26507 26508 26509 26510 26511 26512 26513 26514 26515 26516 26517 26518 26519 26520 26521 26522 26523 26524 26525 26526 26527 26528 26529 26530 26531 26532 26533 26534 26535 26536 26537 26538 26539 26540 26541 26542 26543 26544 26545 26546 26547 26548 26549 26550 26551 26552 26553 26554 26555 26556 26557 26558 26559 26560 26561 26562 26563 26564 26565 26566 26567 26568 26569 26570 26571 26572 26573 26574 26575 26576 26577 26578 26579 26580 26581 26582 26583 26584 26585 26586 26587 26588 26589 26590 26591 26592 26593 26594 26595 26596 26597 26598 26599 26600 26601 26602 26603 26604 26605 26606 26607 26608 26609 26610 26611 26612 26613 26614 26615 26616 26617 26618 26619 26620 26621 26622 26623 26624 26625 26626 26627 26628 26629 26630 26631 26632 26633 26634 26635 26636 26637 26638 26639 26640 26641 26642 26643 26644 26645 26646 26647 26648 26649 26650 26651 26652 26653 26654 26655 26656 26657 26658 26659 26660 26661 26662 26663 26664 26665 26666 26667 26668 26669 26670 26671 26672 26673 26674 26675 26676 26677 26678 26679 26680 26681 26682 26683 26684 26685 26686 26687 26688 26689 26690 26691 26692 26693 26694 26695 26696 26697 26698 26699 26700 26701 26702 26703 26704 26705 26706 26707 26708 26709 26710 26711 26712 26713 26714 26715 26716 26717 26718 26719 26720 26721 26722 26723 26724 26725 26726 26727 26728 26729 26730 26731 26732 26733 26734 26735 26736 26737 26738 26739 26740 26741 26742 26743 26744 26745 26746 26747 26748 26749 26750 26751 26752 26753 26754 26755 26756 26757 26758 26759 26760 26761 26762 26763 26764 26765 26766 26767 26768 26769 26770 26771 26772 26773 26774 26775 26776 26777 26778 26779 26780 26781 26782 26783 26784 26785 26786 26787 26788 26789 26790 26791 26792 26793 26794 26795 26796 26797 26798 26799 26800 26801 26802 26803 26804 26805 26806 26807 26808 26809 26810 26811 26812 26813 26814 26815 26816 26817 26818 26819 26820 26821 26822 26823 26824 26825 26826 26827 26828 26829 26830 26831 26832 26833 26834 26835 26836 26837 26838 26839 26840 26841 26842 26843 26844 26845 26846 26847 26848 26849 26850 26851 26852 26853 26854 26855 26856 26857 26858 26859 26860 26861 26862 26863 26864 26865 26866 26867 26868 26869 26870 26871 26872 26873 26874 26875 26876 26877 26878 26879 26880 26881 26882 26883 26884 26885 26886 26887 26888 26889 26890 26891 26892 26893 26894 26895 26896 26897 26898 26899 26900 26901 26902 26903 26904 26905 26906 26907 26908 26909 26910 26911 26912 26913 26914 26915 26916 26917 26918 26919 26920 26921 26922 26923 26924 26925 26926 26927 26928 26929 26930 26931 26932 26933 26934 26935 26936 26937 26938 26939 26940 26941 26942 26943 26944 26945 26946 26947 26948 26949 26950 26951 26952 26953 26954 26955 26956 26957 26958 26959 26960 26961 26962 26963 26964 26965 26966 26967 26968 26969 26970 26971 26972 26973 26974 26975 26976 26977 26978 26979 26980 26981 26982 26983 26984 26985 26986 26987 26988 26989 26990 26991 26992 26993 26994 26995 26996 26997 26998 26999 27000 27001 27002 27003 27004 27005 27006 27007 27008 27009 27010 27011 27012 27013 27014 27015 27016 27017 27018 27019 27020 27021 27022 27023 27024 27025 27026 27027 27028 27029 27030 27031 27032 27033 27034 27035 27036 27037 27038 27039 27040 27041 27042 27043 27044 27045 27046 27047 27048 27049 27050 27051 27052 27053 27054 27055 27056 27057 27058 27059 27060 27061 27062 27063 27064 27065 27066 27067 27068 27069 27070 27071 27072 27073 27074 27075 27076 27077 27078 27079 27080 27081 27082 27083 27084 27085 27086 27087 27088 27089 27090 27091 27092 27093 27094 27095 27096 27097 27098 27099 27100 27101 27102 27103 27104 27105 27106 27107 27108 27109 27110 27111 27112 27113 27114 27115 27116 27117 27118 27119 27120 27121 27122 27123 27124 27125 27126 27127 27128 27129 27130 27131 27132 27133 27134 27135 27136 27137 27138 27139 27140 27141 27142 27143 27144 27145 27146 27147 27148 27149 27150 27151 27152 27153 27154 27155 27156 27157 27158 27159 27160 27161 27162 27163 27164 27165 27166 27167 27168 27169 27170 27171 27172 27173 27174 27175 27176 27177 27178 27179 27180 27181 27182 27183 27184 27185 27186 27187 27188 27189 27190 27191 27192 27193 27194 27195 27196 27197 27198 27199 27200 27201 27202 27203 27204 27205 27206 27207 27208 27209 27210 27211 27212 27213 27214 27215 27216 27217 27218 27219 27220 27221 27222 27223 27224 27225 27226 27227 27228 27229 27230 27231 27232 27233 27234 27235 27236 27237 27238 27239 27240 27241 27242 27243 27244 27245 27246 27247 27248 27249 27250 27251 27252 27253 27254 27255 27256 27257 27258 27259 27260 27261 27262 27263 27264 27265 27266 27267 27268 27269 27270 27271 27272 27273 27274 27275 27276 27277 27278 27279 27280 27281 27282 27283 27284 27285 27286 27287 27288 27289 27290 27291 27292 27293 27294 27295 27296 27297 27298 27299 27300 27301 27302 27303 27304 27305 27306 27307 27308 27309 27310 27311 27312 27313 27314 27315 27316 27317 27318 27319 27320 27321 27322 27323 27324 27325 27326 27327 27328 27329 27330 27331 27332 27333 27334 27335 27336 27337 27338 27339 27340 27341 27342 27343 27344 27345 27346 27347 27348 27349 27350 27351 27352 27353 27354 27355 27356 27357 27358 27359 27360 27361 27362 27363 27364 27365 27366 27367 27368 27369 27370 27371 27372 27373 27374 27375 27376 27377 27378 27379 27380 27381 27382 27383 27384 27385 27386 27387 27388 27389 27390 27391 27392 27393 27394 27395 27396 27397 27398 27399 27400 27401 27402 27403 27404 27405 27406 27407 27408 27409 27410 27411 27412 27413 27414 27415 27416 27417 27418 27419 27420 27421 27422 27423 27424 27425 27426 27427 27428 27429 27430 27431 27432 27433 27434 27435 27436 27437 27438 27439 27440 27441 27442 27443 27444 27445 27446 27447 27448 27449 27450 27451 27452 27453 27454 27455 27456 27457 27458 27459 27460 27461 27462 27463 27464 27465 27466 27467 27468 27469 27470 27471 27472 27473 27474 27475 27476 27477 27478 27479 27480 27481 27482 27483 27484 27485 27486 27487 27488 27489 27490 27491 27492 27493 27494 27495 27496 27497 27498 27499 27500 27501 27502 27503 27504 27505 27506 27507 27508 27509 27510 27511 27512 27513 27514 27515 27516 27517 27518 27519 27520 27521 27522 27523 27524 27525 27526 27527 27528 27529 27530 27531 27532 27533 27534 27535 27536 27537 27538 27539 27540 27541 27542 27543 27544 27545 27546 27547 27548 27549 27550 27551 27552 27553 27554 27555 27556 27557 27558 27559 27560 27561 27562 27563 27564 27565 27566 27567 27568 27569 27570 27571 27572 27573 27574 27575 27576 27577 27578 27579 27580 27581 27582 27583 27584 27585 27586 27587 27588 27589 27590 27591 27592 27593 27594 27595 27596 27597 27598 27599 27600 27601 27602 27603 27604 27605 27606 27607 27608 27609 27610 27611 27612 27613 27614 27615 27616 27617 27618 27619 27620 27621 27622 27623 27624 27625 27626 27627 27628 27629 27630 27631 27632 27633 27634 27635 27636 27637 27638 27639 27640 27641 27642 27643 27644 27645 27646 27647 27648 27649 27650 27651 27652 27653 27654 27655 27656 27657 27658 27659 27660 27661 27662 27663 27664 27665 27666 27667 27668 27669 27670 27671 27672 27673 27674 27675 27676 27677 27678 27679 27680 27681 27682 27683 27684 27685 27686 27687 27688 27689 27690 27691 27692 27693 27694 27695 27696 27697 27698 27699 27700 27701 27702 27703 27704 27705 27706 27707 27708 27709 27710 27711 27712 27713 27714 27715 27716 27717 27718 27719 27720 27721 27722 27723 27724 27725 27726 27727 27728 27729 27730 27731 27732 27733 27734 27735 27736 27737 27738 27739 27740 27741 27742 27743 27744 27745 27746 27747 27748 27749 27750 27751 27752 27753 27754 27755 27756 27757 27758 27759 27760 27761 27762 27763 27764 27765 27766 27767 27768 27769 27770 27771 27772 27773 27774 27775 27776 27777 27778 27779 27780 27781 27782 27783 27784 27785 27786 27787 27788 27789 27790 27791 27792 27793 27794 27795 27796 27797 27798 27799 27800 27801 27802 27803 27804 27805 27806 27807 27808 27809 27810 27811 27812 27813 27814 27815 27816 27817 27818 27819 27820 27821 27822 27823 27824 27825 27826 27827 27828 27829 27830 27831 27832 27833 27834 27835 27836 27837 27838 27839 27840 27841 27842 27843 27844 27845 27846 27847 27848 27849 27850 27851 27852 27853 27854 27855 27856 27857 27858 27859 27860 27861 27862 27863 27864 27865 27866 27867 27868 27869 27870 27871 27872 27873 27874 27875 27876 27877 27878 27879 27880 27881 27882 27883 27884 27885 27886 27887 27888 27889 27890 27891 27892 27893 27894 27895 27896 27897 27898 27899 27900 27901 27902 27903 27904 27905 27906 27907 27908 27909 27910 27911 27912 27913 27914 27915 27916 27917 27918 27919 27920 27921 27922 27923 27924 27925 27926 27927 27928 27929 27930 27931 27932 27933 27934 27935 27936 27937 27938 27939 27940 27941 27942 27943 27944 27945 27946 27947 27948 27949 27950 27951 27952 27953 27954 27955 27956 27957 27958 27959 27960 27961 27962 27963 27964 27965 27966 27967 27968 27969 27970 27971 27972 27973 27974 27975 27976 27977 27978 27979 27980 27981 27982 27983 27984 27985 27986 27987 27988 27989 27990 27991 27992 27993 27994 27995 27996 27997 27998 27999 28000 28001 28002 28003 28004 28005 28006 28007 28008 28009 28010 28011 28012 28013 28014 28015 28016 28017 28018 28019 28020 28021 28022 28023 28024 28025 28026 28027 28028 28029 28030 28031 28032 28033 28034 28035 28036 28037 28038 28039 28040 28041 28042 28043 28044 28045 28046 28047 28048 28049 28050 28051 28052 28053 28054 28055 28056 28057 28058 28059 28060 28061 28062 28063 28064 28065 28066 28067 28068 28069 28070 28071 28072 28073 28074 28075 28076 28077 28078 28079 28080 28081 28082 28083 28084 28085 28086 28087 28088 28089 28090 28091 28092 28093 28094 28095 28096 28097 28098 28099 28100 28101 28102 28103 28104 28105 28106 28107 28108 28109 28110 28111 28112 28113 28114 28115 28116 28117 28118 28119 28120 28121 28122 28123 28124 28125 28126 28127 28128 28129 28130 28131 28132 28133 28134 28135 28136 28137 28138 28139 28140 28141 28142 28143 28144 28145 28146 28147 28148 28149 28150 28151 28152 28153 28154 28155 28156 28157 28158 28159 28160 28161 28162 28163 28164 28165 28166 28167 28168 28169 28170 28171 28172 28173 28174 28175 28176 28177 28178 28179 28180 28181 28182 28183 28184 28185 28186 28187 28188 28189 28190 28191 28192 28193 28194 28195 28196 28197 28198 28199 28200 28201 28202 28203 28204 28205 28206 28207 28208 28209 28210 28211 28212 28213 28214 28215 28216 28217 28218 28219 28220 28221 28222 28223 28224 28225 28226 28227 28228 28229 28230 28231 28232 28233 28234 28235 28236 28237 28238 28239 28240 28241 28242 28243 28244 28245 28246 28247 28248 28249 28250 28251 28252 28253 28254 28255 28256 28257 28258 28259 28260 28261 28262 28263 28264 28265 28266 28267 28268 28269 28270 28271 28272 28273 28274 28275 28276 28277 28278 28279 28280 28281 28282 28283 28284 28285 28286 28287 28288 28289 28290 28291 28292 28293 28294 28295 28296 28297 28298 28299 28300 28301 28302 28303 28304 28305 28306 28307 28308 28309 28310 28311 28312 28313 28314 28315 28316 28317 28318 28319 28320 28321 28322 28323 28324 28325 28326 28327 28328 28329 28330 28331 28332 28333 28334 28335 28336 28337 28338 28339 28340 28341 28342 28343 28344 28345 28346 28347 28348 28349 28350 28351 28352 28353 28354 28355 28356 28357 28358 28359 28360 28361 28362 28363 28364 28365 28366 28367 28368 28369 28370 28371 28372 28373 28374 28375 28376 28377 28378 28379 28380 28381 28382 28383 28384 28385 28386 28387 28388 28389 28390 28391 28392 28393 28394 28395 28396 28397 28398 28399 28400 28401 28402 28403 28404 28405 28406 28407 28408 28409 28410 28411 28412 28413 28414 28415 28416 28417 28418 28419 28420 28421 28422 28423 28424 28425 28426 28427 28428 28429 28430 28431 28432 28433 28434 28435 28436 28437 28438 28439 28440 28441 28442 28443 28444 28445 28446 28447 28448 28449 28450 28451 28452 28453 28454 28455 28456 28457 28458 28459 28460 28461 28462 28463 28464 28465 28466 28467 28468 28469 28470 28471 28472 28473 28474 28475 28476 28477 28478 28479 28480 28481 28482 28483 28484 28485 28486 28487 28488 28489 28490 28491 28492 28493 28494 28495 28496 28497 28498 28499 28500 28501 28502 28503 28504 28505 28506 28507 28508 28509 28510 28511 28512 28513 28514 28515 28516 28517 28518 28519 28520 28521 28522 28523 28524 28525 28526 28527 28528 28529 28530 28531 28532 28533 28534 28535 28536 28537 28538 28539 28540 28541 28542 28543 28544 28545 28546 28547 28548 28549 28550 28551 28552 28553 28554 28555 28556 28557 28558 28559 28560 28561 28562 28563 28564 28565 28566 28567 28568 28569 28570 28571 28572 28573 28574 28575 28576 28577 28578 28579 28580 28581 28582 28583 28584 28585 28586 28587 28588 28589 28590 28591 28592 28593 28594 28595 28596 28597 28598 28599 28600 28601 28602 28603 28604 28605 28606 28607 28608 28609 28610 28611 28612 28613 28614 28615 28616 28617 28618 28619 28620 28621 28622 28623 28624 28625 28626 28627 28628 28629 28630 28631 28632 28633 28634 28635 28636 28637 28638 28639 28640 28641 28642 28643 28644 28645 28646 28647 28648 28649 28650 28651 28652 28653 28654 28655 28656 28657 28658 28659 28660 28661 28662 28663 28664 28665 28666 28667 28668 28669 28670 28671 28672 28673 28674 28675 28676 28677 28678 28679 28680 28681 28682 28683 28684 28685 28686 28687 28688 28689 28690 28691 28692 28693 28694 28695 28696 28697 28698 28699 28700 28701 28702 28703 28704 28705 28706 28707 28708 28709 28710 28711 28712 28713 28714 28715 28716 28717 28718 28719 28720 28721 28722 28723 28724 28725 28726 28727 28728 28729 28730 28731 28732 28733 28734 28735 28736 28737 28738 28739 28740 28741 28742 28743 28744 28745 28746 28747 28748 28749 28750 28751 28752 28753 28754 28755 28756 28757 28758 28759 28760 28761 28762 28763 28764 28765 28766 28767 28768 28769 28770 28771 28772 28773 28774 28775 28776 28777 28778 28779 28780 28781 28782 28783 28784 28785 28786 28787 28788 28789 28790 28791 28792 28793 28794 28795 28796 28797 28798 28799 28800 28801 28802 28803 28804 28805 28806 28807 28808 28809 28810 28811 28812 28813 28814 28815 28816 28817 28818 28819 28820 28821 28822 28823 28824 28825 28826 28827 28828 28829 28830 28831 28832 28833 28834 28835 28836 28837 28838 28839 28840 28841 28842 28843 28844 28845 28846 28847 28848 28849 28850 28851 28852 28853 28854 28855 28856 28857 28858 28859 28860 28861 28862 28863 28864 28865 28866 28867 28868 28869 28870 28871 28872 28873 28874 28875 28876 28877 28878 28879 28880 28881 28882 28883 28884 28885 28886 28887 28888 28889 28890 28891 28892 28893 28894 28895 28896 28897 28898 28899 28900 28901 28902 28903 28904 28905 28906 28907 28908 28909 28910 28911 28912 28913 28914 28915 28916 28917 28918 28919 28920 28921 28922 28923 28924 28925 28926 28927 28928 28929 28930 28931 28932 28933 28934 28935 28936 28937 28938 28939 28940 28941 28942 28943 28944 28945 28946 28947 28948 28949 28950 28951 28952 28953 28954 28955 28956 28957 28958 28959 28960 28961 28962 28963 28964 28965 28966 28967 28968 28969 28970 28971 28972 28973 28974 28975 28976 28977 28978 28979 28980 28981 28982 28983 28984 28985 28986 28987 28988 28989 28990 28991 28992 28993 28994 28995 28996 28997 28998 28999 29000 29001 29002 29003 29004 29005 29006 29007 29008 29009 29010 29011 29012 29013 29014 29015 29016 29017 29018 29019 29020 29021 29022 29023 29024 29025 29026 29027 29028 29029 29030 29031 29032 29033 29034 29035 29036 29037 29038 29039 29040 29041 29042 29043 29044 29045 29046 29047 29048 29049 29050 29051 29052 29053 29054 29055 29056 29057 29058 29059 29060 29061 29062 29063 29064 29065 29066 29067 29068 29069 29070 29071 29072 29073 29074 29075 29076 29077 29078 29079 29080 29081 29082 29083 29084 29085 29086 29087 29088 29089 29090 29091 29092 29093 29094 29095 29096 29097 29098 29099 29100 29101 29102 29103 29104 29105 29106 29107 29108 29109 29110 29111 29112 29113 29114 29115 29116 29117 29118 29119 29120 29121 29122 29123 29124 29125 29126 29127 29128 29129 29130 29131 29132 29133 29134 29135 29136 29137 29138 29139 29140 29141 29142 29143 29144 29145 29146 29147 29148 29149 29150 29151 29152 29153 29154 29155 29156 29157 29158 29159 29160 29161 29162 29163 29164 29165 29166 29167 29168 29169 29170 29171 29172 29173 29174 29175 29176 29177 29178 29179 29180 29181 29182 29183 29184 29185 29186 29187 29188 29189 29190 29191 29192 29193 29194 29195 29196 29197 29198 29199 29200 29201 29202 29203 29204 29205 29206 29207 29208 29209 29210 29211 29212 29213 29214 29215 29216 29217 29218 29219 29220 29221 29222 29223 29224 29225 29226 29227 29228 29229 29230 29231 29232 29233 29234 29235 29236 29237 29238 29239 29240 29241 29242 29243 29244 29245 29246 29247 29248 29249 29250 29251 29252 29253 29254 29255 29256 29257 29258 29259 29260 29261 29262 29263 29264 29265 29266 29267 29268 29269 29270 29271 29272 29273 29274 29275 29276 29277 29278 29279 29280 29281 29282 29283 29284 29285 29286 29287 29288 29289 29290 29291 29292 29293 29294 29295 29296 29297 29298 29299 29300 29301 29302 29303 29304 29305 29306 29307 29308 29309 29310 29311 29312 29313 29314 29315 29316 29317 29318 29319 29320 29321 29322 29323 29324 29325 29326 29327 29328 29329 29330 29331 29332 29333 29334 29335 29336 29337 29338 29339 29340 29341 29342 29343 29344 29345 29346 29347 29348 29349 29350 29351 29352 29353 29354 29355 29356 29357 29358 29359 29360 29361 29362 29363 29364 29365 29366 29367 29368 29369 29370 29371 29372 29373 29374 29375 29376 29377 29378 29379 29380 29381 29382 29383 29384 29385 29386 29387 29388 29389 29390 29391 29392 29393 29394 29395 29396 29397 29398 29399 29400 29401 29402 29403 29404 29405 29406 29407 29408 29409 29410 29411 29412 29413 29414 29415 29416 29417 29418 29419 29420 29421 29422 29423 29424 29425 29426 29427 29428 29429 29430 29431 29432 29433 29434 29435 29436 29437 29438 29439 29440 29441 29442 29443 29444 29445 29446 29447 29448 29449 29450 29451 29452 29453 29454 29455 29456 29457 29458 29459 29460 29461 29462 29463 29464 29465 29466 29467 29468 29469 29470 29471 29472 29473 29474 29475 29476 29477 29478 29479 29480 29481 29482 29483 29484 29485 29486 29487 29488 29489 29490 29491 29492 29493 29494 29495 29496 29497 29498 29499 29500 29501 29502 29503 29504 29505 29506 29507 29508 29509 29510 29511 29512 29513 29514 29515 29516 29517 29518 29519 29520 29521 29522 29523 29524 29525 29526 29527 29528 29529 29530 29531 29532 29533 29534 29535 29536 29537 29538 29539 29540 29541 29542 29543 29544 29545 29546 29547 29548 29549 29550 29551 29552 29553 29554 29555 29556 29557 29558 29559 29560 29561 29562 29563 29564 29565 29566 29567 29568 29569 29570 29571 29572 29573 29574 29575 29576 29577 29578 29579 29580 29581 29582 29583 29584 29585 29586 29587 29588 29589 29590 29591 29592 29593 29594 29595 29596 29597 29598 29599 29600 29601 29602 29603 29604 29605 29606 29607 29608 29609 29610 29611 29612 29613 29614 29615 29616 29617 29618 29619 29620 29621 29622 29623 29624 29625 29626 29627 29628 29629 29630 29631 29632 29633 29634 29635 29636 29637 29638 29639 29640 29641 29642 29643 29644 29645 29646 29647 29648 29649 29650 29651 29652 29653 29654 29655 29656 29657 29658 29659 29660 29661 29662 29663 29664 29665 29666 29667 29668 29669 29670 29671 29672 29673 29674 29675 29676 29677 29678 29679 29680 29681 29682 29683 29684 29685 29686 29687 29688 29689 29690 29691 29692 29693 29694 29695 29696 29697 29698 29699 29700 29701 29702 29703 29704 29705 29706 29707 29708 29709 29710 29711 29712 29713 29714 29715 29716 29717 29718 29719 29720 29721 29722 29723 29724 29725 29726 29727 29728 29729 29730 29731 29732 29733 29734 29735 29736 29737 29738 29739 29740 29741 29742 29743 29744 29745 29746 29747 29748 29749 29750 29751 29752 29753 29754 29755 29756 29757 29758 29759 29760 29761 29762 29763 29764 29765 29766 29767 29768 29769 29770 29771 29772 29773 29774 29775 29776 29777 29778 29779 29780 29781 29782 29783 29784 29785 29786 29787 29788 29789 29790 29791 29792 29793 29794 29795 29796 29797 29798 29799 29800 29801 29802 29803 29804 29805 29806 29807 29808 29809 29810 29811 29812 29813 29814 29815 29816 29817 29818 29819 29820 29821 29822 29823 29824 29825 29826 29827 29828 29829 29830 29831 29832 29833 29834 29835 29836 29837 29838 29839 29840 29841 29842 29843 29844 29845 29846 29847 29848 29849 29850 29851 29852 29853 29854 29855 29856 29857 29858 29859 29860 29861 29862 29863 29864 29865 29866 29867 29868 29869 29870 29871 29872 29873 29874 29875 29876 29877 29878 29879 29880 29881 29882 29883 29884 29885 29886 29887 29888 29889 29890 29891 29892 29893 29894 29895 29896 29897 29898 29899 29900 29901 29902 29903 29904 29905 29906 29907 29908 29909 29910 29911 29912 29913 29914 29915 29916 29917 29918 29919 29920 29921 29922 29923 29924 29925 29926 29927 29928 29929 29930 29931 29932 29933 29934 29935 29936 29937 29938 29939 29940 29941 29942 29943 29944 29945 29946 29947 29948 29949 29950 29951 29952 29953 29954 29955 29956 29957 29958 29959 29960 29961 29962 29963 29964 29965 29966 29967 29968 29969 29970 29971 29972 29973 29974 29975 29976 29977 29978 29979 29980 29981 29982 29983 29984 29985 29986 29987 29988 29989 29990 29991 29992 29993 29994 29995 29996 29997 29998 29999 30000 30001 30002 30003 30004 30005 30006 30007 30008 30009 30010 30011 30012 30013 30014 30015 30016 30017 30018 30019 30020 30021 30022 30023 30024 30025 30026 30027 30028 30029 30030 30031 30032 30033 30034 30035 30036 30037 30038 30039 30040 30041 30042 30043 30044 30045 30046 30047 30048 30049 30050 30051 30052 30053 30054 30055 30056 30057 30058 30059 30060 30061 30062 30063 30064 30065 30066 30067 30068 30069 30070 30071 30072 30073 30074 30075 30076 30077 30078 30079 30080 30081 30082 30083 30084 30085 30086 30087 30088 30089 30090 30091 30092 30093 30094 30095 30096 30097 30098 30099 30100 30101 30102 30103 30104 30105 30106 30107 30108 30109 30110 30111 30112 30113 30114 30115 30116 30117 30118 30119 30120 30121 30122 30123 30124 30125 30126 30127 30128 30129 30130 30131 30132 30133 30134 30135 30136 30137 30138 30139 30140 30141 30142 30143 30144 30145 30146 30147 30148 30149 30150 30151 30152 30153 30154 30155 30156 30157 30158 30159 30160 30161 30162 30163 30164 30165 30166 30167 30168 30169 30170 30171 30172 30173 30174 30175 30176 30177 30178 30179 30180 30181 30182 30183 30184 30185 30186 30187 30188 30189 30190 30191 30192 30193 30194 30195 30196 30197 30198 30199 30200 30201 30202 30203 30204 30205 30206 30207 30208 30209 30210 30211 30212 30213 30214 30215 30216 30217 30218 30219 30220 30221 30222 30223 30224 30225 30226 30227 30228 30229 30230 30231 30232 30233 30234 30235 30236 30237 30238 30239 30240 30241 30242 30243 30244 30245 30246 30247 30248 30249 30250 30251 30252 30253 30254 30255 30256 30257 30258 30259 30260 30261 30262 30263 30264 30265 30266 30267 30268 30269 30270 30271 30272 30273 30274 30275 30276 30277 30278 30279 30280 30281 30282 30283 30284 30285 30286 30287 30288 30289 30290 30291 30292 30293 30294 30295 30296 30297 30298 30299 30300 30301 30302 30303 30304 30305 30306 30307 30308 30309 30310 30311 30312 30313 30314 30315 30316 30317 30318 30319 30320 30321 30322 30323 30324 30325 30326 30327 30328 30329 30330 30331 30332 30333 30334 30335 30336 30337 30338 30339 30340 30341 30342 30343 30344 30345 30346 30347 30348 30349 30350 30351 30352 30353 30354 30355 30356 30357 30358 30359 30360 30361 30362 30363 30364 30365 30366 30367 30368 30369 30370 30371 30372 30373 30374 30375 30376 30377 30378 30379 30380 30381 30382 30383 30384 30385 30386 30387 30388 30389 30390 30391 30392 30393 30394 30395 30396 30397 30398 30399 30400 30401 30402 30403 30404 30405 30406 30407 30408 30409 30410 30411 30412 30413 30414 30415 30416 30417 30418 30419 30420 30421 30422 30423 30424 30425 30426 30427 30428 30429 30430 30431 30432 30433 30434 30435 30436 30437 30438 30439 30440 30441 30442 30443 30444 30445 30446 30447 30448 30449 30450 30451 30452 30453 30454 30455 30456 30457 30458 30459 30460 30461 30462 30463 30464 30465 30466 30467 30468 30469 30470 30471 30472 30473 30474 30475 30476 30477 30478 30479 30480 30481 30482 30483 30484 30485 30486 30487 30488 30489 30490 30491 30492 30493 30494 30495 30496 30497 30498 30499 30500 30501 30502 30503 30504 30505 30506 30507 30508 30509 30510 30511 30512 30513 30514 30515 30516 30517 30518 30519 30520 30521 30522 30523 30524 30525 30526 30527 30528 30529 30530 30531 30532 30533 30534 30535 30536 30537 30538 30539 30540 30541 30542 30543 30544 30545 30546 30547 30548 30549 30550 30551 30552 30553 30554 30555 30556 30557 30558 30559 30560 30561 30562 30563 30564 30565 30566 30567 30568 30569 30570 30571 30572 30573 30574 30575 30576 30577 30578 30579 30580 30581 30582 30583 30584 30585 30586 30587 30588 30589 30590 30591 30592 30593 30594 30595 30596 30597 30598 30599 30600 30601 30602 30603 30604 30605 30606 30607 30608 30609 30610 30611 30612 30613 30614 30615 30616 30617 30618 30619 30620 30621 30622 30623 30624 30625 30626 30627 30628 30629 30630 30631 30632 30633 30634 30635 30636 30637 30638 30639 30640 30641 30642 30643 30644 30645 30646 30647 30648 30649 30650 30651 30652 30653 30654 30655 30656 30657 30658 30659 30660 30661 30662 30663 30664 30665 30666 30667 30668 30669 30670 30671 30672 30673 30674 30675 30676 30677 30678 30679 30680 30681 30682 30683 30684 30685 30686 30687 30688 30689 30690 30691 30692 30693 30694 30695 30696 30697 30698 30699 30700 30701 30702 30703 30704 30705 30706 30707 30708 30709 30710 30711 30712 30713 30714 30715 30716 30717 30718 30719 30720 30721 30722 30723 30724 30725 30726 30727 30728 30729 30730 30731 30732 30733 30734 30735 30736 30737 30738 30739 30740 30741 30742 30743 30744 30745 30746 30747 30748 30749 30750 30751 30752 30753 30754 30755 30756 30757 30758 30759 30760 30761 30762 30763 30764 30765 30766 30767 30768 30769 30770 30771 30772 30773 30774 30775 30776 30777 30778 30779 30780 30781 30782 30783 30784 30785 30786 30787 30788 30789 30790 30791 30792 30793 30794 30795 30796 30797 30798 30799 30800 30801 30802 30803 30804 30805 30806 30807 30808 30809 30810 30811 30812 30813 30814 30815 30816 30817 30818 30819 30820 30821 30822 30823 30824 30825 30826 30827 30828 30829 30830 30831 30832 30833 30834 30835 30836 30837 30838 30839 30840 30841 30842 30843 30844 30845 30846 30847 30848 30849 30850 30851 30852 30853 30854 30855 30856 30857 30858 30859 30860 30861 30862 30863 30864 30865 30866 30867 30868 30869 30870 30871 30872 30873 30874 30875 30876 30877 30878 30879 30880 30881 30882 30883 30884 30885 30886 30887 30888 30889 30890 30891 30892 30893 30894 30895 30896 30897 30898 30899 30900 30901 30902 30903 30904 30905 30906 30907 30908 30909 30910 30911 30912 30913 30914 30915 30916 30917 30918 30919 30920 30921 30922 30923 30924 30925 30926 30927 30928 30929 30930 30931 30932 30933 30934 30935 30936 30937 30938 30939 30940 30941 30942 30943 30944 30945 30946 30947 30948 30949 30950 30951 30952 30953 30954 30955 30956 30957 30958 30959 30960 30961 30962 30963 30964 30965 30966 30967 30968 30969 30970 30971 30972 30973 30974 30975 30976 30977 30978 30979 30980 30981 30982 30983 30984 30985 30986 30987 30988 30989 30990 30991 30992 30993 30994 30995 30996 30997 30998 30999 31000 31001 31002 31003 31004 31005 31006 31007 31008 31009 31010 31011 31012 31013 31014 31015 31016 31017 31018 31019 31020 31021 31022 31023 31024 31025 31026 31027 31028 31029 31030 31031 31032 31033 31034 31035 31036 31037 31038 31039 31040 31041 31042 31043 31044 31045 31046 31047 31048 31049 31050 31051 31052 31053 31054 31055 31056 31057 31058 31059 31060 31061 31062 31063 31064 31065 31066 31067 31068 31069 31070 31071 31072 31073 31074 31075 31076 31077 31078 31079 31080 31081 31082 31083 31084 31085 31086 31087 31088 31089 31090 31091 31092 31093 31094 31095 31096 31097 31098 31099 31100 31101 31102 31103 31104 31105 31106 31107 31108 31109 31110 31111 31112 31113 31114 31115 31116 31117 31118 31119 31120 31121 31122 31123 31124 31125 31126 31127 31128 31129 31130 31131 31132 31133 31134 31135 31136 31137 31138 31139 31140 31141 31142 31143 31144 31145 31146 31147 31148 31149 31150 31151 31152 31153 31154 31155 31156 31157 31158 31159 31160 31161 31162 31163 31164 31165 31166 31167 31168 31169 31170 31171 31172 31173 31174 31175 31176 31177 31178 31179 31180 31181 31182 31183 31184 31185 31186 31187 31188 31189 31190 31191 31192 31193 31194 31195 31196 31197 31198 31199 31200 31201 31202 31203 31204 31205 31206 31207 31208 31209 31210 31211 31212 31213 31214 31215 31216 31217 31218 31219 31220 31221 31222 31223 31224 31225 31226 31227 31228 31229 31230 31231 31232 31233 31234 31235 31236 31237 31238 31239 31240 31241 31242 31243 31244 31245 31246 31247 31248 31249 31250 31251 31252 31253 31254 31255 31256 31257 31258 31259 31260 31261 31262 31263 31264 31265 31266 31267 31268 31269 31270 31271 31272 31273 31274 31275 31276 31277 31278 31279 31280 31281 31282 31283 31284 31285 31286 31287 31288 31289 31290 31291 31292 31293 31294 31295 31296 31297 31298 31299 31300 31301 31302 31303 31304 31305 31306 31307 31308 31309 31310 31311 31312 31313 31314 31315 31316 31317 31318 31319 31320 31321 31322 31323 31324 31325 31326 31327 31328 31329 31330 31331 31332 31333 31334 31335 31336 31337 31338 31339 31340 31341 31342 31343 31344 31345 31346 31347 31348 31349 31350 31351 31352 31353 31354 31355 31356 31357 31358 31359 31360 31361 31362 31363 31364 31365 31366 31367 31368 31369 31370 31371 31372 31373 31374 31375 31376 31377 31378 31379 31380 31381 31382 31383 31384 31385 31386 31387 31388 31389 31390 31391 31392 31393 31394 31395 31396 31397 31398 31399 31400 31401 31402 31403 31404 31405 31406 31407 31408 31409 31410 31411 31412 31413 31414 31415 31416 31417 31418 31419 31420 31421 31422 31423 31424 31425 31426 31427 31428 31429 31430 31431 31432 31433 31434 31435 31436 31437 31438 31439 31440 31441 31442 31443 31444 31445 31446 31447 31448 31449 31450 31451 31452 31453 31454 31455 31456 31457 31458 31459 31460 31461 31462 31463 31464 31465 31466 31467 31468 31469 31470 31471 31472 31473 31474 31475 31476 31477 31478 31479 31480 31481 31482 31483 31484 31485 31486 31487 31488 31489 31490 31491 31492 31493 31494 31495 31496 31497 31498 31499 31500 31501 31502 31503 31504 31505 31506 31507 31508 31509 31510 31511 31512 31513 31514 31515 31516 31517 31518 31519 31520 31521 31522 31523 31524 31525 31526 31527 31528 31529 31530 31531 31532 31533 31534 31535 31536 31537 31538 31539 31540 31541 31542 31543 31544 31545 31546 31547 31548 31549 31550 31551 31552 31553 31554 31555 31556 31557 31558 31559 31560 31561 31562 31563 31564 31565 31566 31567 31568 31569 31570 31571 31572 31573 31574 31575 31576 31577 31578 31579 31580 31581 31582 31583 31584 31585 31586 31587 31588 31589 31590 31591 31592 31593 31594 31595 31596 31597 31598 31599 31600 31601 31602 31603 31604 31605 31606 31607 31608 31609 31610 31611 31612 31613 31614 31615 31616 31617 31618 31619 31620 31621 31622 31623 31624 31625 31626 31627 31628 31629 31630 31631 31632 31633 31634 31635 31636 31637 31638 31639 31640 31641 31642 31643 31644 31645 31646 31647 31648 31649 31650 31651 31652 31653 31654 31655 31656 31657 31658 31659 31660 31661 31662 31663 31664 31665 31666 31667 31668 31669 31670 31671 31672 31673 31674 31675 31676 31677 31678 31679 31680 31681 31682 31683 31684 31685 31686 31687 31688 31689 31690 31691 31692 31693 31694 31695 31696 31697 31698 31699 31700 31701 31702 31703 31704 31705 31706 31707 31708 31709 31710 31711 31712 31713 31714 31715 31716 31717 31718 31719 31720 31721 31722 31723 31724 31725 31726 31727 31728 31729 31730 31731 31732 31733 31734 31735 31736 31737 31738 31739 31740 31741 31742 31743 31744 31745 31746 31747 31748 31749 31750 31751 31752 31753 31754 31755 31756 31757 31758 31759 31760 31761 31762 31763 31764 31765 31766 31767 31768 31769 31770 31771 31772 31773 31774 31775 31776 31777 31778 31779 31780 31781 31782 31783 31784 31785 31786 31787 31788 31789 31790 31791 31792 31793 31794 31795 31796 31797 31798 31799 31800 31801 31802 31803 31804 31805 31806 31807 31808 31809 31810 31811 31812 31813 31814 31815 31816 31817 31818 31819 31820 31821 31822 31823 31824 31825 31826 31827 31828 31829 31830 31831 31832 31833 31834 31835 31836 31837 31838 31839 31840 31841 31842 31843 31844 31845 31846 31847 31848 31849 31850 31851 31852 31853 31854 31855 31856 31857 31858 31859 31860 31861 31862 31863 31864 31865 31866 31867 31868 31869 31870 31871 31872 31873 31874 31875 31876 31877 31878 31879 31880 31881 31882 31883 31884 31885 31886 31887 31888 31889 31890 31891 31892 31893 31894 31895 31896 31897 31898 31899 31900 31901 31902 31903 31904 31905 31906 31907 31908 31909 31910 31911 31912 31913 31914 31915 31916 31917 31918 31919 31920 31921 31922 31923 31924 31925 31926 31927 31928 31929 31930 31931 31932 31933 31934 31935 31936 31937 31938 31939 31940 31941 31942 31943 31944 31945 31946 31947 31948 31949 31950 31951 31952 31953 31954 31955 31956 31957 31958 31959 31960 31961 31962 31963 31964 31965 31966 31967 31968 31969 31970 31971 31972 31973 31974 31975 31976 31977 31978 31979 31980 31981 31982 31983 31984 31985 31986 31987 31988 31989 31990 31991 31992 31993 31994 31995 31996 31997 31998 31999 32000 32001 32002 32003 32004 32005 32006 32007 32008 32009 32010 32011 32012 32013 32014 32015 32016 32017 32018 32019 32020 32021 32022 32023 32024 32025 32026 32027 32028 32029 32030 32031 32032 32033 32034 32035 32036 32037 32038 32039 32040 32041 32042 32043 32044 32045 32046 32047 32048 32049 32050 32051 32052 32053 32054 32055 32056 32057 32058 32059 32060 32061 32062 32063 32064 32065 32066 32067 32068 32069 32070 32071 32072 32073 32074 32075 32076 32077 32078 32079 32080 32081 32082 32083 32084 32085 32086 32087 32088 32089 32090 32091 32092 32093 32094 32095 32096 32097 32098 32099 32100 32101 32102 32103 32104 32105 32106 32107 32108 32109 32110 32111 32112 32113 32114 32115 32116 32117 32118 32119 32120 32121 32122 32123 32124 32125 32126 32127 32128 32129 32130 32131 32132 32133 32134 32135 32136 32137 32138 32139 32140 32141 32142 32143 32144 32145 32146 32147 32148 32149 32150 32151 32152 32153 32154 32155 32156 32157 32158 32159 32160 32161 32162 32163 32164 32165 32166 32167 32168 32169 32170 32171 32172 32173 32174 32175 32176 32177 32178 32179 32180 32181 32182 32183 32184 32185 32186 32187 32188 32189 32190 32191 32192 32193 32194 32195 32196 32197 32198 32199 32200 32201 32202 32203 32204 32205 32206 32207 32208 32209 32210 32211 32212 32213 32214 32215 32216 32217 32218 32219 32220 32221 32222 32223 32224 32225 32226 32227 32228 32229 32230 32231 32232 32233 32234 32235 32236 32237 32238 32239 32240 32241 32242 32243 32244 32245 32246 32247 32248 32249 32250 32251 32252 32253 32254 32255 32256 32257 32258 32259 32260 32261 32262 32263 32264 32265 32266 32267 32268 32269 32270 32271 32272 32273 32274 32275 32276 32277 32278 32279 32280 32281 32282 32283 32284 32285 32286 32287 32288 32289 32290 32291 32292 32293 32294 32295 32296 32297 32298 32299 32300 32301 32302 32303 32304 32305 32306 32307 32308 32309 32310 32311 32312 32313 32314 32315 32316 32317 32318 32319 32320 32321 32322 32323 32324 32325 32326 32327 32328 32329 32330 32331 32332 32333 32334 32335 32336 32337 32338 32339 32340 32341 32342 32343 32344 32345 32346 32347 32348 32349 32350 32351 32352 32353 32354 32355 32356 32357 32358 32359 32360 32361 32362 32363 32364 32365 32366 32367 32368 32369 32370 32371 32372 32373 32374 32375 32376 32377 32378 32379 32380 32381 32382 32383 32384 32385 32386 32387 32388 32389 32390 32391 32392 32393 32394 32395 32396 32397 32398 32399 32400 32401 32402 32403 32404 32405 32406 32407 32408 32409 32410 32411 32412 32413 32414 32415 32416 32417 32418 32419 32420 32421 32422 32423 32424 32425 32426 32427 32428 32429 32430 32431 32432 32433 32434 32435 32436 32437 32438 32439 32440 32441 32442 32443 32444 32445 32446 32447 32448 32449 32450 32451 32452 32453 32454 32455 32456 32457 32458 32459 32460 32461 32462 32463 32464 32465 32466 32467 32468 32469 32470 32471 32472 32473 32474 32475 32476 32477 32478 32479 32480 32481 32482 32483 32484 32485 32486 32487 32488 32489 32490 32491 32492 32493 32494 32495 32496 32497 32498 32499 32500 32501 32502 32503 32504 32505 32506 32507 32508 32509 32510 32511 32512 32513 32514 32515 32516 32517 32518 32519 32520 32521 32522 32523 32524 32525 32526 32527 32528 32529 32530 32531 32532 32533 32534 32535 32536 32537 32538 32539 32540 32541 32542 32543 32544 32545 32546 32547 32548 32549 32550 32551 32552 32553 32554 32555 32556 32557 32558 32559 32560 32561 32562 32563 32564 32565 32566 32567 32568 32569 32570 32571 32572 32573 32574 32575 32576 32577 32578 32579 32580 32581 32582 32583 32584 32585 32586 32587 32588 32589 32590 32591 32592 32593 32594 32595 32596 32597 32598 32599 32600 32601 32602 32603 32604 32605 32606 32607 32608 32609 32610 32611 32612 32613 32614 32615 32616 32617 32618 32619 32620 32621 32622 32623 32624 32625 32626 32627 32628 32629 32630 32631 32632 32633 32634 32635 32636 32637 32638 32639 32640 32641 32642 32643 32644 32645 32646 32647 32648 32649 32650 32651 32652 32653 32654 32655 32656 32657 32658 32659 32660 32661 32662 32663 32664 32665 32666 32667 32668 32669 32670 32671 32672 32673 32674 32675 32676 32677 32678 32679 32680 32681 32682 32683 32684 32685 32686 32687 32688 32689 32690 32691 32692 32693 32694 32695 32696 32697 32698 32699 32700 32701 32702 32703 32704 32705 32706 32707 32708 32709 32710 32711 32712 32713 32714 32715 32716 32717 32718 32719 32720 32721 32722 32723 32724 32725 32726 32727 32728 32729 32730 32731 32732 32733 32734 32735 32736 32737 32738 32739 32740 32741 32742 32743 32744 32745 32746 32747 32748 32749 32750 32751 32752 32753 32754 32755 32756 32757 32758 32759 32760 32761 32762 32763 32764 32765 32766 32767 32768 32769 32770 32771 32772 32773 32774 32775 32776 32777 32778 32779 32780 32781 32782 32783 32784 32785 32786 32787 32788 32789 32790 32791 32792 32793 32794 32795 32796 32797 32798 32799 32800 32801 32802 32803 32804 32805 32806 32807 32808 32809 32810 32811 32812 32813 32814 32815 32816 32817 32818 32819 32820 32821 32822 32823 32824 32825 32826 32827 32828 32829 32830 32831 32832 32833 32834 32835 32836 32837 32838 32839 32840 32841 32842 32843 32844 32845 32846 32847 32848 32849 32850 32851 32852 32853 32854 32855 32856 32857 32858 32859 32860 32861 32862 32863 32864 32865 32866 32867 32868 32869 32870 32871 32872 32873 32874 32875 32876 32877 32878 32879 32880 32881 32882 32883 32884 32885 32886 32887 32888 32889 32890 32891 32892 32893 32894 32895 32896 32897 32898 32899 32900 32901 32902 32903 32904 32905 32906 32907 32908 32909 32910 32911 32912 32913 32914 32915 32916 32917 32918 32919 32920 32921 32922 32923 32924 32925 32926 32927 32928 32929 32930 32931 32932 32933 32934 32935 32936 32937 32938 32939 32940 32941 32942 32943 32944 32945 32946 32947 32948 32949 32950 32951 32952 32953 32954 32955 32956 32957 32958 32959 32960 32961 32962 32963 32964 32965 32966 32967 32968 32969 32970 32971 32972 32973 32974 32975 32976 32977 32978 32979 32980 32981 32982 32983 32984 32985 32986 32987 32988 32989 32990 32991 32992 32993 32994 32995 32996 32997 32998 32999 33000 33001 33002 33003 33004 33005 33006 33007 33008 33009 33010 33011 33012 33013 33014 33015 33016 33017 33018 33019 33020 33021 33022 33023 33024 33025 33026 33027 33028 33029 33030 33031 33032 33033 33034 33035 33036 33037 33038 33039 33040 33041 33042 33043 33044 33045 33046 33047 33048 33049 33050 33051 33052 33053 33054 33055 33056 33057 33058 33059 33060 33061 33062 33063 33064 33065 33066 33067 33068 33069 33070 33071 33072 33073 33074 33075 33076 33077 33078 33079 33080 33081 33082 33083 33084 33085 33086 33087 33088 33089 33090 33091 33092 33093 33094 33095 33096 33097 33098 33099 33100 33101 33102 33103 33104 33105 33106 33107 33108 33109 33110 33111 33112 33113 33114 33115 33116 33117 33118 33119 33120 33121 33122 33123 33124 33125 33126 33127 33128 33129 33130 33131 33132 33133 33134 33135 33136 33137 33138 33139 33140 33141 33142 33143 33144 33145 33146 33147 33148 33149 33150 33151 33152 33153 33154 33155 33156 33157 33158 33159 33160 33161 33162 33163 33164 33165 33166 33167 33168 33169 33170 33171 33172 33173 33174 33175 33176 33177 33178 33179 33180 33181 33182 33183 33184 33185 33186 33187 33188 33189 33190 33191 33192 33193 33194 33195 33196 33197 33198 33199 33200 33201 33202 33203 33204 33205 33206 33207 33208 33209 33210 33211 33212 33213 33214 33215 33216 33217 33218 33219 33220 33221 33222 33223 33224 33225 33226 33227 33228 33229 33230 33231 33232 33233 33234 33235 33236 33237 33238 33239 33240 33241 33242 33243 33244 33245 33246 33247 33248 33249 33250 33251 33252 33253 33254 33255 33256 33257 33258 33259 33260 33261 33262 33263 33264 33265 33266 33267 33268 33269 33270 33271 33272 33273 33274 33275 33276 33277 33278 33279 33280 33281 33282 33283 33284 33285 33286 33287 33288 33289 33290 33291 33292 33293 33294 33295 33296 33297 33298 33299 33300 33301 33302 33303 33304 33305 33306 33307 33308 33309 33310 33311 33312 33313 33314 33315 33316 33317 33318 33319 33320 33321 33322 33323 33324 33325 33326 33327 33328 33329 33330 33331 33332 33333 33334 33335 33336 33337 33338 33339 33340 33341 33342 33343 33344 33345 33346 33347 33348 33349 33350 33351 33352 33353 33354 33355 33356 33357 33358 33359 33360 33361 33362 33363 33364 33365 33366 33367 33368 33369 33370 33371 33372 33373 33374 33375 33376 33377 33378 33379 33380 33381 33382 33383 33384 33385 33386 33387 33388 33389 33390 33391 33392 33393 33394 33395 33396 33397 33398 33399 33400 33401 33402 33403 33404 33405 33406 33407 33408 33409 33410 33411 33412 33413 33414 33415 33416 33417 33418 33419 33420 33421 33422 33423 33424 33425 33426 33427 33428 33429 33430 33431 33432 33433 33434 33435 33436 33437 33438 33439 33440 33441 33442 33443 33444 33445 33446 33447 33448 33449 33450 33451 33452 33453 33454 33455 33456 33457 33458 33459 33460 33461 33462 33463 33464 33465 33466 33467 33468 33469 33470 33471 33472 33473 33474 33475 33476 33477 33478 33479 33480 33481 33482 33483 33484 33485 33486 33487 33488 33489 33490 33491 33492 33493 33494 33495 33496 33497 33498 33499 33500 33501 33502 33503 33504 33505 33506 33507 33508 33509 33510 33511 33512 33513 33514 33515 33516 33517 33518 33519 33520 33521 33522 33523 33524 33525 33526 33527 33528 33529 33530 33531 33532 33533 33534 33535 33536 33537 33538 33539 33540 33541 33542 33543 33544 33545 33546 33547 33548 33549 33550 33551 33552 33553 33554 33555 33556 33557 33558 33559 33560 33561 33562 33563 33564 33565 33566 33567 33568 33569 33570 33571 33572 33573 33574 33575 33576 33577 33578 33579 33580 33581 33582 33583 33584 33585 33586 33587 33588 33589 33590 33591 33592 33593 33594 33595 33596 33597 33598 33599 33600 33601 33602 33603 33604 33605 33606 33607 33608 33609 33610 33611 33612 33613 33614 33615 33616 33617 33618 33619 33620 33621 33622 33623 33624 33625 33626 33627 33628 33629 33630 33631 33632 33633 33634 33635 33636 33637 33638 33639 33640 33641 33642 33643 33644 33645 33646 33647 33648 33649 33650 33651 33652 33653 33654 33655 33656 33657 33658 33659 33660 33661 33662 33663 33664 33665 33666 33667 33668 33669 33670 33671 33672 33673 33674 33675 33676 33677 33678 33679 33680 33681 33682 33683 33684 33685 33686 33687 33688 33689 33690 33691 33692 33693 33694 33695 33696 33697 33698 33699 33700 33701 33702 33703 33704 33705 33706 33707 33708 33709 33710 33711 33712 33713 33714 33715 33716 33717 33718 33719 33720 33721 33722 33723 33724 33725 33726 33727 33728 33729 33730 33731 33732 33733 33734 33735 33736 33737 33738 33739 33740 33741 33742 33743 33744 33745 33746 33747 33748 33749 33750 33751 33752 33753 33754 33755 33756 33757 33758 33759 33760 33761 33762 33763 33764 33765 33766 33767 33768 33769 33770 33771 33772 33773 33774 33775 33776 33777 33778 33779 33780 33781 33782 33783 33784 33785 33786 33787 33788 33789 33790 33791 33792 33793 33794 33795 33796 33797 33798 33799 33800 33801 33802 33803 33804 33805 33806 33807 33808 33809 33810 33811 33812 33813 33814 33815 33816 33817 33818 33819 33820 33821 33822 33823 33824 33825 33826 33827 33828 33829 33830 33831 33832 33833 33834 33835 33836 33837 33838 33839 33840 33841 33842 33843 33844 33845 33846 33847 33848 33849 33850 33851 33852 33853 33854 33855 33856 33857 33858 33859 33860 33861 33862 33863 33864 33865 33866 33867 33868 33869 33870 33871 33872 33873 33874 33875 33876 33877 33878 33879 33880 33881 33882 33883 33884 33885 33886 33887 33888 33889 33890 33891 33892 33893 33894 33895 33896 33897 33898 33899 33900 33901 33902 33903 33904 33905 33906 33907 33908 33909 33910 33911 33912 33913 33914 33915 33916 33917 33918 33919 33920 33921 33922 33923 33924 33925 33926 33927 33928 33929 33930 33931 33932 33933 33934 33935 33936 33937 33938 33939 33940 33941 33942 33943 33944 33945 33946 33947 33948 33949 33950 33951 33952 33953 33954 33955 33956 33957 33958 33959 33960 33961 33962 33963 33964 33965 33966 33967 33968 33969 33970 33971 33972 33973 33974 33975 33976 33977 33978 33979 33980 33981 33982 33983 33984 33985 33986 33987 33988 33989 33990 33991 33992 33993 33994 33995 33996 33997 33998 33999 34000 34001 34002 34003 34004 34005 34006 34007 34008 34009 34010 34011 34012 34013 34014 34015 34016 34017 34018 34019 34020 34021 34022 34023 34024 34025 34026 34027 34028 34029 34030 34031 34032 34033 34034 34035 34036 34037 34038 34039 34040 34041 34042 34043 34044 34045 34046 34047 34048 34049 34050 34051 34052 34053 34054 34055 34056 34057 34058 34059 34060 34061 34062 34063 34064 34065 34066 34067 34068 34069 34070 34071 34072 34073 34074 34075 34076 34077 34078 34079 34080 34081 34082 34083 34084 34085 34086 34087 34088 34089 34090 34091 34092 34093 34094 34095 34096 34097 34098 34099 34100 34101 34102 34103 34104 34105 34106 34107 34108 34109 34110 34111 34112 34113 34114 34115 34116 34117 34118 34119 34120 34121 34122 34123 34124 34125 34126 34127 34128 34129 34130 34131 34132 34133 34134 34135 34136 34137 34138 34139 34140 34141 34142 34143 34144 34145 34146 34147 34148 34149 34150 34151 34152 34153 34154 34155 34156 34157 34158 34159 34160 34161 34162 34163 34164 34165 34166 34167 34168 34169 34170 34171 34172 34173 34174 34175 34176 34177 34178 34179 34180 34181 34182 34183 34184 34185 34186 34187 34188 34189 34190 34191 34192 34193 34194 34195 34196 34197 34198 34199 34200 34201 34202 34203 34204 34205 34206 34207 34208 34209 34210 34211 34212 34213 34214 34215 34216 34217 34218 34219 34220 34221 34222 34223 34224 34225 34226 34227 34228 34229 34230 34231 34232 34233 34234 34235 34236 34237 34238 34239 34240 34241 34242 34243 34244 34245 34246 34247 34248 34249 34250 34251 34252 34253 34254 34255 34256 34257 34258 34259 34260 34261 34262 34263 34264 34265 34266 34267 34268 34269 34270 34271 34272 34273 34274 34275 34276 34277 34278 34279 34280 34281 34282 34283 34284 34285 34286 34287 34288 34289 34290 34291 34292 34293 34294 34295 34296 34297 34298 34299 34300 34301 34302 34303 34304 34305 34306 34307 34308 34309 34310 34311 34312 34313 34314 34315 34316 34317 34318 34319 34320 34321 34322 34323 34324 34325 34326 34327 34328 34329 34330 34331 34332 34333 34334 34335 34336 34337 34338 34339 34340 34341 34342 34343 34344 34345 34346 34347 34348 34349 34350 34351 34352 34353 34354 34355 34356 34357 34358 34359 34360 34361 34362 34363 34364 34365 34366 34367 34368 34369 34370 34371 34372 34373 34374 34375 34376 34377 34378 34379 34380 34381 34382 34383 34384 34385 34386 34387 34388 34389 34390 34391 34392 34393 34394 34395 34396 34397 34398 34399 34400 34401 34402 34403 34404 34405 34406 34407 34408 34409 34410 34411 34412 34413 34414 34415 34416 34417 34418 34419 34420 34421 34422 34423 34424 34425 34426 34427 34428 34429 34430 34431 34432 34433 34434 34435 34436 34437 34438 34439 34440 34441 34442 34443 34444 34445 34446 34447 34448 34449 34450 34451 34452 34453 34454 34455 34456 34457 34458 34459 34460 34461 34462 34463 34464 34465 34466 34467 34468 34469 34470 34471 34472 34473 34474 34475 34476 34477 34478 34479 34480 34481 34482 34483 34484 34485 34486 34487 34488 34489 34490 34491 34492 34493 34494 34495 34496 34497 34498 34499 34500 34501 34502 34503 34504 34505 34506 34507 34508 34509 34510 34511 34512 34513 34514 34515 34516 34517 34518 34519 34520 34521 34522 34523 34524 34525 34526 34527 34528 34529 34530 34531 34532 34533 34534 34535 34536 34537 34538 34539 34540 34541 34542 34543 34544 34545 34546 34547 34548 34549 34550 34551 34552 34553 34554 34555 34556 34557 34558 34559 34560 34561 34562 34563 34564 34565 34566 34567 34568 34569 34570 34571 34572 34573 34574 34575 34576 34577 34578 34579 34580 34581 34582 34583 34584 34585 34586 34587 34588 34589 34590 34591 34592 34593 34594 34595 34596 34597 34598 34599 34600 34601 34602 34603 34604 34605 34606 34607 34608 34609 34610 34611 34612 34613 34614 34615 34616 34617 34618 34619 34620 34621 34622 34623 34624 34625 34626 34627 34628 34629 34630 34631 34632 34633 34634 34635 34636 34637 34638 34639 34640 34641 34642 34643 34644 34645 34646 34647 34648 34649 34650 34651 34652 34653 34654 34655 34656 34657 34658 34659 34660 34661 34662 34663 34664 34665 34666 34667 34668 34669 34670 34671 34672 34673 34674 34675 34676 34677 34678 34679 34680 34681 34682 34683 34684 34685 34686 34687 34688 34689 34690 34691 34692 34693 34694 34695 34696 34697 34698 34699 34700 34701 34702 34703 34704 34705 34706 34707 34708 34709 34710 34711 34712 34713 34714 34715 34716 34717 34718 34719 34720 34721 34722 34723 34724 34725 34726 34727 34728 34729 34730 34731 34732 34733 34734 34735 34736 34737 34738 34739 34740 34741 34742 34743 34744 34745 34746 34747 34748 34749 34750 34751 34752 34753 34754 34755 34756 34757 34758 34759 34760 34761 34762 34763 34764 34765 34766 34767 34768 34769 34770 34771 34772 34773 34774 34775 34776 34777 34778 34779 34780 34781 34782 34783 34784 34785 34786 34787 34788 34789 34790 34791 34792 34793 34794 34795 34796 34797 34798 34799 34800 34801 34802 34803 34804 34805 34806 34807 34808 34809 34810 34811 34812 34813 34814 34815 34816 34817 34818 34819 34820 34821 34822 34823 34824 34825 34826 34827 34828 34829 34830 34831 34832 34833 34834 34835 34836 34837 34838 34839 34840 34841 34842 34843 34844 34845 34846 34847 34848 34849 34850 34851 34852 34853 34854 34855 34856 34857 34858 34859 34860 34861 34862 34863 34864 34865 34866 34867 34868 34869 34870 34871 34872 34873 34874 34875 34876 34877 34878 34879 34880 34881 34882 34883 34884 34885 34886 34887 34888 34889 34890 34891 34892 34893 34894 34895 34896 34897 34898 34899 34900 34901 34902 34903 34904 34905 34906 34907 34908 34909 34910 34911 34912 34913 34914 34915 34916 34917 34918 34919 34920 34921 34922 34923 34924 34925 34926 34927 34928 34929 34930 34931 34932 34933 34934 34935 34936 34937 34938 34939 34940 34941 34942 34943 34944 34945 34946 34947 34948 34949 34950 34951 34952 34953 34954 34955 34956 34957 34958 34959 34960 34961 34962 34963 34964 34965 34966 34967 34968 34969 34970 34971 34972 34973 34974 34975 34976 34977 34978 34979 34980 34981 34982 34983 34984 34985 34986 34987 34988 34989 34990 34991 34992 34993 34994 34995 34996 34997 34998 34999 35000 35001 35002 35003 35004 35005 35006 35007 35008 35009 35010 35011 35012 35013 35014 35015 35016 35017 35018 35019 35020 35021 35022 35023 35024 35025 35026 35027 35028 35029 35030 35031 35032 35033 35034 35035 35036 35037 35038 35039 35040 35041 35042 35043 35044 35045 35046 35047 35048 35049 35050 35051 35052 35053 35054 35055 35056 35057 35058 35059 35060 35061 35062 35063 35064 35065 35066 35067 35068 35069 35070 35071 35072 35073 35074 35075 35076 35077 35078 35079 35080 35081 35082 35083 35084 35085 35086 35087 35088 35089 35090 35091 35092 35093 35094 35095 35096 35097 35098 35099 35100 35101 35102 35103 35104 35105 35106 35107 35108 35109 35110 35111 35112 35113 35114 35115 35116 35117 35118 35119 35120 35121 35122 35123 35124 35125 35126 35127 35128 35129 35130 35131 35132 35133 35134 35135 35136 35137 35138 35139 35140 35141 35142 35143 35144 35145 35146 35147 35148 35149 35150 35151 35152 35153 35154 35155 35156 35157 35158 35159 35160 35161 35162 35163 35164 35165 35166 35167 35168 35169 35170 35171 35172 35173 35174 35175 35176 35177 35178 35179 35180 35181 35182 35183 35184 35185 35186 35187 35188 35189 35190 35191 35192 35193 35194 35195 35196 35197 35198 35199 35200 35201 35202 35203 35204 35205 35206 35207 35208 35209 35210 35211 35212 35213 35214 35215 35216 35217 35218 35219 35220 35221 35222 35223 35224 35225 35226 35227 35228 35229 35230 35231 35232 35233 35234 35235 35236 35237 35238 35239 35240 35241 35242 35243 35244 35245 35246 35247 35248 35249 35250 35251 35252 35253 35254 35255 35256 35257 35258 35259 35260 35261 35262 35263 35264 35265 35266 35267 35268 35269 35270 35271 35272 35273 35274 35275 35276 35277 35278 35279 35280 35281 35282 35283 35284 35285 35286 35287 35288 35289 35290 35291 35292 35293 35294 35295 35296 35297 35298 35299 35300 35301 35302 35303 35304 35305 35306 35307 35308 35309 35310 35311 35312 35313 35314 35315 35316 35317 35318 35319 35320 35321 35322 35323 35324 35325 35326 35327 35328 35329 35330 35331 35332 35333 35334 35335 35336 35337 35338 35339 35340 35341 35342 35343 35344 35345 35346 35347 35348 35349 35350 35351 35352 35353 35354 35355 35356 35357 35358 35359 35360 35361 35362 35363 35364 35365 35366 35367 35368 35369 35370 35371 35372 35373 35374 35375 35376 35377 35378 35379 35380 35381 35382 35383 35384 35385 35386 35387 35388 35389 35390 35391 35392 35393 35394 35395 35396 35397 35398 35399 35400 35401 35402 35403 35404 35405 35406 35407 35408 35409 35410 35411 35412 35413 35414 35415 35416 35417 35418 35419 35420 35421 35422 35423 35424 35425 35426 35427 35428 35429 35430 35431 35432 35433 35434 35435 35436 35437 35438 35439 35440 35441 35442 35443 35444 35445 35446 35447 35448 35449 35450 35451 35452 35453 35454 35455 35456 35457 35458 35459 35460 35461 35462 35463 35464 35465 35466 35467 35468 35469 35470 35471 35472 35473 35474 35475 35476 35477 35478 35479 35480 35481 35482 35483 35484 35485 35486 35487 35488 35489 35490 35491 35492 35493 35494 35495 35496 35497 35498 35499 35500 35501 35502 35503 35504 35505 35506 35507 35508 35509 35510 35511 35512 35513 35514 35515 35516 35517 35518 35519 35520 35521 35522 35523 35524 35525 35526 35527 35528 35529 35530 35531 35532 35533 35534 35535 35536 35537 35538 35539 35540 35541 35542 35543 35544 35545 35546 35547 35548 35549 35550 35551 35552 35553 35554 35555 35556 35557 35558 35559 35560 35561 35562 35563 35564 35565 35566 35567 35568 35569 35570 35571 35572 35573 35574 35575 35576 35577 35578 35579 35580 35581 35582 35583 35584 35585 35586 35587 35588 35589 35590 35591 35592 35593 35594 35595 35596 35597 35598 35599 35600 35601 35602 35603 35604 35605 35606 35607 35608 35609 35610 35611 35612 35613 35614 35615 35616 35617 35618 35619 35620 35621 35622 35623 35624 35625 35626 35627 35628 35629 35630 35631 35632 35633 35634 35635 35636 35637 35638 35639 35640 35641 35642 35643 35644 35645 35646 35647 35648 35649 35650 35651 35652 35653 35654 35655 35656 35657 35658 35659 35660 35661 35662 35663 35664 35665 35666 35667 35668 35669 35670 35671 35672 35673 35674 35675 35676 35677 35678 35679 35680 35681 35682 35683 35684 35685 35686 35687 35688 35689 35690 35691 35692 35693 35694 35695 35696 35697 35698 35699 35700 35701 35702 35703 35704 35705 35706 35707 35708 35709 35710 35711 35712 35713 35714 35715 35716 35717 35718 35719 35720 35721 35722 35723 35724 35725 35726 35727 35728 35729 35730 35731 35732 35733 35734 35735 35736 35737 35738 35739 35740 35741 35742 35743 35744 35745 35746 35747 35748 35749 35750 35751 35752 35753 35754 35755 35756 35757 35758 35759 35760 35761 35762 35763 35764 35765 35766 35767 35768 35769 35770 35771 35772 35773 35774 35775 35776 35777 35778 35779 35780 35781 35782 35783 35784 35785 35786 35787 35788 35789 35790 35791 35792 35793 35794 35795 35796 35797 35798 35799 35800 35801 35802 35803 35804 35805 35806 35807 35808 35809 35810 35811 35812 35813 35814 35815 35816 35817 35818 35819 35820 35821 35822 35823 35824 35825 35826 35827 35828 35829 35830 35831 35832 35833 35834 35835 35836 35837 35838 35839 35840 35841 35842 35843 35844 35845 35846 35847 35848 35849 35850 35851 35852 35853 35854 35855 35856 35857 35858 35859 35860 35861 35862 35863 35864 35865 35866 35867 35868 35869 35870 35871 35872 35873 35874 35875 35876 35877 35878 35879 35880 35881 35882 35883 35884 35885 35886 35887 35888 35889 35890 35891 35892 35893 35894 35895 35896 35897 35898 35899 35900 35901 35902 35903 35904 35905 35906 35907 35908 35909 35910 35911 35912 35913 35914 35915 35916 35917 35918 35919 35920 35921 35922 35923 35924 35925 35926 35927 35928 35929 35930 35931 35932 35933 35934 35935 35936 35937 35938 35939 35940 35941 35942 35943 35944 35945 35946 35947 35948 35949 35950 35951 35952 35953 35954 35955 35956 35957 35958 35959 35960 35961 35962 35963 35964 35965 35966 35967 35968 35969 35970 35971 35972 35973 35974 35975 35976 35977 35978 35979 35980 35981 35982 35983 35984 35985 35986 35987 35988 35989 35990 35991 35992 35993 35994 35995 35996 35997 35998 35999 36000 36001 36002 36003 36004 36005 36006 36007 36008 36009 36010 36011 36012 36013 36014 36015 36016 36017 36018 36019 36020 36021 36022 36023 36024 36025 36026 36027 36028 36029 36030 36031 36032 36033 36034 36035 36036 36037 36038 36039 36040 36041 36042 36043 36044 36045 36046 36047 36048 36049 36050 36051 36052 36053 36054 36055 36056 36057 36058 36059 36060 36061 36062 36063 36064 36065 36066 36067 36068 36069 36070 36071 36072 36073 36074 36075 36076 36077 36078 36079 36080 36081 36082 36083 36084 36085 36086 36087 36088 36089 36090 36091 36092 36093 36094 36095 36096 36097 36098 36099 36100 36101 36102 36103 36104 36105 36106 36107 36108 36109 36110 36111 36112 36113 36114 36115 36116 36117 36118 36119 36120 36121 36122 36123 36124 36125 36126 36127 36128 36129 36130 36131 36132 36133 36134 36135 36136 36137 36138 36139 36140 36141 36142 36143 36144 36145 36146 36147 36148 36149 36150 36151 36152 36153 36154 36155 36156 36157 36158 36159 36160 36161 36162 36163 36164 36165 36166 36167 36168 36169 36170 36171 36172 36173 36174 36175 36176 36177 36178 36179 36180 36181 36182 36183 36184 36185 36186 36187 36188 36189 36190 36191 36192 36193 36194 36195 36196 36197 36198 36199 36200 36201 36202 36203 36204 36205 36206 36207 36208 36209 36210 36211 36212 36213 36214 36215 36216 36217 36218 36219 36220 36221 36222 36223 36224 36225 36226 36227 36228 36229 36230 36231 36232 36233 36234 36235 36236 36237 36238 36239 36240 36241 36242 36243 36244 36245 36246 36247 36248 36249 36250 36251 36252 36253 36254 36255 36256 36257 36258 36259 36260 36261 36262 36263 36264 36265 36266 36267 36268 36269 36270 36271 36272 36273 36274 36275 36276 36277 36278 36279 36280 36281 36282 36283 36284 36285 36286 36287 36288 36289 36290 36291 36292 36293 36294 36295 36296 36297 36298 36299 36300 36301 36302 36303 36304 36305 36306 36307 36308 36309 36310 36311 36312 36313 36314 36315 36316 36317 36318 36319 36320 36321 36322 36323 36324 36325 36326 36327 36328 36329 36330 36331 36332 36333 36334 36335 36336 36337 36338 36339 36340 36341 36342 36343 36344 36345 36346 36347 36348 36349 36350 36351 36352 36353 36354 36355 36356 36357 36358 36359 36360 36361 36362 36363 36364 36365 36366 36367 36368 36369 36370 36371 36372 36373 36374 36375 36376 36377 36378 36379 36380 36381 36382 36383 36384 36385 36386 36387 36388 36389 36390 36391 36392 36393 36394 36395 36396 36397 36398 36399 36400 36401 36402 36403 36404 36405 36406 36407 36408 36409 36410 36411 36412 36413 36414 36415 36416 36417 36418 36419 36420 36421 36422 36423 36424 36425 36426 36427 36428 36429 36430 36431 36432 36433 36434 36435 36436 36437 36438 36439 36440 36441 36442 36443 36444 36445 36446 36447 36448 36449 36450 36451 36452 36453 36454 36455 36456 36457 36458 36459 36460 36461 36462 36463 36464 36465 36466 36467 36468 36469 36470 36471 36472 36473 36474 36475 36476 36477 36478 36479 36480 36481 36482 36483 36484 36485 36486 36487 36488 36489 36490 36491 36492 36493 36494 36495 36496 36497 36498 36499 36500 36501 36502 36503 36504 36505 36506 36507 36508 36509 36510 36511 36512 36513 36514 36515 36516 36517 36518 36519 36520 36521 36522 36523 36524 36525 36526 36527 36528 36529 36530 36531 36532 36533 36534 36535 36536 36537 36538 36539 36540 36541 36542 36543 36544 36545 36546 36547 36548 36549 36550 36551 36552 36553 36554 36555 36556 36557 36558 36559 36560 36561 36562 36563 36564 36565 36566 36567 36568 36569 36570 36571 36572 36573 36574 36575 36576 36577 36578 36579 36580 36581 36582 36583 36584 36585 36586 36587 36588 36589 36590 36591 36592 36593 36594 36595 36596 36597 36598 36599 36600 36601 36602 36603 36604 36605 36606 36607 36608 36609 36610 36611 36612 36613 36614 36615 36616 36617 36618 36619 36620 36621 36622 36623 36624 36625 36626 36627 36628 36629 36630 36631 36632 36633 36634 36635 36636 36637 36638 36639 36640 36641 36642 36643 36644 36645 36646 36647 36648 36649 36650 36651 36652 36653 36654 36655 36656 36657 36658 36659 36660 36661 36662 36663 36664 36665 36666 36667 36668 36669 36670 36671 36672 36673 36674 36675 36676 36677 36678 36679 36680 36681 36682 36683 36684 36685 36686 36687 36688 36689 36690 36691 36692 36693 36694 36695 36696 36697 36698 36699 36700 36701 36702 36703 36704 36705 36706 36707 36708 36709 36710 36711 36712 36713 36714 36715 36716 36717 36718 36719 36720 36721 36722 36723 36724 36725 36726 36727 36728 36729 36730 36731 36732 36733 36734 36735 36736 36737 36738 36739 36740 36741 36742 36743 36744 36745 36746 36747 36748 36749 36750 36751 36752 36753 36754 36755 36756 36757 36758 36759 36760 36761 36762 36763 36764 36765 36766 36767 36768 36769 36770 36771 36772 36773 36774 36775 36776 36777 36778 36779 36780 36781 36782 36783 36784 36785 36786 36787 36788 36789 36790 36791 36792 36793 36794 36795 36796 36797 36798 36799 36800 36801 36802 36803 36804 36805 36806 36807 36808 36809 36810 36811 36812 36813 36814 36815 36816 36817 36818 36819 36820 36821 36822 36823 36824 36825 36826 36827 36828 36829 36830 36831 36832 36833 36834 36835 36836 36837 36838 36839 36840 36841 36842 36843 36844 36845 36846 36847 36848 36849 36850 36851 36852 36853 36854 36855 36856 36857 36858 36859 36860 36861 36862 36863 36864 36865 36866 36867 36868 36869 36870 36871 36872 36873 36874 36875 36876 36877 36878 36879 36880 36881 36882 36883 36884 36885 36886 36887 36888 36889 36890 36891 36892 36893 36894 36895 36896 36897 36898 36899 36900 36901 36902 36903 36904 36905 36906 36907 36908 36909 36910 36911 36912 36913 36914 36915 36916 36917 36918 36919 36920 36921 36922 36923 36924 36925 36926 36927 36928 36929 36930 36931 36932 36933 36934 36935 36936 36937 36938 36939 36940 36941 36942 36943 36944 36945 36946 36947 36948 36949 36950 36951 36952 36953 36954 36955 36956 36957 36958 36959 36960 36961 36962 36963 36964 36965 36966 36967 36968 36969 36970 36971 36972 36973 36974 36975 36976 36977 36978 36979 36980 36981 36982 36983 36984 36985 36986 36987 36988 36989 36990 36991 36992 36993 36994 36995 36996 36997 36998 36999 37000 37001 37002 37003 37004 37005 37006 37007 37008 37009 37010 37011 37012 37013 37014 37015 37016 37017 37018 37019 37020 37021 37022 37023 37024 37025 37026 37027 37028 37029 37030 37031 37032 37033 37034 37035 37036 37037 37038 37039 37040 37041 37042 37043 37044 37045 37046 37047 37048 37049 37050 37051 37052 37053 37054 37055 37056 37057 37058 37059 37060 37061 37062 37063 37064 37065 37066 37067 37068 37069 37070 37071 37072 37073 37074 37075 37076 37077 37078 37079 37080 37081 37082 37083 37084 37085 37086 37087 37088 37089 37090 37091 37092 37093 37094 37095 37096 37097 37098 37099 37100 37101 37102 37103 37104 37105 37106 37107 37108 37109 37110 37111 37112 37113 37114 37115 37116 37117 37118 37119 37120 37121 37122 37123 37124 37125 37126 37127 37128 37129 37130 37131 37132 37133 37134 37135 37136 37137 37138 37139 37140 37141 37142 37143 37144 37145 37146 37147 37148 37149 37150 37151 37152 37153 37154 37155 37156 37157 37158 37159 37160 37161 37162 37163 37164 37165 37166 37167 37168 37169 37170 37171 37172 37173 37174 37175 37176 37177 37178 37179 37180 37181 37182 37183 37184 37185 37186 37187 37188 37189 37190 37191 37192 37193 37194 37195 37196 37197 37198 37199 37200 37201 37202 37203 37204 37205 37206 37207 37208 37209 37210 37211 37212 37213 37214 37215 37216 37217 37218 37219 37220 37221 37222 37223 37224 37225 37226 37227 37228 37229 37230 37231 37232 37233 37234 37235 37236 37237 37238 37239 37240 37241 37242 37243 37244 37245 37246 37247 37248 37249 37250 37251 37252 37253 37254 37255 37256 37257 37258 37259 37260 37261 37262 37263 37264 37265 37266 37267 37268 37269 37270 37271 37272 37273 37274 37275 37276 37277 37278 37279 37280 37281 37282 37283 37284 37285 37286 37287 37288 37289 37290 37291 37292 37293 37294 37295 37296 37297 37298 37299 37300 37301 37302 37303 37304 37305 37306 37307 37308 37309 37310 37311 37312 37313 37314 37315 37316 37317 37318 37319 37320 37321 37322 37323 37324 37325 37326 37327 37328 37329 37330 37331 37332 37333 37334 37335 37336 37337 37338 37339 37340 37341 37342 37343 37344 37345 37346 37347 37348 37349 37350 37351 37352 37353 37354 37355 37356 37357 37358 37359 37360 37361 37362 37363 37364 37365 37366 37367 37368 37369 37370 37371 37372 37373 37374 37375 37376 37377 37378 37379 37380 37381 37382 37383 37384 37385 37386 37387 37388 37389 37390 37391 37392 37393 37394 37395 37396 37397 37398 37399 37400 37401 37402 37403 37404 37405 37406 37407 37408 37409 37410 37411 37412 37413 37414 37415 37416 37417 37418 37419 37420 37421 37422 37423 37424 37425 37426 37427 37428 37429 37430 37431 37432 37433 37434 37435 37436 37437 37438 37439 37440 37441 37442 37443 37444 37445 37446 37447 37448 37449 37450 37451 37452 37453 37454 37455 37456 37457 37458 37459 37460 37461 37462 37463 37464 37465 37466 37467 37468 37469 37470 37471 37472 37473 37474 37475 37476 37477 37478 37479 37480 37481 37482 37483 37484 37485 37486 37487 37488 37489 37490 37491 37492 37493 37494 37495 37496 37497 37498 37499 37500 37501 37502 37503 37504 37505 37506 37507 37508 37509 37510 37511 37512 37513 37514 37515 37516 37517 37518 37519 37520 37521 37522 37523 37524 37525 37526 37527 37528 37529 37530 37531 37532 37533 37534 37535 37536 37537 37538 37539 37540 37541 37542 37543 37544 37545 37546 37547 37548 37549 37550 37551 37552 37553 37554 37555 37556 37557 37558 37559 37560 37561 37562 37563 37564 37565 37566 37567 37568 37569 37570 37571 37572 37573 37574 37575 37576 37577 37578 37579 37580 37581 37582 37583 37584 37585 37586 37587 37588 37589 37590 37591 37592 37593 37594 37595 37596 37597 37598 37599 37600 37601 37602 37603 37604 37605 37606 37607 37608 37609 37610 37611 37612 37613 37614 37615 37616 37617 37618 37619 37620 37621 37622 37623 37624 37625 37626 37627 37628 37629 37630 37631 37632 37633 37634 37635 37636 37637 37638 37639 37640 37641 37642 37643 37644 37645 37646 37647 37648 37649 37650 37651 37652 37653 37654 37655 37656 37657 37658 37659 37660 37661 37662 37663 37664 37665 37666 37667 37668 37669 37670 37671 37672 37673 37674 37675 37676 37677 37678 37679 37680 37681 37682 37683 37684 37685 37686 37687 37688 37689 37690 37691 37692 37693 37694 37695 37696 37697 37698 37699 37700 37701 37702 37703 37704 37705 37706 37707 37708 37709 37710 37711 37712 37713 37714 37715 37716 37717 37718 37719 37720 37721 37722 37723 37724 37725 37726 37727 37728 37729 37730 37731 37732 37733 37734 37735 37736 37737 37738 37739 37740 37741 37742 37743 37744 37745 37746 37747 37748 37749 37750 37751 37752 37753 37754 37755 37756 37757 37758 37759 37760 37761 37762 37763 37764 37765 37766 37767 37768 37769 37770 37771 37772 37773 37774 37775 37776 37777 37778 37779 37780 37781 37782 37783 37784 37785 37786 37787 37788 37789 37790 37791 37792 37793 37794 37795 37796 37797 37798 37799 37800 37801 37802 37803 37804 37805 37806 37807 37808 37809 37810 37811 37812 37813 37814 37815 37816 37817 37818 37819 37820 37821 37822 37823 37824 37825 37826 37827 37828 37829 37830 37831 37832 37833 37834 37835 37836 37837 37838 37839 37840 37841 37842 37843 37844 37845 37846 37847 37848 37849 37850 37851 37852 37853 37854 37855 37856 37857 37858 37859 37860 37861 37862 37863 37864 37865 37866 37867 37868 37869 37870 37871 37872 37873 37874 37875 37876 37877 37878 37879 37880 37881 37882 37883 37884 37885 37886 37887 37888 37889 37890 37891 37892 37893 37894 37895 37896 37897 37898 37899 37900 37901 37902 37903 37904 37905 37906 37907 37908 37909 37910 37911 37912 37913 37914 37915 37916 37917 37918 37919 37920 37921 37922 37923 37924 37925 37926 37927 37928 37929 37930 37931 37932 37933 37934 37935 37936 37937 37938 37939 37940 37941 37942 37943 37944 37945 37946 37947 37948 37949 37950 37951 37952 37953 37954 37955 37956 37957 37958 37959 37960 37961 37962 37963 37964 37965 37966 37967 37968 37969 37970 37971 37972 37973 37974 37975 37976 37977 37978 37979 37980 37981 37982 37983 37984 37985 37986 37987 37988 37989 37990 37991 37992 37993 37994 37995 37996 37997 37998 37999 38000 38001 38002 38003 38004 38005 38006 38007 38008 38009 38010 38011 38012 38013 38014 38015 38016 38017 38018 38019 38020 38021 38022 38023 38024 38025 38026 38027 38028 38029 38030 38031 38032 38033 38034 38035 38036 38037 38038 38039 38040 38041 38042 38043 38044 38045 38046 38047 38048 38049 38050 38051 38052 38053 38054 38055 38056 38057 38058 38059 38060 38061 38062 38063 38064 38065 38066 38067 38068 38069 38070 38071 38072 38073 38074 38075 38076 38077 38078 38079 38080 38081 38082 38083 38084 38085 38086 38087 38088 38089 38090 38091 38092 38093 38094 38095 38096 38097 38098 38099 38100 38101 38102 38103 38104 38105 38106 38107 38108 38109 38110 38111 38112 38113 38114 38115 38116 38117 38118 38119 38120 38121 38122 38123 38124 38125 38126 38127 38128 38129 38130 38131 38132 38133 38134 38135 38136 38137 38138 38139 38140 38141 38142 38143 38144 38145 38146 38147 38148 38149 38150 38151 38152 38153 38154 38155 38156 38157 38158 38159 38160 38161 38162 38163 38164 38165 38166 38167 38168 38169 38170 38171 38172 38173 38174 38175 38176 38177 38178 38179 38180 38181 38182 38183 38184 38185 38186 38187 38188 38189 38190 38191 38192 38193 38194 38195 38196 38197 38198 38199 38200 38201 38202 38203 38204 38205 38206 38207 38208 38209 38210 38211 38212 38213 38214 38215 38216 38217 38218 38219 38220 38221 38222 38223 38224 38225 38226 38227 38228 38229 38230 38231 38232 38233 38234 38235 38236 38237 38238 38239 38240 38241 38242 38243 38244 38245 38246 38247 38248 38249 38250 38251 38252 38253 38254 38255 38256 38257 38258 38259 38260 38261 38262 38263 38264 38265 38266 38267 38268 38269 38270 38271 38272 38273 38274 38275 38276 38277 38278 38279 38280 38281 38282 38283 38284 38285 38286 38287 38288 38289 38290 38291 38292 38293 38294 38295 38296 38297 38298 38299 38300 38301 38302 38303 38304 38305 38306 38307 38308 38309 38310 38311 38312 38313 38314 38315 38316 38317 38318 38319 38320 38321 38322 38323 38324 38325 38326 38327 38328 38329 38330 38331 38332 38333 38334 38335 38336 38337 38338 38339 38340 38341 38342 38343 38344 38345 38346 38347 38348 38349 38350 38351 38352 38353 38354 38355 38356 38357 38358 38359 38360 38361 38362 38363 38364 38365 38366 38367 38368 38369 38370 38371 38372 38373 38374 38375 38376 38377 38378 38379 38380 38381 38382 38383 38384 38385 38386 38387 38388 38389 38390 38391 38392 38393 38394 38395 38396 38397 38398 38399 38400 38401 38402 38403 38404 38405 38406 38407 38408 38409 38410 38411 38412 38413 38414 38415 38416 38417 38418 38419 38420 38421 38422 38423 38424 38425 38426 38427 38428 38429 38430 38431 38432 38433 38434 38435 38436 38437 38438 38439 38440 38441 38442 38443 38444 38445 38446 38447 38448 38449 38450 38451 38452 38453 38454 38455 38456 38457 38458 38459 38460 38461 38462 38463 38464 38465 38466 38467 38468 38469 38470 38471 38472 38473 38474 38475 38476 38477 38478 38479 38480 38481 38482 38483 38484 38485 38486 38487 38488 38489 38490 38491 38492 38493 38494 38495 38496 38497 38498 38499 38500 38501 38502 38503 38504 38505 38506 38507 38508 38509 38510 38511 38512 38513 38514 38515 38516 38517 38518 38519 38520 38521 38522 38523 38524 38525 38526 38527 38528 38529 38530 38531 38532 38533 38534 38535 38536 38537 38538 38539 38540 38541 38542 38543 38544 38545 38546 38547 38548 38549 38550 38551 38552 38553 38554 38555 38556 38557 38558 38559 38560 38561 38562 38563 38564 38565 38566 38567 38568 38569 38570 38571 38572 38573 38574 38575 38576 38577 38578 38579 38580 38581 38582 38583 38584 38585 38586 38587 38588 38589 38590 38591 38592 38593 38594 38595 38596 38597 38598 38599 38600 38601 38602 38603 38604 38605 38606 38607 38608 38609 38610 38611 38612 38613 38614 38615 38616 38617 38618 38619 38620 38621 38622 38623 38624 38625 38626 38627 38628 38629 38630 38631 38632 38633 38634 38635 38636 38637 38638 38639 38640 38641 38642 38643 38644 38645 38646 38647 38648 38649 38650 38651 38652 38653 38654 38655 38656 38657 38658 38659 38660 38661 38662 38663 38664 38665 38666 38667 38668 38669 38670 38671 38672 38673 38674 38675 38676 38677 38678 38679 38680 38681 38682 38683 38684 38685 38686 38687 38688 38689 38690 38691 38692 38693 38694 38695 38696 38697 38698 38699 38700 38701 38702 38703 38704 38705 38706 38707 38708 38709 38710 38711 38712 38713 38714 38715 38716 38717 38718 38719 38720 38721 38722 38723 38724 38725 38726 38727 38728 38729 38730 38731 38732 38733 38734 38735 38736 38737 38738 38739 38740 38741 38742 38743 38744 38745 38746 38747 38748 38749 38750 38751 38752 38753 38754 38755 38756 38757 38758 38759 38760 38761 38762 38763 38764 38765 38766 38767 38768 38769 38770 38771 38772 38773 38774 38775 38776 38777 38778 38779 38780 38781 38782 38783 38784 38785 38786 38787 38788 38789 38790 38791 38792 38793 38794 38795 38796 38797 38798 38799 38800 38801 38802 38803 38804 38805 38806 38807 38808 38809 38810 38811 38812 38813 38814 38815 38816 38817 38818 38819 38820 38821 38822 38823 38824 38825 38826 38827 38828 38829 38830 38831 38832 38833 38834 38835 38836 38837 38838 38839 38840 38841 38842 38843 38844 38845 38846 38847 38848 38849 38850 38851 38852 38853 38854 38855 38856 38857 38858 38859 38860 38861 38862 38863 38864 38865 38866 38867 38868 38869 38870 38871 38872 38873 38874 38875 38876 38877 38878 38879 38880 38881 38882 38883 38884 38885 38886 38887 38888 38889 38890 38891 38892 38893 38894 38895 38896 38897 38898 38899 38900 38901 38902 38903 38904 38905 38906 38907 38908 38909 38910 38911 38912 38913 38914 38915 38916 38917 38918 38919 38920 38921 38922 38923 38924 38925 38926 38927 38928 38929 38930 38931 38932 38933 38934 38935 38936 38937 38938 38939 38940 38941 38942 38943 38944 38945 38946 38947 38948 38949 38950 38951 38952 38953 38954 38955 38956 38957 38958 38959 38960 38961 38962 38963 38964 38965 38966 38967 38968 38969 38970 38971 38972 38973 38974 38975 38976 38977 38978 38979 38980 38981 38982 38983 38984 38985 38986 38987 38988 38989 38990 38991 38992 38993 38994 38995 38996 38997 38998 38999 39000 39001 39002 39003 39004 39005 39006 39007 39008 39009 39010 39011 39012 39013 39014 39015 39016 39017 39018 39019 39020 39021 39022 39023 39024 39025 39026 39027 39028 39029 39030 39031 39032 39033 39034 39035 39036 39037 39038 39039 39040 39041 39042 39043 39044 39045 39046 39047 39048 39049 39050 39051 39052 39053 39054 39055 39056 39057 39058 39059 39060 39061 39062 39063 39064 39065 39066 39067 39068 39069 39070 39071 39072 39073 39074 39075 39076 39077 39078 39079 39080 39081 39082 39083 39084 39085 39086 39087 39088 39089 39090 39091 39092 39093 39094 39095 39096 39097 39098 39099 39100 39101 39102 39103 39104 39105 39106 39107 39108 39109 39110 39111 39112 39113 39114 39115 39116 39117 39118 39119 39120 39121 39122 39123 39124 39125 39126 39127 39128 39129 39130 39131 39132 39133 39134 39135 39136 39137 39138 39139 39140 39141 39142 39143 39144 39145 39146 39147 39148 39149 39150 39151 39152 39153 39154 39155 39156 39157 39158 39159 39160 39161 39162 39163 39164 39165 39166 39167 39168 39169 39170 39171 39172 39173 39174 39175 39176 39177 39178 39179 39180 39181 39182 39183 39184 39185 39186 39187 39188 39189 39190 39191 39192 39193 39194 39195 39196 39197 39198 39199 39200 39201 39202 39203 39204 39205 39206 39207 39208 39209 39210 39211 39212 39213 39214 39215 39216 39217 39218 39219 39220 39221 39222 39223 39224 39225 39226 39227 39228 39229 39230 39231 39232 39233 39234 39235 39236 39237 39238 39239 39240 39241 39242 39243 39244 39245 39246 39247 39248 39249 39250 39251 39252 39253 39254 39255 39256 39257 39258 39259 39260 39261 39262 39263 39264 39265 39266 39267 39268 39269 39270 39271 39272 39273 39274 39275 39276 39277 39278 39279 39280 39281 39282 39283 39284 39285 39286 39287 39288 39289 39290 39291 39292 39293 39294 39295 39296 39297 39298 39299 39300 39301 39302 39303 39304 39305 39306 39307 39308 39309 39310 39311 39312 39313 39314 39315 39316 39317 39318 39319 39320 39321 39322 39323 39324 39325 39326 39327 39328 39329 39330 39331 39332 39333 39334 39335 39336 39337 39338 39339 39340 39341 39342 39343 39344 39345 39346 39347 39348 39349 39350 39351 39352 39353 39354 39355 39356 39357 39358 39359 39360 39361 39362 39363 39364 39365 39366 39367 39368 39369 39370 39371 39372 39373 39374 39375 39376 39377 39378 39379 39380 39381 39382 39383 39384 39385 39386 39387 39388 39389 39390 39391 39392 39393 39394 39395 39396 39397 39398 39399 39400 39401 39402 39403 39404 39405 39406 39407 39408 39409 39410 39411 39412 39413 39414 39415 39416 39417 39418 39419 39420 39421 39422 39423 39424 39425 39426 39427 39428 39429 39430 39431 39432 39433 39434 39435 39436 39437 39438 39439 39440 39441 39442 39443 39444 39445 39446 39447 39448 39449 39450 39451 39452 39453 39454 39455 39456 39457 39458 39459 39460 39461 39462 39463 39464 39465 39466 39467 39468 39469 39470 39471 39472 39473 39474 39475 39476 39477 39478 39479 39480 39481 39482 39483 39484 39485 39486 39487 39488 39489 39490 39491 39492 39493 39494 39495 39496 39497 39498 39499 39500 39501 39502 39503 39504 39505 39506 39507 39508 39509 39510 39511 39512 39513 39514 39515 39516 39517 39518 39519 39520 39521 39522 39523 39524 39525 39526 39527 39528 39529 39530 39531 39532 39533 39534 39535 39536 39537 39538 39539 39540 39541 39542 39543 39544 39545 39546 39547 39548 39549 39550 39551 39552 39553 39554 39555 39556 39557 39558 39559 39560 39561 39562 39563 39564 39565 39566 39567 39568 39569 39570 39571 39572 39573 39574 39575 39576 39577 39578 39579 39580 39581 39582 39583 39584 39585 39586 39587 39588 39589 39590 39591 39592 39593 39594 39595 39596 39597 39598 39599 39600 39601 39602 39603 39604 39605 39606 39607 39608 39609 39610 39611 39612 39613 39614 39615 39616 39617 39618 39619 39620 39621 39622 39623 39624 39625 39626 39627 39628 39629 39630 39631 39632 39633 39634 39635 39636 39637 39638 39639 39640 39641 39642 39643 39644 39645 39646 39647 39648 39649 39650 39651 39652 39653 39654 39655 39656 39657 39658 39659 39660 39661 39662 39663 39664 39665 39666 39667 39668 39669 39670 39671 39672 39673 39674 39675 39676 39677 39678 39679 39680 39681 39682 39683 39684 39685 39686 39687 39688 39689 39690 39691 39692 39693 39694 39695 39696 39697 39698 39699 39700 39701 39702 39703 39704 39705 39706 39707 39708 39709 39710 39711 39712 39713 39714 39715 39716 39717 39718 39719 39720 39721 39722 39723 39724 39725 39726 39727 39728 39729 39730 39731 39732 39733 39734 39735 39736 39737 39738 39739 39740 39741 39742 39743 39744 39745 39746 39747 39748 39749 39750 39751 39752 39753 39754 39755 39756 39757 39758 39759 39760 39761 39762 39763 39764 39765 39766 39767 39768 39769 39770 39771 39772 39773 39774 39775 39776 39777 39778 39779 39780 39781 39782 39783 39784 39785 39786 39787 39788 39789 39790 39791 39792 39793 39794 39795 39796 39797 39798 39799 39800 39801 39802 39803 39804 39805 39806 39807 39808 39809 39810 39811 39812 39813 39814 39815 39816 39817 39818 39819 39820 39821 39822 39823 39824 39825 39826 39827 39828 39829 39830 39831 39832 39833 39834 39835 39836 39837 39838 39839 39840 39841 39842 39843 39844 39845 39846 39847 39848 39849 39850 39851 39852 39853 39854 39855 39856 39857 39858 39859 39860 39861 39862 39863 39864 39865 39866 39867 39868 39869 39870 39871 39872 39873 39874 39875 39876 39877 39878 39879 39880 39881 39882 39883 39884 39885 39886 39887 39888 39889 39890 39891 39892 39893 39894 39895 39896 39897 39898 39899 39900 39901 39902 39903 39904 39905 39906 39907 39908 39909 39910 39911 39912 39913 39914 39915 39916 39917 39918 39919 39920 39921 39922 39923 39924 39925 39926 39927 39928 39929 39930 39931 39932 39933 39934 39935 39936 39937 39938 39939 39940 39941 39942 39943 39944 39945 39946 39947 39948 39949 39950 39951 39952 39953 39954 39955 39956 39957 39958 39959 39960 39961 39962 39963 39964 39965 39966 39967 39968 39969 39970 39971 39972 39973 39974 39975 39976 39977 39978 39979 39980 39981 39982 39983 39984 39985 39986 39987 39988 39989 39990 39991 39992 39993 39994 39995 39996 39997 39998 39999 40000 40001 40002 40003 40004 40005 40006 40007 40008 40009 40010 40011 40012 40013 40014 40015 40016 40017 40018 40019 40020 40021 40022 40023 40024 40025 40026 40027 40028 40029 40030 40031 40032 40033 40034 40035 40036 40037 40038 40039 40040 40041 40042 40043 40044 40045 40046 40047 40048 40049 40050 40051 40052 40053 40054 40055 40056 40057 40058 40059 40060 40061 40062 40063 40064 40065 40066 40067 40068 40069 40070 40071 40072 40073 40074 40075 40076 40077 40078 40079 40080 40081 40082 40083 40084 40085 40086 40087 40088 40089 40090 40091 40092 40093 40094 40095 40096 40097 40098 40099 40100 40101 40102 40103 40104 40105 40106 40107 40108 40109 40110 40111 40112 40113 40114 40115 40116 40117 40118 40119 40120 40121 40122 40123 40124 40125 40126 40127 40128 40129 40130 40131 40132 40133 40134 40135 40136 40137 40138 40139 40140 40141 40142 40143 40144 40145 40146 40147 40148 40149 40150 40151 40152 40153 40154 40155 40156 40157 40158 40159 40160 40161 40162 40163 40164 40165 40166 40167 40168 40169 40170 40171 40172 40173 40174 40175 40176 40177 40178 40179 40180 40181 40182 40183 40184 40185 40186 40187 40188 40189 40190 40191 40192 40193 40194 40195 40196 40197 40198 40199 40200 40201 40202 40203 40204 40205 40206 40207 40208 40209 40210 40211 40212 40213 40214 40215 40216 40217 40218 40219 40220 40221 40222 40223 40224 40225 40226 40227 40228 40229 40230 40231 40232 40233 40234 40235 40236 40237 40238 40239 40240 40241 40242 40243 40244 40245 40246 40247 40248 40249 40250 40251 40252 40253 40254 40255 40256 40257 40258 40259 40260 40261 40262 40263 40264 40265 40266 40267 40268 40269 40270 40271 40272 40273 40274 40275 40276 40277 40278 40279 40280 40281 40282 40283 40284 40285 40286 40287 40288 40289 40290 40291 40292 40293 40294 40295 40296 40297 40298 40299 40300 40301 40302 40303 40304 40305 40306 40307 40308 40309 40310 40311 40312 40313 40314 40315 40316 40317 40318 40319 40320 40321 40322 40323 40324 40325 40326 40327 40328 40329 40330 40331 40332 40333 40334 40335 40336 40337 40338 40339 40340 40341 40342 40343 40344 40345 40346 40347 40348 40349 40350 40351 40352 40353 40354 40355 40356 40357 40358 40359 40360 40361 40362 40363 40364 40365 40366 40367 40368 40369 40370 40371 40372 40373 40374 40375 40376 40377 40378 40379 40380 40381 40382 40383 40384 40385 40386 40387 40388 40389 40390 40391 40392 40393 40394 40395 40396 40397 40398 40399 40400 40401 40402 40403 40404 40405 40406 40407 40408 40409 40410 40411 40412 40413 40414 40415 40416 40417 40418 40419 40420 40421 40422 40423 40424 40425 40426 40427 40428 40429 40430 40431 40432 40433 40434 40435 40436 40437 40438 40439 40440 40441 40442 40443 40444 40445 40446 40447 40448 40449 40450 40451 40452 40453 40454 40455 40456 40457 40458 40459 40460 40461 40462 40463 40464 40465 40466 40467 40468 40469 40470 40471 40472 40473 40474 40475 40476 40477 40478 40479 40480 40481 40482 40483 40484 40485 40486 40487 40488 40489 40490 40491 40492 40493 40494 40495 40496 40497 40498 40499 40500 40501 40502 40503 40504 40505 40506 40507 40508 40509 40510 40511 40512 40513 40514 40515 40516 40517 40518 40519 40520 40521 40522 40523 40524 40525 40526 40527 40528 40529 40530 40531 40532 40533 40534 40535 40536 40537 40538 40539 40540 40541 40542 40543 40544 40545 40546 40547 40548 40549 40550 40551 40552 40553 40554 40555 40556 40557 40558 40559 40560 40561 40562 40563 40564 40565 40566 40567 40568 40569 40570 40571 40572 40573 40574 40575 40576 40577 40578 40579 40580 40581 40582 40583 40584 40585 40586 40587 40588 40589 40590 40591 40592 40593 40594 40595 40596 40597 40598 40599 40600 40601 40602 40603 40604 40605 40606 40607 40608 40609 40610 40611 40612 40613 40614 40615 40616 40617 40618 40619 40620 40621 40622 40623 40624 40625 40626 40627 40628 40629 40630 40631 40632 40633 40634 40635 40636 40637 40638 40639 40640 40641 40642 40643 40644 40645 40646 40647 40648 40649 40650 40651 40652 40653 40654 40655 40656 40657 40658 40659 40660 40661 40662 40663 40664 40665 40666 40667 40668 40669 40670 40671 40672 40673 40674 40675 40676 40677 40678 40679 40680 40681 40682 40683 40684 40685 40686 40687 40688 40689 40690 40691 40692 40693 40694 40695 40696 40697 40698 40699 40700 40701 40702 40703 40704 40705 40706 40707 40708 40709 40710 40711 40712 40713 40714 40715 40716 40717 40718 40719 40720 40721 40722 40723 40724 40725 40726 40727 40728 40729 40730 40731 40732 40733 40734 40735 40736 40737 40738 40739 40740 40741 40742 40743 40744 40745 40746 40747 40748 40749 40750 40751 40752 40753 40754 40755 40756 40757 40758 40759 40760 40761 40762 40763 40764 40765 40766 40767 40768 40769 40770 40771 40772 40773 40774 40775 40776 40777 40778 40779 40780 40781 40782 40783 40784 40785 40786 40787 40788 40789 40790 40791 40792 40793 40794 40795 40796 40797 40798 40799 40800 40801 40802 40803 40804 40805 40806 40807 40808 40809 40810 40811 40812 40813 40814 40815 40816 40817 40818 40819 40820 40821 40822 40823 40824 40825 40826 40827 40828 40829 40830 40831 40832 40833 40834 40835 40836 40837 40838 40839 40840 40841 40842 40843 40844 40845 40846 40847 40848 40849 40850 40851 40852 40853 40854 40855 40856 40857 40858 40859 40860 40861 40862 40863 40864 40865 40866 40867 40868 40869 40870 40871 40872 40873 40874 40875 40876 40877 40878 40879 40880 40881 40882 40883 40884 40885 40886 40887 40888 40889 40890 40891 40892 40893 40894 40895 40896 40897 40898 40899 40900 40901 40902 40903 40904 40905 40906 40907 40908 40909 40910 40911 40912 40913 40914 40915 40916 40917 40918 40919 40920 40921 40922 40923 40924 40925 40926 40927 40928 40929 40930 40931 40932 40933 40934 40935 40936 40937 40938 40939 40940 40941 40942 40943 40944 40945 40946 40947 40948 40949 40950 40951 40952 40953 40954 40955 40956 40957 40958 40959 40960 40961 40962 40963 40964 40965 40966 40967 40968 40969 40970 40971 40972 40973 40974 40975 40976 40977 40978 40979 40980 40981 40982 40983 40984 40985 40986 40987 40988 40989 40990 40991 40992 40993 40994 40995 40996 40997 40998 40999 41000 41001 41002 41003 41004 41005 41006 41007 41008 41009 41010 41011 41012 41013 41014 41015 41016 41017 41018 41019 41020 41021 41022 41023 41024 41025 41026 41027 41028 41029 41030 41031 41032 41033 41034 41035 41036 41037 41038 41039 41040 41041 41042 41043 41044 41045 41046 41047 41048 41049 41050 41051 41052 41053 41054 41055 41056 41057 41058 41059 41060 41061 41062 41063 41064 41065 41066 41067 41068 41069 41070 41071 41072 41073 41074 41075 41076 41077 41078 41079 41080 41081 41082 41083 41084 41085 41086 41087 41088 41089 41090 41091 41092 41093 41094 41095 41096 41097 41098 41099 41100 41101 41102 41103 41104 41105 41106 41107 41108 41109 41110 41111 41112 41113 41114 41115 41116 41117 41118 41119 41120 41121 41122 41123 41124 41125 41126 41127 41128 41129 41130 41131 41132 41133 41134 41135 41136 41137 41138 41139 41140 41141 41142 41143 41144 41145 41146 41147 41148 41149 41150 41151 41152 41153 41154 41155 41156 41157 41158 41159 41160 41161 41162 41163 41164 41165 41166 41167 41168 41169 41170 41171 41172 41173 41174 41175 41176 41177 41178 41179 41180 41181 41182 41183 41184 41185 41186 41187 41188 41189 41190 41191 41192 41193 41194 41195 41196 41197 41198 41199 41200 41201 41202 41203 41204 41205 41206 41207 41208 41209 41210 41211 41212 41213 41214 41215 41216 41217 41218 41219 41220 41221 41222 41223 41224 41225 41226 41227 41228 41229 41230 41231 41232 41233 41234 41235 41236 41237 41238 41239 41240 41241 41242 41243 41244 41245 41246 41247 41248 41249 41250 41251 41252 41253 41254 41255 41256 41257 41258 41259 41260 41261 41262 41263 41264 41265 41266 41267 41268 41269 41270 41271 41272 41273 41274 41275 41276 41277 41278 41279 41280 41281 41282 41283 41284 41285 41286 41287 41288 41289 41290 41291 41292 41293 41294 41295 41296 41297 41298 41299 41300 41301 41302 41303 41304 41305 41306 41307 41308 41309 41310 41311 41312 41313 41314 41315 41316 41317 41318 41319 41320 41321 41322 41323 41324 41325 41326 41327 41328 41329 41330 41331 41332 41333 41334 41335 41336 41337 41338 41339 41340 41341 41342 41343 41344 41345 41346 41347 41348 41349 41350 41351 41352 41353 41354 41355 41356 41357 41358 41359 41360 41361 41362 41363 41364 41365 41366 41367 41368 41369 41370 41371 41372 41373 41374 41375 41376 41377 41378 41379 41380 41381 41382 41383 41384 41385 41386 41387 41388 41389 41390 41391 41392 41393 41394 41395 41396 41397 41398 41399 41400 41401 41402 41403 41404 41405 41406 41407 41408 41409 41410 41411 41412 41413 41414 41415 41416 41417 41418 41419 41420 41421 41422 41423 41424 41425 41426 41427 41428 41429 41430 41431 41432 41433 41434 41435 41436 41437 41438 41439 41440 41441 41442 41443 41444 41445 41446 41447 41448 41449 41450 41451 41452 41453 41454 41455 41456 41457 41458 41459 41460 41461 41462 41463 41464 41465 41466 41467 41468 41469 41470 41471 41472 41473 41474 41475 41476 41477 41478 41479 41480 41481 41482 41483 41484 41485 41486 41487 41488 41489 41490 41491 41492 41493 41494 41495 41496 41497 41498 41499 41500 41501 41502 41503 41504 41505 41506 41507 41508 41509 41510 41511 41512 41513 41514 41515 41516 41517 41518 41519 41520 41521 41522 41523 41524 41525 41526 41527 41528 41529 41530 41531 41532 41533 41534 41535 41536 41537 41538 41539 41540 41541 41542 41543 41544 41545 41546 41547 41548 41549 41550 41551 41552 41553 41554 41555 41556 41557 41558 41559 41560 41561 41562 41563 41564 41565 41566 41567 41568 41569 41570 41571 41572 41573 41574 41575 41576 41577 41578 41579 41580 41581 41582 41583 41584 41585 41586 41587 41588 41589 41590 41591 41592 41593 41594 41595 41596 41597 41598 41599 41600 41601 41602 41603 41604 41605 41606 41607 41608 41609 41610 41611 41612 41613 41614 41615 41616 41617 41618 41619 41620 41621 41622 41623 41624 41625 41626 41627 41628 41629 41630 41631 41632 41633 41634 41635 41636 41637 41638 41639 41640 41641 41642 41643 41644 41645 41646 41647 41648 41649 41650 41651 41652 41653 41654 41655 41656 41657 41658 41659 41660 41661 41662 41663 41664 41665 41666 41667 41668 41669 41670 41671 41672 41673 41674 41675 41676 41677 41678 41679 41680 41681 41682 41683 41684 41685 41686 41687 41688 41689 41690 41691 41692 41693 41694 41695 41696 41697 41698 41699 41700 41701 41702 41703 41704 41705 41706 41707 41708 41709 41710 41711 41712 41713 41714 41715 41716 41717 41718 41719 41720 41721 41722 41723 41724 41725 41726 41727 41728 41729 41730 41731 41732 41733 41734 41735 41736 41737 41738 41739 41740 41741 41742 41743 41744 41745 41746 41747 41748 41749 41750 41751 41752 41753 41754 41755 41756 41757 41758 41759 41760 41761 41762 41763 41764 41765 41766 41767 41768 41769 41770 41771 41772 41773 41774 41775 41776 41777 41778 41779 41780 41781 41782 41783 41784 41785 41786 41787 41788 41789 41790 41791 41792 41793 41794 41795 41796 41797 41798 41799 41800 41801 41802 41803 41804 41805 41806 41807 41808 41809 41810 41811 41812 41813 41814 41815 41816 41817 41818 41819 41820 41821 41822 41823 41824 41825 41826 41827 41828 41829 41830 41831 41832 41833 41834 41835 41836 41837 41838 41839 41840 41841 41842 41843 41844 41845 41846 41847 41848 41849 41850 41851 41852 41853 41854 41855 41856 41857 41858 41859 41860 41861 41862 41863 41864 41865 41866 41867 41868 41869 41870 41871 41872 41873 41874 41875 41876 41877 41878 41879 41880 41881 41882 41883 41884 41885 41886 41887 41888 41889 41890 41891 41892 41893 41894 41895 41896 41897 41898 41899 41900 41901 41902 41903 41904 41905 41906 41907 41908 41909 41910 41911 41912 41913 41914 41915 41916 41917 41918 41919 41920 41921 41922 41923 41924 41925 41926 41927 41928 41929 41930 41931 41932 41933 41934 41935 41936 41937 41938 41939 41940 41941 41942 41943 41944 41945 41946 41947 41948 41949 41950 41951 41952 41953 41954 41955 41956 41957 41958 41959 41960 41961 41962 41963 41964 41965 41966 41967 41968 41969 41970 41971 41972 41973 41974 41975 41976 41977 41978 41979 41980 41981 41982 41983 41984 41985 41986 41987 41988 41989 41990 41991 41992 41993 41994 41995 41996 41997 41998 41999 42000 42001 42002 42003 42004 42005 42006 42007 42008 42009 42010 42011 42012 42013 42014 42015 42016 42017 42018 42019 42020 42021 42022 42023 42024 42025 42026 42027 42028 42029 42030 42031 42032 42033 42034 42035 42036 42037 42038 42039 42040 42041 42042 42043 42044 42045 42046 42047 42048 42049 42050 42051 42052 42053 42054 42055 42056 42057 42058 42059 42060 42061 42062 42063 42064 42065 42066 42067 42068 42069 42070 42071 42072 42073 42074 42075 42076 42077 42078 42079 42080 42081 42082 42083 42084 42085 42086 42087 42088 42089 42090 42091 42092 42093 42094 42095 42096 42097 42098 42099 42100 42101 42102 42103 42104 42105 42106 42107 42108 42109 42110 42111 42112 42113 42114 42115 42116 42117 42118 42119 42120 42121 42122 42123 42124 42125 42126 42127 42128 42129 42130 42131 42132 42133 42134 42135 42136 42137 42138 42139 42140 42141 42142 42143 42144 42145 42146 42147 42148 42149 42150 42151 42152 42153 42154 42155 42156 42157 42158 42159 42160 42161 42162 42163 42164 42165 42166 42167 42168 42169 42170 42171 42172 42173 42174 42175 42176 42177 42178 42179 42180 42181 42182 42183 42184 42185 42186 42187 42188 42189 42190 42191 42192 42193 42194 42195 42196 42197 42198 42199 42200 42201 42202 42203 42204 42205 42206 42207 42208 42209 42210 42211 42212 42213 42214 42215 42216 42217 42218 42219 42220 42221 42222 42223 42224 42225 42226 42227 42228 42229 42230 42231 42232 42233 42234 42235 42236 42237 42238 42239 42240 42241 42242 42243 42244 42245 42246 42247 42248 42249 42250 42251 42252 42253 42254 42255 42256 42257 42258 42259 42260 42261 42262 42263 42264 42265 42266 42267 42268 42269 42270 42271 42272 42273 42274 42275 42276 42277 42278 42279 42280 42281 42282 42283 42284 42285 42286 42287 42288 42289 42290 42291 42292 42293 42294 42295 42296 42297 42298 42299 42300 42301 42302 42303 42304 42305 42306 42307 42308 42309 42310 42311 42312 42313 42314 42315 42316 42317 42318 42319 42320 42321 42322 42323 42324 42325 42326 42327 42328 42329 42330 42331 42332 42333 42334 42335 42336 42337 42338 42339 42340 42341 42342 42343 42344 42345 42346 42347 42348 42349 42350 42351 42352 42353 42354 42355 42356 42357 42358 42359 42360 42361 42362 42363 42364 42365 42366 42367 42368 42369 42370 42371 42372 42373 42374 42375 42376 42377 42378 42379 42380 42381 42382 42383 42384 42385 42386 42387 42388 42389 42390 42391 42392 42393 42394 42395 42396 42397 42398 42399 42400 42401 42402 42403 42404 42405 42406 42407 42408 42409 42410 42411 42412 42413 42414 42415 42416 42417 42418 42419 42420 42421 42422 42423 42424 42425 42426 42427 42428 42429 42430 42431 42432 42433 42434 42435 42436 42437 42438 42439 42440 42441 42442 42443 42444 42445 42446 42447 42448 42449 42450 42451 42452 42453 42454 42455 42456 42457 42458 42459 42460 42461 42462 42463 42464 42465 42466 42467 42468 42469 42470 42471 42472 42473 42474 42475 42476 42477 42478 42479 42480 42481 42482 42483 42484 42485 42486 42487 42488 42489 42490 42491 42492 42493 42494 42495 42496 42497 42498 42499 42500 42501 42502 42503 42504 42505 42506 42507 42508 42509 42510 42511 42512 42513 42514 42515 42516 42517 42518 42519 42520 42521 42522 42523 42524 42525 42526 42527 42528 42529 42530 42531 42532 42533 42534 42535 42536 42537 42538 42539 42540 42541 42542 42543 42544 42545 42546 42547 42548 42549 42550 42551 42552 42553 42554 42555 42556 42557 42558 42559 42560 42561 42562 42563 42564 42565 42566 42567 42568 42569 42570 42571 42572 42573 42574 42575 42576 42577 42578 42579 42580 42581 42582 42583 42584 42585 42586 42587 42588 42589 42590 42591 42592 42593 42594 42595 42596 42597 42598 42599 42600 42601 42602 42603 42604 42605 42606 42607 42608 42609 42610 42611 42612 42613 42614 42615 42616 42617 42618 42619 42620 42621 42622 42623 42624 42625 42626 42627 42628 42629 42630 42631 42632 42633 42634 42635 42636 42637 42638 42639 42640 42641 42642 42643 42644 42645 42646 42647 42648 42649 42650 42651 42652 42653 42654 42655 42656 42657 42658 42659 42660 42661 42662 42663 42664 42665 42666 42667 42668 42669 42670 42671 42672 42673 42674 42675 42676 42677 42678 42679 42680 42681 42682 42683 42684 42685 42686 42687 42688 42689 42690 42691 42692 42693 42694 42695 42696 42697 42698 42699 42700 42701 42702 42703 42704 42705 42706 42707 42708 42709 42710 42711 42712 42713 42714 42715 42716 42717 42718 42719 42720 42721 42722 42723 42724 42725 42726 42727 42728 42729 42730 42731 42732 42733 42734 42735 42736 42737 42738 42739 42740 42741 42742 42743 42744 42745 42746 42747 42748 42749 42750 42751 42752 42753 42754 42755 42756 42757 42758 42759 42760 42761 42762 42763 42764 42765 42766 42767 42768 42769 42770 42771 42772 42773 42774 42775 42776 42777 42778 42779 42780 42781 42782 42783 42784 42785 42786 42787 42788 42789 42790 42791 42792 42793 42794 42795 42796 42797 42798 42799 42800 42801 42802 42803 42804 42805 42806 42807 42808 42809 42810 42811 42812 42813 42814 42815 42816 42817 42818 42819 42820 42821 42822 42823 42824 42825 42826 42827 42828 42829 42830 42831 42832 42833 42834 42835 42836 42837 42838 42839 42840 42841 42842 42843 42844 42845 42846 42847 42848 42849 42850 42851 42852 42853 42854 42855 42856 42857 42858 42859 42860 42861 42862 42863 42864 42865 42866 42867 42868 42869 42870 42871 42872 42873 42874 42875 42876 42877 42878 42879 42880 42881 42882 42883 42884 42885 42886 42887 42888 42889 42890 42891 42892 42893 42894 42895 42896 42897 42898 42899 42900 42901 42902 42903 42904 42905 42906 42907 42908 42909 42910 42911 42912 42913 42914 42915 42916 42917 42918 42919 42920 42921 42922 42923 42924 42925 42926 42927 42928 42929 42930 42931 42932 42933 42934 42935 42936 42937 42938 42939 42940 42941 42942 42943 42944 42945 42946 42947 42948 42949 42950 42951 42952 42953 42954 42955 42956 42957 42958 42959 42960 42961 42962 42963 42964 42965 42966 42967 42968 42969 42970 42971 42972 42973 42974 42975 42976 42977 42978 42979 42980 42981 42982 42983 42984 42985 42986 42987 42988 42989 42990 42991 42992 42993 42994 42995 42996 42997 42998 42999 43000 43001 43002 43003 43004 43005 43006 43007 43008 43009 43010 43011 43012 43013 43014 43015 43016 43017 43018 43019 43020 43021 43022 43023 43024 43025 43026 43027 43028 43029 43030 43031 43032 43033 43034 43035 43036 43037 43038 43039 43040 43041 43042 43043 43044 43045 43046 43047 43048 43049 43050 43051 43052 43053 43054 43055 43056 43057 43058 43059 43060 43061 43062 43063 43064 43065 43066 43067 43068 43069 43070 43071 43072 43073 43074 43075 43076 43077 43078 43079 43080 43081 43082 43083 43084 43085 43086 43087 43088 43089 43090 43091 43092 43093 43094 43095 43096 43097 43098 43099 43100 43101 43102 43103 43104 43105 43106 43107 43108 43109 43110 43111 43112 43113 43114 43115 43116 43117 43118 43119 43120 43121 43122 43123 43124 43125 43126 43127 43128 43129 43130 43131 43132 43133 43134 43135 43136 43137 43138 43139 43140 43141 43142 43143 43144 43145 43146 43147 43148 43149 43150 43151 43152 43153 43154 43155 43156 43157 43158 43159 43160 43161 43162 43163 43164 43165 43166 43167 43168 43169 43170 43171 43172 43173 43174 43175 43176 43177 43178 43179 43180 43181 43182 43183 43184 43185 43186 43187 43188 43189 43190 43191 43192 43193 43194 43195 43196 43197 43198 43199 43200 43201 43202 43203 43204 43205 43206 43207 43208 43209 43210 43211 43212 43213 43214 43215 43216 43217 43218 43219 43220 43221 43222 43223 43224 43225 43226 43227 43228 43229 43230 43231 43232 43233 43234 43235 43236 43237 43238 43239 43240 43241 43242 43243 43244 43245 43246 43247 43248 43249 43250 43251 43252 43253 43254 43255 43256 43257 43258 43259 43260 43261 43262 43263 43264 43265 43266 43267 43268 43269 43270 43271 43272 43273 43274 43275 43276 43277 43278 43279 43280 43281 43282 43283 43284 43285 43286 43287 43288 43289 43290 43291 43292 43293 43294 43295 43296 43297 43298 43299 43300 43301 43302 43303 43304 43305 43306 43307 43308 43309 43310 43311 43312 43313 43314 43315 43316 43317 43318 43319 43320 43321 43322 43323 43324 43325 43326 43327 43328 43329 43330 43331 43332 43333 43334 43335 43336 43337 43338 43339 43340 43341 43342 43343 43344 43345 43346 43347 43348 43349 43350 43351 43352 43353 43354 43355 43356 43357 43358 43359 43360 43361 43362 43363 43364 43365 43366 43367 43368 43369 43370 43371 43372 43373 43374 43375 43376 43377 43378 43379 43380 43381 43382 43383 43384 43385 43386 43387 43388 43389 43390 43391 43392 43393 43394 43395 43396 43397 43398 43399 43400 43401 43402 43403 43404 43405 43406 43407 43408 43409 43410 43411 43412 43413 43414 43415 43416 43417 43418 43419 43420 43421 43422 43423 43424 43425 43426 43427 43428 43429 43430 43431 43432 43433 43434 43435 43436 43437 43438 43439 43440 43441 43442 43443 43444 43445 43446 43447 43448 43449 43450 43451 43452 43453 43454 43455 43456 43457 43458 43459 43460 43461 43462 43463 43464 43465 43466 43467 43468 43469 43470 43471 43472 43473 43474 43475 43476 43477 43478 43479 43480 43481 43482 43483 43484 43485 43486 43487 43488 43489 43490 43491 43492 43493 43494 43495 43496 43497 43498 43499 43500 43501 43502 43503 43504 43505 43506 43507 43508 43509 43510 43511 43512 43513 43514 43515 43516 43517 43518 43519 43520 43521 43522 43523 43524 43525 43526 43527 43528 43529 43530 43531 43532 43533 43534 43535 43536 43537 43538 43539 43540 43541 43542 43543 43544 43545 43546 43547 43548 43549 43550 43551 43552 43553 43554 43555 43556 43557 43558 43559 43560 43561 43562 43563 43564 43565 43566 43567 43568 43569 43570 43571 43572 43573 43574 43575 43576 43577 43578 43579 43580 43581 43582 43583 43584 43585 43586 43587 43588 43589 43590 43591 43592 43593 43594 43595 43596 43597 43598 43599 43600 43601 43602 43603 43604 43605 43606 43607 43608 43609 43610 43611 43612 43613 43614 43615 43616 43617 43618 43619 43620 43621 43622 43623 43624 43625 43626 43627 43628 43629 43630 43631 43632 43633 43634 43635 43636 43637 43638 43639 43640 43641 43642 43643 43644 43645 43646 43647 43648 43649 43650 43651 43652 43653 43654 43655 43656 43657 43658 43659 43660 43661 43662 43663 43664 43665 43666 43667 43668 43669 43670 43671 43672 43673 43674 43675 43676 43677 43678 43679 43680 43681 43682 43683 43684 43685 43686 43687 43688 43689 43690 43691 43692 43693 43694 43695 43696 43697 43698 43699 43700 43701 43702 43703 43704 43705 43706 43707 43708 43709 43710 43711 43712 43713 43714 43715 43716 43717 43718 43719 43720 43721 43722 43723 43724 43725 43726 43727 43728 43729 43730 43731 43732 43733 43734 43735 43736 43737 43738 43739 43740 43741 43742 43743 43744 43745 43746 43747 43748 43749 43750 43751 43752 43753 43754 43755 43756 43757 43758 43759 43760 43761 43762 43763 43764 43765 43766 43767 43768 43769 43770 43771 43772 43773 43774 43775 43776 43777 43778 43779 43780 43781 43782 43783 43784 43785 43786 43787 43788 43789 43790 43791 43792 43793 43794 43795 43796 43797 43798 43799 43800 43801 43802 43803 43804 43805 43806 43807 43808 43809 43810 43811 43812 43813 43814 43815 43816 43817 43818 43819 43820 43821 43822 43823 43824 43825 43826 43827 43828 43829 43830 43831 43832 43833 43834 43835 43836 43837 43838 43839 43840 43841 43842 43843 43844 43845 43846 43847 43848 43849 43850 43851 43852 43853 43854 43855 43856 43857 43858 43859 43860 43861 43862 43863 43864 43865 43866 43867 43868 43869 43870 43871 43872 43873 43874 43875 43876 43877 43878 43879 43880 43881 43882 43883 43884 43885 43886 43887 43888 43889 43890 43891 43892 43893 43894 43895 43896 43897 43898 43899 43900 43901 43902 43903 43904 43905 43906 43907 43908 43909 43910 43911 43912 43913 43914 43915 43916 43917 43918 43919 43920 43921 43922 43923 43924 43925 43926 43927 43928 43929 43930 43931 43932 43933 43934 43935 43936 43937 43938 43939 43940 43941 43942 43943 43944 43945 43946 43947 43948 43949 43950 43951 43952 43953 43954 43955 43956 43957 43958 43959 43960 43961 43962 43963 43964 43965 43966 43967 43968 43969 43970 43971 43972 43973 43974 43975 43976 43977 43978 43979 43980 43981 43982 43983 43984 43985 43986 43987 43988 43989 43990 43991 43992 43993 43994 43995 43996 43997 43998 43999 44000 44001 44002 44003 44004 44005 44006 44007 44008 44009 44010 44011 44012 44013 44014 44015 44016 44017 44018 44019 44020 44021 44022 44023 44024 44025 44026 44027 44028 44029 44030 44031 44032 44033 44034 44035 44036 44037 44038 44039 44040 44041 44042 44043 44044 44045 44046 44047 44048 44049 44050 44051 44052 44053 44054 44055 44056 44057 44058 44059 44060 44061 44062 44063 44064 44065 44066 44067 44068 44069 44070 44071 44072 44073 44074 44075 44076 44077 44078 44079 44080 44081 44082 44083 44084 44085 44086 44087 44088 44089 44090 44091 44092 44093 44094 44095 44096 44097 44098 44099 44100 44101 44102 44103 44104 44105 44106 44107 44108 44109 44110 44111 44112 44113 44114 44115 44116 44117 44118 44119 44120 44121 44122 44123 44124 44125 44126 44127 44128 44129 44130 44131 44132 44133 44134 44135 44136 44137 44138 44139 44140 44141 44142 44143 44144 44145 44146 44147 44148 44149 44150 44151 44152 44153 44154 44155 44156 44157 44158 44159 44160 44161 44162 44163 44164 44165 44166 44167 44168 44169 44170 44171 44172 44173 44174 44175 44176 44177 44178 44179 44180 44181 44182 44183 44184 44185 44186 44187 44188 44189 44190 44191 44192 44193 44194 44195 44196 44197 44198 44199 44200 44201 44202 44203 44204 44205 44206 44207 44208 44209 44210 44211 44212 44213 44214 44215 44216 44217 44218 44219 44220 44221 44222 44223 44224 44225 44226 44227 44228 44229 44230 44231 44232 44233 44234 44235 44236 44237 44238 44239 44240 44241 44242 44243 44244 44245 44246 44247 44248 44249 44250 44251 44252 44253 44254 44255 44256 44257 44258 44259 44260 44261 44262 44263 44264 44265 44266 44267 44268 44269 44270 44271 44272 44273 44274 44275 44276 44277 44278 44279 44280 44281 44282 44283 44284 44285 44286 44287 44288 44289 44290 44291 44292 44293 44294 44295 44296 44297 44298 44299 44300 44301 44302 44303 44304 44305 44306 44307 44308 44309 44310 44311 44312 44313 44314 44315 44316 44317 44318 44319 44320 44321 44322 44323 44324 44325 44326 44327 44328 44329 44330 44331 44332 44333 44334 44335 44336 44337 44338 44339 44340 44341 44342 44343 44344 44345 44346 44347 44348 44349 44350 44351 44352 44353 44354 44355 44356 44357 44358 44359 44360 44361 44362 44363 44364 44365 44366 44367 44368 44369 44370 44371 44372 44373 44374 44375 44376 44377 44378 44379 44380 44381 44382 44383 44384 44385 44386 44387 44388 44389 44390 44391 44392 44393 44394 44395 44396 44397 44398 44399 44400 44401 44402 44403 44404 44405 44406 44407 44408 44409 44410 44411 44412 44413 44414 44415 44416 44417 44418 44419 44420 44421 44422 44423 44424 44425 44426 44427 44428 44429 44430 44431 44432 44433 44434 44435 44436 44437 44438 44439 44440 44441 44442 44443 44444 44445 44446 44447 44448 44449 44450 44451 44452 44453 44454 44455 44456 44457 44458 44459 44460 44461 44462 44463 44464 44465 44466 44467 44468 44469 44470 44471 44472 44473 44474 44475 44476 44477 44478 44479 44480 44481 44482 44483 44484 44485 44486 44487 44488 44489 44490 44491 44492 44493 44494 44495 44496 44497 44498 44499 44500 44501 44502 44503 44504 44505 44506 44507 44508 44509 44510 44511 44512 44513 44514 44515 44516 44517 44518 44519 44520 44521 44522 44523 44524 44525 44526 44527 44528 44529 44530 44531 44532 44533 44534 44535 44536 44537 44538 44539 44540 44541 44542 44543 44544 44545 44546 44547 44548 44549 44550 44551 44552 44553 44554 44555 44556 44557 44558 44559 44560 44561 44562 44563 44564 44565 44566 44567 44568 44569 44570 44571 44572 44573 44574 44575 44576 44577 44578 44579 44580 44581 44582 44583 44584 44585 44586 44587 44588 44589 44590 44591 44592 44593 44594 44595 44596 44597 44598 44599 44600 44601 44602 44603 44604 44605 44606 44607 44608 44609 44610 44611 44612 44613 44614 44615 44616 44617 44618 44619 44620 44621 44622 44623 44624 44625 44626 44627 44628 44629 44630 44631 44632 44633 44634 44635 44636 44637 44638 44639 44640 44641 44642 44643 44644 44645 44646 44647 44648 44649 44650 44651 44652 44653 44654 44655 44656 44657 44658 44659 44660 44661 44662 44663 44664 44665 44666 44667 44668 44669 44670 44671 44672 44673 44674 44675 44676 44677 44678 44679 44680 44681 44682 44683 44684 44685 44686 44687 44688 44689 44690 44691 44692 44693 44694 44695 44696 44697 44698 44699 44700 44701 44702 44703 44704 44705 44706 44707 44708 44709 44710 44711 44712 44713 44714 44715 44716 44717 44718 44719 44720 44721 44722 44723 44724 44725 44726 44727 44728 44729 44730 44731 44732 44733 44734 44735 44736 44737 44738 44739 44740 44741 44742 44743 44744 44745 44746 44747 44748 44749 44750 44751 44752 44753 44754 44755 44756 44757 44758 44759 44760 44761 44762 44763 44764 44765 44766 44767 44768 44769 44770 44771 44772 44773 44774 44775 44776 44777 44778 44779 44780 44781 44782 44783 44784 44785 44786 44787 44788 44789 44790 44791 44792 44793 44794 44795 44796 44797 44798 44799 44800 44801 44802 44803 44804 44805 44806 44807 44808 44809 44810 44811 44812 44813 44814 44815 44816 44817 44818 44819 44820 44821 44822 44823 44824 44825 44826 44827 44828 44829 44830 44831 44832 44833 44834 44835 44836 44837 44838 44839 44840 44841 44842 44843 44844 44845 44846 44847 44848 44849 44850 44851 44852 44853 44854 44855 44856 44857 44858 44859 44860 44861 44862 44863 44864 44865 44866 44867 44868 44869 44870 44871 44872 44873 44874 44875 44876 44877 44878 44879 44880 44881 44882 44883 44884 44885 44886 44887 44888 44889 44890 44891 44892 44893 44894 44895 44896 44897 44898 44899 44900 44901 44902 44903 44904 44905 44906 44907 44908 44909 44910 44911 44912 44913 44914 44915 44916 44917 44918 44919 44920 44921 44922 44923 44924 44925 44926 44927 44928 44929 44930 44931 44932 44933 44934 44935 44936 44937 44938 44939 44940 44941 44942 44943 44944 44945 44946 44947 44948 44949 44950 44951 44952 44953 44954 44955 44956 44957 44958 44959 44960 44961 44962 44963 44964 44965 44966 44967 44968 44969 44970 44971 44972 44973 44974 44975 44976 44977 44978 44979 44980 44981 44982 44983 44984 44985 44986 44987 44988 44989 44990 44991 44992 44993 44994 44995 44996 44997 44998 44999 45000 45001 45002 45003 45004 45005 45006 45007 45008 45009 45010 45011 45012 45013 45014 45015 45016 45017 45018 45019 45020 45021 45022 45023 45024 45025 45026 45027 45028 45029 45030 45031 45032 45033 45034 45035 45036 45037 45038 45039 45040 45041 45042 45043 45044 45045 45046 45047 45048 45049 45050 45051 45052 45053 45054 45055 45056 45057 45058 45059 45060 45061 45062 45063 45064 45065 45066 45067 45068 45069 45070 45071 45072 45073 45074 45075 45076 45077 45078 45079 45080 45081 45082 45083 45084 45085 45086 45087 45088 45089 45090 45091 45092 45093 45094 45095 45096 45097 45098 45099 45100 45101 45102 45103 45104 45105 45106 45107 45108 45109 45110 45111 45112 45113 45114 45115 45116 45117 45118 45119 45120 45121 45122 45123 45124 45125 45126 45127 45128 45129 45130 45131 45132 45133 45134 45135 45136 45137 45138 45139 45140 45141 45142 45143 45144 45145 45146 45147 45148 45149 45150 45151 45152 45153 45154 45155 45156 45157 45158 45159 45160 45161 45162 45163 45164 45165 45166 45167 45168 45169 45170 45171 45172 45173 45174 45175 45176 45177 45178 45179 45180 45181 45182 45183 45184 45185 45186 45187 45188 45189 45190 45191 45192 45193 45194 45195 45196 45197 45198 45199 45200 45201 45202 45203 45204 45205 45206 45207 45208 45209 45210 45211 45212 45213 45214 45215 45216 45217 45218 45219 45220 45221 45222 45223 45224 45225 45226 45227 45228 45229 45230 45231 45232 45233 45234 45235 45236 45237 45238 45239 45240 45241 45242 45243 45244 45245 45246 45247 45248 45249 45250 45251 45252 45253 45254 45255 45256 45257 45258 45259 45260 45261 45262 45263 45264 45265 45266 45267 45268 45269 45270 45271 45272 45273 45274 45275 45276 45277 45278 45279 45280 45281 45282 45283 45284 45285 45286 45287 45288 45289 45290 45291 45292 45293 45294 45295 45296 45297 45298 45299 45300 45301 45302 45303 45304 45305 45306 45307 45308 45309 45310 45311 45312 45313 45314 45315 45316 45317 45318 45319 45320 45321 45322 45323 45324 45325 45326 45327 45328 45329 45330 45331 45332 45333 45334 45335 45336 45337 45338 45339 45340 45341 45342 45343 45344 45345 45346 45347 45348 45349 45350 45351 45352 45353 45354 45355 45356 45357 45358 45359 45360 45361 45362 45363 45364 45365 45366 45367 45368 45369 45370 45371 45372 45373 45374 45375 45376 45377 45378 45379 45380 45381 45382 45383 45384 45385 45386 45387 45388 45389 45390 45391 45392 45393 45394 45395 45396 45397 45398 45399 45400 45401 45402 45403 45404 45405 45406 45407 45408 45409 45410 45411 45412 45413 45414 45415 45416 45417 45418 45419 45420 45421 45422 45423 45424 45425 45426 45427 45428 45429 45430 45431 45432 45433 45434 45435 45436 45437 45438 45439 45440 45441 45442 45443 45444 45445 45446 45447 45448 45449 45450 45451 45452 45453 45454 45455 45456 45457 45458 45459 45460 45461 45462 45463 45464 45465 45466 45467 45468 45469 45470 45471 45472 45473 45474 45475 45476 45477 45478 45479 45480 45481 45482 45483 45484 45485 45486 45487 45488 45489 45490 45491 45492 45493 45494 45495 45496 45497 45498 45499 45500 45501 45502 45503 45504 45505 45506 45507 45508 45509 45510 45511 45512 45513 45514 45515 45516 45517 45518 45519 45520 45521 45522 45523 45524 45525 45526 45527 45528 45529 45530 45531 45532 45533 45534 45535 45536 45537 45538 45539 45540 45541 45542 45543 45544 45545 45546 45547 45548 45549 45550 45551 45552 45553 45554 45555 45556 45557 45558 45559 45560 45561 45562 45563 45564 45565 45566 45567 45568 45569 45570 45571 45572 45573 45574 45575 45576 45577 45578 45579 45580 45581 45582 45583 45584 45585 45586 45587 45588 45589 45590 45591 45592 45593 45594 45595 45596 45597 45598 45599 45600 45601 45602 45603 45604 45605 45606 45607 45608 45609 45610 45611 45612 45613 45614 45615 45616 45617 45618 45619 45620 45621 45622 45623 45624 45625 45626 45627 45628 45629 45630 45631 45632 45633 45634 45635 45636 45637 45638 45639 45640 45641 45642 45643 45644 45645 45646 45647 45648 45649 45650 45651 45652 45653 45654 45655 45656 45657 45658 45659 45660 45661 45662 45663 45664 45665 45666 45667 45668 45669 45670 45671 45672 45673 45674 45675 45676 45677 45678 45679 45680 45681 45682 45683 45684 45685 45686 45687 45688 45689 45690 45691 45692 45693 45694 45695 45696 45697 45698 45699 45700 45701 45702 45703 45704 45705 45706 45707 45708 45709 45710 45711 45712 45713 45714 45715 45716 45717 45718 45719 45720 45721 45722 45723 45724 45725 45726 45727 45728 45729 45730 45731 45732 45733 45734 45735 45736 45737 45738 45739 45740 45741 45742 45743 45744 45745 45746 45747 45748 45749 45750 45751 45752 45753 45754 45755 45756 45757 45758 45759 45760 45761 45762 45763 45764 45765 45766 45767 45768 45769 45770 45771 45772 45773 45774 45775 45776 45777 45778 45779 45780 45781 45782 45783 45784 45785 45786 45787 45788 45789 45790 45791 45792 45793 45794 45795 45796 45797 45798 45799 45800 45801 45802 45803 45804 45805 45806 45807 45808 45809 45810 45811 45812 45813 45814 45815 45816 45817 45818 45819 45820 45821 45822 45823 45824 45825 45826 45827 45828 45829 45830 45831 45832 45833 45834 45835 45836 45837 45838 45839 45840 45841 45842 45843 45844 45845 45846 45847 45848 45849 45850 45851 45852 45853 45854 45855 45856 45857 45858 45859 45860 45861 45862 45863 45864 45865 45866 45867 45868 45869 45870 45871 45872 45873 45874 45875 45876 45877 45878 45879 45880 45881 45882 45883 45884 45885 45886 45887 45888 45889 45890 45891 45892 45893 45894 45895 45896 45897 45898 45899 45900 45901 45902 45903 45904 45905 45906 45907 45908 45909 45910 45911 45912 45913 45914 45915 45916 45917 45918 45919 45920 45921 45922 45923 45924 45925 45926 45927 45928 45929 45930 45931 45932 45933 45934 45935 45936 45937 45938 45939 45940 45941 45942 45943 45944 45945 45946 45947 45948 45949 45950 45951 45952 45953 45954 45955 45956 45957 45958 45959 45960 45961 45962 45963 45964 45965 45966 45967 45968 45969 45970 45971 45972 45973 45974 45975 45976 45977 45978 45979 45980 45981 45982 45983 45984 45985 45986 45987 45988 45989 45990 45991 45992 45993 45994 45995 45996 45997 45998 45999 46000 46001 46002 46003 46004 46005 46006 46007 46008 46009 46010 46011 46012 46013 46014 46015 46016 46017 46018 46019 46020 46021 46022 46023 46024 46025 46026 46027 46028 46029 46030 46031 46032 46033 46034 46035 46036 46037 46038 46039 46040 46041 46042 46043 46044 46045 46046 46047 46048 46049 46050 46051 46052 46053 46054 46055 46056 46057 46058 46059 46060 46061 46062 46063 46064 46065 46066 46067 46068 46069 46070 46071 46072 46073 46074 46075 46076 46077 46078 46079 46080 46081 46082 46083 46084 46085 46086 46087 46088 46089 46090 46091 46092 46093 46094 46095 46096 46097 46098 46099 46100 46101 46102 46103 46104 46105 46106 46107 46108 46109 46110 46111 46112 46113 46114 46115 46116 46117 46118 46119 46120 46121 46122 46123 46124 46125 46126 46127 46128 46129 46130 46131 46132 46133 46134 46135 46136 46137 46138 46139 46140 46141 46142 46143 46144 46145 46146 46147 46148 46149 46150 46151 46152 46153 46154 46155 46156 46157 46158 46159 46160 46161 46162 46163 46164 46165 46166 46167 46168 46169 46170 46171 46172 46173 46174 46175 46176 46177 46178 46179 46180 46181 46182 46183 46184 46185 46186 46187 46188 46189 46190 46191 46192 46193 46194 46195 46196 46197 46198 46199 46200 46201 46202 46203 46204 46205 46206 46207 46208 46209 46210 46211 46212 46213 46214 46215 46216 46217 46218 46219 46220 46221 46222 46223 46224 46225 46226 46227 46228 46229 46230 46231 46232 46233 46234 46235 46236 46237 46238 46239 46240 46241 46242 46243 46244 46245 46246 46247 46248 46249 46250 46251 46252 46253 46254 46255 46256 46257 46258 46259 46260 46261 46262 46263 46264 46265 46266 46267 46268 46269 46270 46271 46272 46273 46274 46275 46276 46277 46278 46279 46280 46281 46282 46283 46284 46285 46286 46287 46288 46289 46290 46291 46292 46293 46294 46295 46296 46297 46298 46299 46300 46301 46302 46303 46304 46305 46306 46307 46308 46309 46310 46311 46312 46313 46314 46315 46316 46317 46318 46319 46320 46321 46322 46323 46324 46325 46326 46327 46328 46329 46330 46331 46332 46333 46334 46335 46336 46337 46338 46339 46340 46341 46342 46343 46344 46345 46346 46347 46348 46349 46350 46351 46352 46353 46354 46355 46356 46357 46358 46359 46360 46361 46362 46363 46364 46365 46366 46367 46368 46369 46370 46371 46372 46373 46374 46375 46376 46377 46378 46379 46380 46381 46382 46383 46384 46385 46386 46387 46388 46389 46390 46391 46392 46393 46394 46395 46396 46397 46398 46399 46400 46401 46402 46403 46404 46405 46406 46407 46408 46409 46410 46411 46412 46413 46414 46415 46416 46417 46418 46419 46420 46421 46422 46423 46424 46425 46426 46427 46428 46429 46430 46431 46432 46433 46434 46435 46436 46437 46438 46439 46440 46441 46442 46443 46444 46445 46446 46447 46448 46449 46450 46451 46452 46453 46454 46455 46456 46457 46458 46459 46460 46461 46462 46463 46464 46465 46466 46467 46468 46469 46470 46471 46472 46473 46474 46475 46476 46477 46478 46479 46480 46481 46482 46483 46484 46485 46486 46487 46488 46489 46490 46491 46492 46493 46494 46495 46496 46497 46498 46499 46500 46501 46502 46503 46504 46505 46506 46507 46508 46509 46510 46511 46512 46513 46514 46515 46516 46517 46518 46519 46520 46521 46522 46523 46524 46525 46526 46527 46528 46529 46530 46531 46532 46533 46534 46535 46536 46537 46538 46539 46540 46541 46542 46543 46544 46545 46546 46547 46548 46549 46550 46551 46552 46553 46554 46555 46556 46557 46558 46559 46560 46561 46562 46563 46564 46565 46566 46567 46568 46569 46570 46571 46572 46573 46574 46575 46576 46577 46578 46579 46580 46581 46582 46583 46584 46585 46586 46587 46588 46589 46590 46591 46592 46593 46594 46595 46596 46597 46598 46599 46600 46601 46602 46603 46604 46605 46606 46607 46608 46609 46610 46611 46612 46613 46614 46615 46616 46617 46618 46619 46620 46621 46622 46623 46624 46625 46626 46627 46628 46629 46630 46631 46632 46633 46634 46635 46636 46637 46638 46639 46640 46641 46642 46643 46644 46645 46646 46647 46648 46649 46650 46651 46652 46653 46654 46655 46656 46657 46658 46659 46660 46661 46662 46663 46664 46665 46666 46667 46668 46669 46670 46671 46672 46673 46674 46675 46676 46677 46678 46679 46680 46681 46682 46683 46684 46685 46686 46687 46688 46689 46690 46691 46692 46693 46694 46695 46696 46697 46698 46699 46700 46701 46702 46703 46704 46705 46706 46707 46708 46709 46710 46711 46712 46713 46714 46715 46716 46717 46718 46719 46720 46721 46722 46723 46724 46725 46726 46727 46728 46729 46730 46731 46732 46733 46734 46735 46736 46737 46738 46739 46740 46741 46742 46743 46744 46745 46746 46747 46748 46749 46750 46751 46752 46753 46754 46755 46756 46757 46758 46759 46760 46761 46762 46763 46764 46765 46766 46767 46768 46769 46770 46771 46772 46773 46774 46775 46776 46777 46778 46779 46780 46781 46782 46783 46784 46785 46786 46787 46788 46789 46790 46791 46792 46793 46794 46795 46796 46797 46798 46799 46800 46801 46802 46803 46804 46805 46806 46807 46808 46809 46810 46811 46812 46813 46814 46815 46816 46817 46818 46819 46820 46821 46822 46823 46824 46825 46826 46827 46828 46829 46830 46831 46832 46833 46834 46835 46836 46837 46838 46839 46840 46841 46842 46843 46844 46845 46846 46847 46848 46849 46850 46851 46852 46853 46854 46855 46856 46857 46858 46859 46860 46861 46862 46863 46864 46865 46866 46867 46868 46869 46870 46871 46872 46873 46874 46875 46876 46877 46878 46879 46880 46881 46882 46883 46884 46885 46886 46887 46888 46889 46890 46891 46892 46893 46894 46895 46896 46897 46898 46899 46900 46901 46902 46903 46904 46905 46906 46907 46908 46909 46910 46911 46912 46913 46914 46915 46916 46917 46918 46919 46920 46921 46922 46923 46924 46925 46926 46927 46928 46929 46930 46931 46932 46933 46934 46935 46936 46937 46938 46939 46940 46941 46942 46943 46944 46945 46946 46947 46948 46949 46950 46951 46952 46953 46954 46955 46956 46957 46958 46959 46960 46961 46962 46963 46964 46965 46966 46967 46968 46969 46970 46971 46972 46973 46974 46975 46976 46977 46978 46979 46980 46981 46982 46983 46984 46985 46986 46987 46988 46989 46990 46991 46992 46993 46994 46995 46996 46997 46998 46999 47000 47001 47002 47003 47004 47005 47006 47007 47008 47009 47010 47011 47012 47013 47014 47015 47016 47017 47018 47019 47020 47021 47022 47023 47024 47025 47026 47027 47028 47029 47030 47031 47032 47033 47034 47035 47036 47037 47038 47039 47040 47041 47042 47043 47044 47045 47046 47047 47048 47049 47050 47051 47052 47053 47054 47055 47056 47057 47058 47059 47060 47061 47062 47063 47064 47065 47066 47067 47068 47069 47070 47071 47072 47073 47074 47075 47076 47077 47078 47079 47080 47081 47082 47083 47084 47085 47086 47087 47088 47089 47090 47091 47092 47093 47094 47095 47096 47097 47098 47099 47100 47101 47102 47103 47104 47105 47106 47107 47108 47109 47110 47111 47112 47113 47114 47115 47116 47117 47118 47119 47120 47121 47122 47123 47124 47125 47126 47127 47128 47129 47130 47131 47132 47133 47134 47135 47136 47137 47138 47139 47140 47141 47142 47143 47144 47145 47146 47147 47148 47149 47150 47151 47152 47153 47154 47155 47156 47157 47158 47159 47160 47161 47162 47163 47164 47165 47166 47167 47168 47169 47170 47171 47172 47173 47174 47175 47176 47177 47178 47179 47180 47181 47182 47183 47184 47185 47186 47187 47188 47189 47190 47191 47192 47193 47194 47195 47196 47197 47198 47199 47200 47201 47202 47203 47204 47205 47206 47207 47208 47209 47210 47211 47212 47213 47214 47215 47216 47217 47218 47219 47220 47221 47222 47223 47224 47225 47226 47227 47228 47229 47230 47231 47232 47233 47234 47235 47236 47237 47238 47239 47240 47241 47242 47243 47244 47245 47246 47247 47248 47249 47250 47251 47252 47253 47254 47255 47256 47257 47258 47259 47260 47261 47262 47263 47264 47265 47266 47267 47268 47269 47270 47271 47272 47273 47274 47275 47276 47277 47278 47279 47280 47281 47282 47283 47284 47285 47286 47287 47288 47289 47290 47291 47292 47293 47294 47295 47296 47297 47298 47299 47300 47301 47302 47303 47304 47305 47306 47307 47308 47309 47310 47311 47312 47313 47314 47315 47316 47317 47318 47319 47320 47321 47322 47323 47324 47325 47326 47327 47328 47329 47330 47331 47332 47333 47334 47335 47336 47337 47338 47339 47340 47341 47342 47343 47344 47345 47346 47347 47348 47349 47350 47351 47352 47353 47354 47355 47356 47357 47358 47359 47360 47361 47362 47363 47364 47365 47366 47367 47368 47369 47370 47371 47372 47373 47374 47375 47376 47377 47378 47379 47380 47381 47382 47383 47384 47385 47386 47387 47388 47389 47390 47391 47392 47393 47394 47395 47396 47397 47398 47399 47400 47401 47402 47403 47404 47405 47406 47407 47408 47409 47410 47411 47412 47413 47414 47415 47416 47417 47418 47419 47420 47421 47422 47423 47424 47425 47426 47427 47428 47429 47430 47431 47432 47433 47434 47435 47436 47437 47438 47439 47440 47441 47442 47443 47444 47445 47446 47447 47448 47449 47450 47451 47452 47453 47454 47455 47456 47457 47458 47459 47460 47461 47462 47463 47464 47465 47466 47467 47468 47469 47470 47471 47472 47473 47474 47475 47476 47477 47478 47479 47480 47481 47482 47483 47484 47485 47486 47487 47488 47489 47490 47491 47492 47493 47494 47495 47496 47497 47498 47499 47500 47501 47502 47503 47504 47505 47506 47507 47508 47509 47510 47511 47512 47513 47514 47515 47516 47517 47518 47519 47520 47521 47522 47523 47524 47525 47526 47527 47528 47529 47530 47531 47532 47533 47534 47535 47536 47537 47538 47539 47540 47541 47542 47543 47544 47545 47546 47547 47548 47549 47550 47551 47552 47553 47554 47555 47556 47557 47558 47559 47560 47561 47562 47563 47564 47565 47566 47567 47568 47569 47570 47571 47572 47573 47574 47575 47576 47577 47578 47579 47580 47581 47582 47583 47584 47585 47586 47587 47588 47589 47590 47591 47592 47593 47594 47595 47596 47597 47598 47599 47600 47601 47602 47603 47604 47605 47606 47607 47608 47609 47610 47611 47612 47613 47614 47615 47616 47617 47618 47619 47620 47621 47622 47623 47624 47625 47626 47627 47628 47629 47630 47631 47632 47633 47634 47635 47636 47637 47638 47639 47640 47641 47642 47643 47644 47645 47646 47647 47648 47649 47650 47651 47652 47653 47654 47655 47656 47657 47658 47659 47660 47661 47662 47663 47664 47665 47666 47667 47668 47669 47670 47671 47672 47673 47674 47675 47676 47677 47678 47679 47680 47681 47682 47683 47684 47685 47686 47687 47688 47689 47690 47691 47692 47693 47694 47695 47696 47697 47698 47699 47700 47701 47702 47703 47704 47705 47706 47707 47708 47709 47710 47711 47712 47713 47714 47715 47716 47717 47718 47719 47720 47721 47722 47723 47724 47725 47726 47727 47728 47729 47730 47731 47732 47733 47734 47735 47736 47737 47738 47739 47740 47741 47742 47743 47744 47745 47746 47747 47748 47749 47750 47751 47752 47753 47754 47755 47756 47757 47758 47759 47760 47761 47762 47763 47764 47765 47766 47767 47768 47769 47770 47771 47772 47773 47774 47775 47776 47777 47778 47779 47780 47781 47782 47783 47784 47785 47786 47787 47788 47789 47790 47791 47792 47793 47794 47795 47796 47797 47798 47799 47800 47801 47802 47803 47804 47805 47806 47807 47808 47809 47810 47811 47812 47813 47814 47815 47816 47817 47818 47819 47820 47821 47822 47823 47824 47825 47826 47827 47828 47829 47830 47831 47832 47833 47834 47835 47836 47837 47838 47839 47840 47841 47842 47843 47844 47845 47846 47847 47848 47849 47850 47851 47852 47853 47854 47855 47856 47857 47858 47859 47860 47861 47862 47863 47864 47865 47866 47867 47868 47869 47870 47871 47872 47873 47874 47875 47876 47877 47878 47879 47880 47881 47882 47883 47884 47885 47886 47887 47888 47889 47890 47891 47892 47893 47894 47895 47896 47897 47898 47899 47900 47901 47902 47903 47904 47905 47906 47907 47908 47909 47910 47911 47912 47913 47914 47915 47916 47917 47918 47919 47920 47921 47922 47923 47924 47925 47926 47927 47928 47929 47930 47931 47932 47933 47934 47935 47936 47937 47938 47939 47940 47941 47942 47943 47944 47945 47946 47947 47948 47949 47950 47951 47952 47953 47954 47955 47956 47957 47958 47959 47960 47961 47962 47963 47964 47965 47966 47967 47968 47969 47970 47971 47972 47973 47974 47975 47976 47977 47978 47979 47980 47981 47982 47983 47984 47985 47986 47987 47988 47989 47990 47991 47992 47993 47994 47995 47996 47997 47998 47999 48000 48001 48002 48003 48004 48005 48006 48007 48008 48009 48010 48011 48012 48013 48014 48015 48016 48017 48018 48019 48020 48021 48022 48023 48024 48025 48026 48027 48028 48029 48030 48031 48032 48033 48034 48035 48036 48037 48038 48039 48040 48041 48042 48043 48044 48045 48046 48047 48048 48049 48050 48051 48052 48053 48054 48055 48056 48057 48058 48059 48060 48061 48062 48063 48064 48065 48066 48067 48068 48069 48070 48071 48072 48073 48074 48075 48076 48077 48078 48079 48080 48081 48082 48083 48084 48085 48086 48087 48088 48089 48090 48091 48092 48093 48094 48095 48096 48097 48098 48099 48100 48101 48102 48103 48104 48105 48106 48107 48108 48109 48110 48111 48112 48113 48114 48115 48116 48117 48118 48119 48120 48121 48122 48123 48124 48125 48126 48127 48128 48129 48130 48131 48132 48133 48134 48135 48136 48137 48138 48139 48140 48141 48142 48143 48144 48145 48146 48147 48148 48149 48150 48151 48152 48153 48154 48155 48156 48157 48158 48159 48160 48161 48162 48163 48164 48165 48166 48167 48168 48169 48170 48171 48172 48173 48174 48175 48176 48177 48178 48179 48180 48181 48182 48183 48184 48185 48186 48187 48188 48189 48190 48191 48192 48193 48194 48195 48196 48197 48198 48199 48200 48201 48202 48203 48204 48205 48206 48207 48208 48209 48210 48211 48212 48213 48214 48215 48216 48217 48218 48219 48220 48221 48222 48223 48224 48225 48226 48227 48228 48229 48230 48231 48232 48233 48234 48235 48236 48237 48238 48239 48240 48241 48242 48243 48244 48245 48246 48247 48248 48249 48250 48251 48252 48253 48254 48255 48256 48257 48258 48259 48260 48261 48262 48263 48264 48265 48266 48267 48268 48269 48270 48271 48272 48273 48274 48275 48276 48277 48278 48279 48280 48281 48282 48283 48284 48285 48286 48287 48288 48289 48290 48291 48292 48293 48294 48295 48296 48297 48298 48299 48300 48301 48302 48303 48304 48305 48306 48307 48308 48309 48310 48311 48312 48313 48314 48315 48316 48317 48318 48319 48320 48321 48322 48323 48324 48325 48326 48327 48328 48329 48330 48331 48332 48333 48334 48335 48336 48337 48338 48339 48340 48341 48342 48343 48344 48345 48346 48347 48348 48349 48350 48351 48352 48353 48354 48355 48356 48357 48358 48359 48360 48361 48362 48363 48364 48365 48366 48367 48368 48369 48370 48371 48372 48373 48374 48375 48376 48377 48378 48379 48380 48381 48382 48383 48384 48385 48386 48387 48388 48389 48390 48391 48392 48393 48394 48395 48396 48397 48398 48399 48400 48401 48402 48403 48404 48405 48406 48407 48408 48409 48410 48411 48412 48413 48414 48415 48416 48417 48418 48419 48420 48421 48422 48423 48424 48425 48426 48427 48428 48429 48430 48431 48432 48433 48434 48435 48436 48437 48438 48439 48440 48441 48442 48443 48444 48445 48446 48447 48448 48449 48450 48451 48452 48453 48454 48455 48456 48457 48458 48459 48460 48461 48462 48463 48464 48465 48466 48467 48468 48469 48470 48471 48472 48473 48474 48475 48476 48477 48478 48479 48480 48481 48482 48483 48484 48485 48486 48487 48488 48489 48490 48491 48492 48493 48494 48495 48496 48497 48498 48499 48500 48501 48502 48503 48504 48505 48506 48507 48508 48509 48510 48511 48512 48513 48514 48515 48516 48517 48518 48519 48520 48521 48522 48523 48524 48525 48526 48527 48528 48529 48530 48531 48532 48533 48534 48535 48536 48537 48538 48539 48540 48541 48542 48543 48544 48545 48546 48547 48548 48549 48550 48551 48552 48553 48554 48555 48556 48557 48558 48559 48560 48561 48562 48563 48564 48565 48566 48567 48568 48569 48570 48571 48572 48573 48574 48575 48576 48577 48578 48579 48580 48581 48582 48583 48584 48585 48586 48587 48588 48589 48590 48591 48592 48593 48594 48595 48596 48597 48598 48599 48600 48601 48602 48603 48604 48605 48606 48607 48608 48609 48610 48611 48612 48613 48614 48615 48616 48617 48618 48619 48620 48621 48622 48623 48624 48625 48626 48627 48628 48629 48630 48631 48632 48633 48634 48635 48636 48637 48638 48639 48640 48641 48642 48643 48644 48645 48646 48647 48648 48649 48650 48651 48652 48653 48654 48655 48656 48657 48658 48659 48660 48661 48662 48663 48664 48665 48666 48667 48668 48669 48670 48671 48672 48673 48674 48675 48676 48677 48678 48679 48680 48681 48682 48683 48684 48685 48686 48687 48688 48689 48690 48691 48692 48693 48694 48695 48696 48697 48698 48699 48700 48701 48702 48703 48704 48705 48706 48707 48708 48709 48710 48711 48712 48713 48714 48715 48716 48717 48718 48719 48720 48721 48722 48723 48724 48725 48726 48727 48728 48729 48730 48731 48732 48733 48734 48735 48736 48737 48738 48739 48740 48741 48742 48743 48744 48745 48746 48747 48748 48749 48750 48751 48752 48753 48754 48755 48756 48757 48758 48759 48760 48761 48762 48763 48764 48765 48766 48767 48768 48769 48770 48771 48772 48773 48774 48775 48776 48777 48778 48779 48780 48781 48782 48783 48784 48785 48786 48787 48788 48789 48790 48791 48792 48793 48794 48795 48796 48797 48798 48799 48800 48801 48802 48803 48804 48805 48806 48807 48808 48809 48810 48811 48812 48813 48814 48815 48816 48817 48818 48819 48820 48821 48822 48823 48824 48825 48826 48827 48828 48829 48830 48831 48832 48833 48834 48835 48836 48837 48838 48839 48840 48841 48842 48843 48844 48845 48846 48847 48848 48849 48850 48851 48852 48853 48854 48855 48856 48857 48858 48859 48860 48861 48862 48863 48864 48865 48866 48867 48868 48869 48870 48871 48872 48873 48874 48875 48876 48877 48878 48879 48880 48881 48882 48883 48884 48885 48886 48887 48888 48889 48890 48891 48892 48893 48894 48895 48896 48897 48898 48899 48900 48901 48902 48903 48904 48905 48906 48907 48908 48909 48910 48911 48912 48913 48914 48915 48916 48917 48918 48919 48920 48921 48922 48923 48924 48925 48926 48927 48928 48929 48930 48931 48932 48933 48934 48935 48936 48937 48938 48939 48940 48941 48942 48943 48944 48945 48946 48947 48948 48949 48950 48951 48952 48953 48954 48955 48956 48957 48958 48959 48960 48961 48962 48963 48964 48965 48966 48967 48968 48969 48970 48971 48972 48973 48974 48975 48976 48977 48978 48979 48980 48981 48982 48983 48984 48985 48986 48987 48988 48989 48990 48991 48992 48993 48994 48995 48996 48997 48998 48999 49000 49001 49002 49003 49004 49005 49006 49007 49008 49009 49010 49011 49012 49013 49014 49015 49016 49017 49018 49019 49020 49021 49022 49023 49024 49025 49026 49027 49028 49029 49030 49031 49032 49033 49034 49035 49036 49037 49038 49039 49040 49041 49042 49043 49044 49045 49046 49047 49048 49049 49050 49051 49052 49053 49054 49055 49056 49057 49058 49059 49060 49061 49062 49063 49064 49065 49066 49067 49068 49069 49070 49071 49072 49073 49074 49075 49076 49077 49078 49079 49080 49081 49082 49083 49084 49085 49086 49087 49088 49089 49090 49091 49092 49093 49094 49095 49096 49097 49098 49099 49100 49101 49102 49103 49104 49105 49106 49107 49108 49109 49110 49111 49112 49113 49114 49115 49116 49117 49118 49119 49120 49121 49122 49123 49124 49125 49126 49127 49128 49129 49130 49131 49132 49133 49134 49135 49136 49137 49138 49139 49140 49141 49142 49143 49144 49145 49146 49147 49148 49149 49150 49151 49152 49153 49154 49155 49156 49157 49158 49159 49160 49161 49162 49163 49164 49165 49166 49167 49168 49169 49170 49171 49172 49173 49174 49175 49176 49177 49178 49179 49180 49181 49182 49183 49184 49185 49186 49187 49188 49189 49190 49191 49192 49193 49194 49195 49196 49197 49198 49199 49200 49201 49202 49203 49204 49205 49206 49207 49208 49209 49210 49211 49212 49213 49214 49215 49216 49217 49218 49219 49220 49221 49222 49223 49224 49225 49226 49227 49228 49229 49230 49231 49232 49233 49234 49235 49236 49237 49238 49239 49240 49241 49242 49243 49244 49245 49246 49247 49248 49249 49250 49251 49252 49253 49254 49255 49256 49257 49258 49259 49260 49261 49262 49263 49264 49265 49266 49267 49268 49269 49270 49271 49272 49273 49274 49275 49276 49277 49278 49279 49280 49281 49282 49283 49284 49285 49286 49287 49288 49289 49290 49291 49292 49293 49294 49295 49296 49297 49298 49299 49300 49301 49302 49303 49304 49305 49306 49307 49308 49309 49310 49311 49312 49313 49314 49315 49316 49317 49318 49319 49320 49321 49322 49323 49324 49325 49326 49327 49328 49329 49330 49331 49332 49333 49334 49335 49336 49337 49338 49339 49340 49341 49342 49343 49344 49345 49346 49347 49348 49349 49350 49351 49352 49353 49354 49355 49356 49357 49358 49359 49360 49361 49362 49363 49364 49365 49366 49367 49368 49369 49370 49371 49372 49373 49374 49375 49376 49377 49378 49379 49380 49381 49382 49383 49384 49385 49386 49387 49388 49389 49390 49391 49392 49393 49394 49395 49396 49397 49398 49399 49400 49401 49402 49403 49404 49405 49406 49407 49408 49409 49410 49411 49412 49413 49414 49415 49416 49417 49418 49419 49420 49421 49422 49423 49424 49425 49426 49427 49428 49429 49430 49431 49432 49433 49434 49435 49436 49437 49438 49439 49440 49441 49442 49443 49444 49445 49446 49447 49448 49449 49450 49451 49452 49453 49454 49455 49456 49457 49458 49459 49460 49461 49462 49463 49464 49465 49466 49467 49468 49469 49470 49471 49472 49473 49474 49475 49476 49477 49478 49479 49480 49481 49482 49483 49484 49485 49486 49487 49488 49489 49490 49491 49492 49493 49494 49495 49496 49497 49498 49499 49500 49501 49502 49503 49504 49505 49506 49507 49508 49509 49510 49511 49512 49513 49514 49515 49516 49517 49518 49519 49520 49521 49522 49523 49524 49525 49526 49527 49528 49529 49530 49531 49532 49533 49534 49535 49536 49537 49538 49539 49540 49541 49542 49543 49544 49545 49546 49547 49548 49549 49550 49551 49552 49553 49554 49555 49556 49557 49558 49559 49560 49561 49562 49563 49564 49565 49566 49567 49568 49569 49570 49571 49572 49573 49574 49575 49576 49577 49578 49579 49580 49581 49582 49583 49584 49585 49586 49587 49588 49589 49590 49591 49592 49593 49594 49595 49596 49597 49598 49599 49600 49601 49602 49603 49604 49605 49606 49607 49608 49609 49610 49611 49612 49613 49614 49615 49616 49617 49618 49619 49620 49621 49622 49623 49624 49625 49626 49627 49628 49629 49630 49631 49632 49633 49634 49635 49636 49637 49638 49639 49640 49641 49642 49643 49644 49645 49646 49647 49648 49649 49650 49651 49652 49653 49654 49655 49656 49657 49658 49659 49660 49661 49662 49663 49664 49665 49666 49667 49668 49669 49670 49671 49672 49673 49674 49675 49676 49677 49678 49679 49680 49681 49682 49683 49684 49685 49686 49687 49688 49689 49690 49691 49692 49693 49694 49695 49696 49697 49698 49699 49700 49701 49702 49703 49704 49705 49706 49707 49708 49709 49710 49711 49712 49713 49714 49715 49716 49717 49718 49719 49720 49721 49722 49723 49724 49725 49726 49727 49728 49729 49730 49731 49732 49733 49734 49735 49736 49737 49738 49739 49740 49741 49742 49743 49744 49745 49746 49747 49748 49749 49750 49751 49752 49753 49754 49755 49756 49757 49758 49759 49760 49761 49762 49763 49764 49765 49766 49767 49768 49769 49770 49771 49772 49773 49774 49775 49776 49777 49778 49779 49780 49781 49782 49783 49784 49785 49786 49787 49788 49789 49790 49791 49792 49793 49794 49795 49796 49797 49798 49799 49800 49801 49802 49803 49804 49805 49806 49807 49808 49809 49810 49811 49812 49813 49814 49815 49816 49817 49818 49819 49820 49821 49822 49823 49824 49825 49826 49827 49828 49829 49830 49831 49832 49833 49834 49835 49836 49837 49838 49839 49840 49841 49842 49843 49844 49845 49846 49847 49848 49849 49850 49851 49852 49853 49854 49855 49856 49857 49858 49859 49860 49861 49862 49863 49864 49865 49866 49867 49868 49869 49870 49871 49872 49873 49874 49875 49876 49877 49878 49879 49880 49881 49882 49883 49884 49885 49886 49887 49888 49889 49890 49891 49892 49893 49894 49895 49896 49897 49898 49899 49900 49901 49902 49903 49904 49905 49906 49907 49908 49909 49910 49911 49912 49913 49914 49915 49916 49917 49918 49919 49920 49921 49922 49923 49924 49925 49926 49927 49928 49929 49930 49931 49932 49933 49934 49935 49936 49937 49938 49939 49940 49941 49942 49943 49944 49945 49946 49947 49948 49949 49950 49951 49952 49953 49954 49955 49956 49957 49958 49959 49960 49961 49962 49963 49964 49965 49966 49967 49968 49969 49970 49971 49972 49973 49974 49975 49976 49977 49978 49979 49980 49981 49982 49983 49984 49985 49986 49987 49988 49989 49990 49991 49992 49993 49994 49995 49996 49997 49998 49999 50000 50001 50002 50003 50004 50005 50006 50007 50008 50009 50010 50011 50012 50013 50014 50015 50016 50017 50018 50019 50020 50021 50022 50023 50024 50025 50026 50027 50028 50029 50030 50031 50032 50033 50034 50035 50036 50037 50038 50039 50040 50041 50042 50043 50044 50045 50046 50047 50048 50049 50050 50051 50052 50053 50054 50055 50056 50057 50058 50059 50060 50061 50062 50063 50064 50065 50066 50067 50068 50069 50070 50071 50072 50073 50074 50075 50076 50077 50078 50079 50080 50081 50082 50083 50084 50085 50086 50087 50088 50089 50090 50091 50092 50093 50094 50095 50096 50097 50098 50099 50100 50101 50102 50103 50104 50105 50106 50107 50108 50109 50110 50111 50112 50113 50114 50115 50116 50117 50118 50119 50120 50121 50122 50123 50124 50125 50126 50127 50128 50129 50130 50131 50132 50133 50134 50135 50136 50137 50138 50139 50140 50141 50142 50143 50144 50145 50146 50147 50148 50149 50150 50151 50152 50153 50154 50155 50156 50157 50158 50159 50160 50161 50162 50163 50164 50165 50166 50167 50168 50169 50170 50171 50172 50173 50174 50175 50176 50177 50178 50179 50180 50181 50182 50183 50184 50185 50186 50187 50188 50189 50190 50191 50192 50193 50194 50195 50196 50197 50198 50199 50200 50201 50202 50203 50204 50205 50206 50207 50208 50209 50210 50211 50212 50213 50214 50215 50216 50217 50218 50219 50220 50221 50222 50223 50224 50225 50226 50227 50228 50229 50230 50231 50232 50233 50234 50235 50236 50237 50238 50239 50240 50241 50242 50243 50244 50245 50246 50247 50248 50249 50250 50251 50252 50253 50254 50255 50256 50257 50258 50259 50260 50261 50262 50263 50264 50265 50266 50267 50268 50269 50270 50271 50272 50273 50274 50275 50276 50277 50278 50279 50280 50281 50282 50283 50284 50285 50286 50287 50288 50289 50290 50291 50292 50293 50294 50295 50296 50297 50298 50299 50300 50301 50302 50303 50304 50305 50306 50307 50308 50309 50310 50311 50312 50313 50314 50315 50316 50317 50318 50319 50320 50321 50322 50323 50324 50325 50326 50327 50328 50329 50330 50331 50332 50333 50334 50335 50336 50337 50338 50339 50340 50341 50342 50343 50344 50345 50346 50347 50348 50349 50350 50351 50352 50353 50354 50355 50356 50357 50358 50359 50360 50361 50362 50363 50364 50365 50366 50367 50368 50369 50370 50371 50372 50373 50374 50375 50376 50377 50378 50379 50380 50381 50382 50383 50384 50385 50386 50387 50388 50389 50390 50391 50392 50393 50394 50395 50396 50397 50398 50399 50400 50401 50402 50403 50404 50405 50406 50407 50408 50409 50410 50411 50412 50413 50414 50415 50416 50417 50418 50419 50420 50421 50422 50423 50424 50425 50426 50427 50428 50429 50430 50431 50432 50433 50434 50435 50436 50437 50438 50439 50440 50441 50442 50443 50444 50445 50446 50447 50448 50449 50450 50451 50452 50453 50454 50455 50456 50457 50458 50459 50460 50461 50462 50463 50464 50465 50466 50467 50468 50469 50470 50471 50472 50473 50474 50475 50476 50477 50478 50479 50480 50481 50482 50483 50484 50485 50486 50487 50488 50489 50490 50491 50492 50493 50494 50495 50496 50497 50498 50499 50500 50501 50502 50503 50504 50505 50506 50507 50508 50509 50510 50511 50512 50513 50514 50515 50516 50517 50518 50519 50520 50521 50522 50523 50524 50525 50526 50527 50528 50529 50530 50531 50532 50533 50534 50535 50536 50537 50538 50539 50540 50541 50542 50543 50544 50545 50546 50547 50548 50549 50550 50551 50552 50553 50554 50555 50556 50557 50558 50559 50560 50561 50562 50563 50564 50565 50566 50567 50568 50569 50570 50571 50572 50573 50574 50575 50576 50577 50578 50579 50580 50581 50582 50583 50584 50585 50586 50587 50588 50589 50590 50591 50592 50593 50594 50595 50596 50597 50598 50599 50600 50601 50602 50603 50604 50605 50606 50607 50608 50609 50610 50611 50612 50613 50614 50615 50616 50617 50618 50619 50620 50621 50622 50623 50624 50625 50626 50627 50628 50629 50630 50631 50632 50633 50634 50635 50636 50637 50638 50639 50640 50641 50642 50643 50644 50645 50646 50647 50648 50649 50650 50651 50652 50653 50654 50655 50656 50657 50658 50659 50660 50661 50662 50663 50664 50665 50666 50667 50668 50669 50670 50671 50672 50673 50674 50675 50676 50677 50678 50679 50680 50681 50682 50683 50684 50685 50686 50687 50688 50689 50690 50691 50692 50693 50694 50695 50696 50697 50698 50699 50700 50701 50702 50703 50704 50705 50706 50707 50708 50709 50710 50711 50712 50713 50714 50715 50716 50717 50718 50719 50720 50721 50722 50723 50724 50725 50726 50727 50728 50729 50730 50731 50732 50733 50734 50735 50736 50737 50738 50739 50740 50741 50742 50743 50744 50745 50746 50747 50748 50749 50750 50751 50752 50753 50754 50755 50756 50757 50758 50759 50760 50761 50762 50763 50764 50765 50766 50767 50768 50769 50770 50771 50772 50773 50774 50775 50776 50777 50778 50779 50780 50781 50782 50783 50784 50785 50786 50787 50788 50789 50790 50791 50792 50793 50794 50795 50796 50797 50798 50799 50800 50801 50802 50803 50804 50805 50806 50807 50808 50809 50810 50811 50812 50813 50814 50815 50816 50817 50818 50819 50820 50821 50822 50823 50824 50825 50826 50827 50828 50829 50830 50831 50832 50833 50834 50835 50836 50837 50838 50839 50840 50841 50842 50843 50844 50845 50846 50847 50848 50849 50850 50851 50852 50853 50854 50855 50856 50857 50858 50859 50860 50861 50862 50863 50864 50865 50866 50867 50868 50869 50870 50871 50872 50873 50874 50875 50876 50877 50878 50879 50880 50881 50882 50883 50884 50885 50886 50887 50888 50889 50890 50891 50892 50893 50894 50895 50896 50897 50898 50899 50900 50901 50902 50903 50904 50905 50906 50907 50908 50909 50910 50911 50912 50913 50914 50915 50916 50917 50918 50919 50920 50921 50922 50923 50924 50925 50926 50927 50928 50929 50930 50931 50932 50933 50934 50935 50936 50937 50938 50939 50940 50941 50942 50943 50944 50945 50946 50947 50948 50949 50950 50951 50952 50953 50954 50955 50956 50957 50958 50959 50960 50961 50962 50963 50964 50965 50966 50967 50968 50969 50970 50971 50972 50973 50974 50975 50976 50977 50978 50979 50980 50981 50982 50983 50984 50985 50986 50987 50988 50989 50990 50991 50992 50993 50994 50995 50996 50997 50998 50999 51000 51001 51002 51003 51004 51005 51006 51007 51008 51009 51010 51011 51012 51013 51014 51015 51016 51017 51018 51019 51020 51021 51022 51023 51024 51025 51026 51027 51028 51029 51030 51031 51032 51033 51034 51035 51036 51037 51038 51039 51040 51041 51042 51043 51044 51045 51046 51047 51048 51049 51050 51051 51052 51053 51054 51055 51056 51057 51058 51059 51060 51061 51062 51063 51064 51065 51066 51067 51068 51069 51070 51071 51072 51073 51074 51075 51076 51077 51078 51079 51080 51081 51082 51083 51084 51085 51086 51087 51088 51089 51090 51091 51092 51093 51094 51095 51096 51097 51098 51099 51100 51101 51102 51103 51104 51105 51106 51107 51108 51109 51110 51111 51112 51113 51114 51115 51116 51117 51118 51119 51120 51121 51122 51123 51124 51125 51126 51127 51128 51129 51130 51131 51132 51133 51134 51135 51136 51137 51138 51139 51140 51141 51142 51143 51144 51145 51146 51147 51148 51149 51150 51151 51152 51153 51154 51155 51156 51157 51158 51159 51160 51161 51162 51163 51164 51165 51166 51167 51168 51169 51170 51171 51172 51173 51174 51175 51176 51177 51178 51179 51180 51181 51182 51183 51184 51185 51186 51187 51188 51189 51190 51191 51192 51193 51194 51195 51196 51197 51198 51199 51200 51201 51202 51203 51204 51205 51206 51207 51208 51209 51210 51211 51212 51213 51214 51215 51216 51217 51218 51219 51220 51221 51222 51223 51224 51225 51226 51227 51228 51229 51230 51231 51232 51233 51234 51235 51236 51237 51238 51239 51240 51241 51242 51243 51244 51245 51246 51247 51248 51249 51250 51251 51252 51253 51254 51255 51256 51257 51258 51259 51260 51261 51262 51263 51264 51265 51266 51267 51268 51269 51270 51271 51272 51273 51274 51275 51276 51277 51278 51279 51280 51281 51282 51283 51284 51285 51286 51287 51288 51289 51290 51291 51292 51293 51294 51295 51296 51297 51298 51299 51300 51301 51302 51303 51304 51305 51306 51307 51308 51309 51310 51311 51312 51313 51314 51315 51316 51317 51318 51319 51320 51321 51322 51323 51324 51325 51326 51327 51328 51329 51330 51331 51332 51333 51334 51335 51336 51337 51338 51339 51340 51341 51342 51343 51344 51345 51346 51347 51348 51349 51350 51351 51352 51353 51354 51355 51356 51357 51358 51359 51360 51361 51362 51363 51364 51365 51366 51367 51368 51369 51370 51371 51372 51373 51374 51375 51376 51377 51378 51379 51380 51381 51382 51383 51384 51385 51386 51387 51388 51389 51390 51391 51392 51393 51394 51395 51396 51397 51398 51399 51400 51401 51402 51403 51404 51405 51406 51407 51408 51409 51410 51411 51412 51413 51414 51415 51416 51417 51418 51419 51420 51421 51422 51423 51424 51425 51426 51427 51428 51429 51430 51431 51432 51433 51434 51435 51436 51437 51438 51439 51440 51441 51442 51443 51444 51445 51446 51447 51448 51449 51450 51451 51452 51453 51454 51455 51456 51457 51458 51459 51460 51461 51462 51463 51464 51465 51466 51467 51468 51469 51470 51471 51472 51473 51474 51475 51476 51477 51478 51479 51480 51481 51482 51483 51484 51485 51486 51487 51488 51489 51490 51491 51492 51493 51494 51495 51496 51497 51498 51499 51500 51501 51502 51503 51504 51505 51506 51507 51508 51509 51510 51511 51512 51513 51514 51515 51516 51517 51518 51519 51520 51521 51522 51523 51524 51525 51526 51527 51528 51529 51530 51531 51532 51533 51534 51535 51536 51537 51538 51539 51540 51541 51542 51543 51544 51545 51546 51547 51548 51549 51550 51551 51552 51553 51554 51555 51556 51557 51558 51559 51560 51561 51562 51563 51564 51565 51566 51567 51568 51569 51570 51571 51572 51573 51574 51575 51576 51577 51578 51579 51580 51581 51582 51583 51584 51585 51586 51587 51588 51589 51590 51591 51592 51593 51594 51595 51596 51597 51598 51599 51600 51601 51602 51603 51604 51605 51606 51607 51608 51609 51610 51611 51612 51613 51614 51615 51616 51617 51618 51619 51620 51621 51622 51623 51624 51625 51626 51627 51628 51629 51630 51631 51632 51633 51634 51635 51636 51637 51638 51639 51640 51641 51642 51643 51644 51645 51646 51647 51648 51649 51650 51651 51652 51653 51654 51655 51656 51657 51658 51659 51660 51661 51662 51663 51664 51665 51666 51667 51668 51669 51670 51671 51672 51673 51674 51675 51676 51677 51678 51679 51680 51681 51682 51683 51684 51685 51686 51687 51688 51689 51690 51691 51692 51693 51694 51695 51696 51697 51698 51699 51700 51701 51702 51703 51704 51705 51706 51707 51708 51709 51710 51711 51712 51713 51714 51715 51716 51717 51718 51719 51720 51721 51722 51723 51724 51725 51726 51727 51728 51729 51730 51731 51732 51733 51734 51735 51736 51737 51738 51739 51740 51741 51742 51743 51744 51745 51746 51747 51748 51749 51750 51751 51752 51753 51754 51755 51756 51757 51758 51759 51760 51761 51762 51763 51764 51765 51766 51767 51768 51769 51770 51771 51772 51773 51774 51775 51776 51777 51778 51779 51780 51781 51782 51783 51784 51785 51786 51787 51788 51789 51790 51791 51792 51793 51794 51795 51796 51797 51798 51799 51800 51801 51802 51803 51804 51805 51806 51807 51808 51809 51810 51811 51812 51813 51814 51815 51816 51817 51818 51819 51820 51821 51822 51823 51824 51825 51826 51827 51828 51829 51830 51831 51832 51833 51834 51835 51836 51837 51838 51839 51840 51841 51842 51843 51844 51845 51846 51847 51848 51849 51850 51851 51852 51853 51854 51855 51856 51857 51858 51859 51860 51861 51862 51863 51864 51865 51866 51867 51868 51869 51870 51871 51872 51873 51874 51875 51876 51877 51878 51879 51880 51881 51882 51883 51884 51885 51886 51887 51888 51889 51890 51891 51892 51893 51894 51895 51896 51897 51898 51899 51900 51901 51902 51903 51904 51905 51906 51907 51908 51909 51910 51911 51912 51913 51914 51915 51916 51917 51918 51919 51920 51921 51922 51923 51924 51925 51926 51927 51928 51929 51930 51931 51932 51933 51934 51935 51936 51937
|
\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 {210.28}
\stardocauthors {R.F. Warren-Smith \& D.S. Berry}
\stardocdate {17th October 2017}
\stardoctitle {AST\linebreak%
A Library for Handling\linebreak%
World Coordinate Systems\linebreak%
in Astronomy}
\stardoccopyright {Copyright (C) 2017 East Asian Observatory}
\stardocversion {V8.6}
\stardocmanual {Programmer's Guide\\(Fortran Version)}
\startitlepic{
\includegraphics[width=0.25\textwidth]{sun210_figures/fronta}~~~~~\hfill
\includegraphics[width=0.25\textwidth]{sun210_figures/frontb}~~~~~\hfill
\includegraphics[width=0.25\textwidth]{sun210_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 Fortran version of this document.\\
For the C version, please see \xref{SUN/211}{sun211}{}.}
\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 Fortran and C interfaces are available (see
\xref{SUN/211}{sun211}{} for the C 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
Fortran and C.
\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]{sun210_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} and
\htmlref{ChebyMap}{ChebyMap}).
\item Lookup tables (the \htmlref{LutMap}{LutMap}).
\item General-purpose transformations expressed using arithmetic
operations and functions similar to those available in Fortran (the
\htmlref{MathMap}{MathMap}).
\item Transformations for internal use within a program, based on
private transformation routines which you write yourself in Fortran
(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]{sun210_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]{sun210_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]{sun210_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]{sun210_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. Routines 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]{sun210_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]{sun210_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]{sun210_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 subroutine 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:
\small
\begin{terminalv}
* Include the interface to the AST library.
INCLUDE 'AST_PAR'
* Declare an integer status variable.
INTEGER STATUS
<maybe other declarations>
* Initialise the status to zero.
STATUS = 0
<maybe some Fortran statements>
* Enclose the parts which use AST between AST_BEGIN and AST_END calls.
CALL AST_BEGIN( STATUS )
<Fortran statements which use AST>
CALL AST_END( STATUS )
<maybe more Fortran statements>
END
\end{terminalv}
\normalsize
The use of \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END} 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\_PAR include 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}
f77 program.f -L/star/lib -I/star/include `ast_link` -o program
\end{terminalv}
\end{small}
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}{}.
To build a program which uses PGPLOT for graphics, use:
\begin{small}
\begin{terminalv}
f77 program.f -L/star/lib `ast_link -pgplot` -o program
\end{terminalv}
\end{small}
again using \verb+g77 -fno-second-underscore+ in place of \verb+f77+
on Linux systems.
For more details about accessing AST include files, 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 an array of character strings
containing a complete set of FITS header cards and NCARD is the number
of cards. Then proceed as follows:
\small
\begin{terminalv}
INTEGER FITSCHAN, ICARD, NCARD, WCSINFO
CHARACTER * ( 80 ) CARDS( NCARD )
...
* Create a FitsChan and fill it with FITS header cards.
FITSCHAN = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS )
DO 1 ICARD = 1, NCARD
CALL AST_PUTFITS( FITSCHAN, CARDS( ICARD ), .FALSE., STATUS )
1 CONTINUE
* Rewind the FitsChan and read WCS information from it.
CALL AST_CLEAR( FITSCHAN, 'Card', STATUS )
WCSINFO = AST_READ( FITSCHAN, STATUS )
\end{terminalv}
\normalsize
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 routine
\xref{NDF\_GTWCS}{sun33}{NDF_GTWCS}---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 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:
\small
\begin{terminalv}
IF ( STATUS .NE. 0 ) THEN
<an error occurred (a message will have been issued)>
ELSE IF ( WCSINFO .EQ. AST__NULL ) THEN
<there was no WCS information present>
ELSE IF ( AST_GETC( WCSINFO, 'Class', STATUS ) .NE. 'FrameSet' ) THEN
<something unexpected was read (i.e. not a FrameSet)>
ELSE
<WCS information was read OK>
END IF
\end{terminalv}
\normalsize
For more information about detecting errors in AST routines, 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}
CALL AST_SHOW( WCSINFO, STATUS )
\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{AST\_SHOW}{AST\_SHOW}, 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:
\small
\begin{terminalv}
INTEGER N
DOUBLE PRECISION XPIXEL( N ), YPIXEL( N )
DOUBLE PRECISION XWORLD( N ), YWORLD( N )
...
CALL AST_TRAN2( WCSINFO, N, XPIXEL, YPIXEL, .TRUE.,
: XWORLD, YWORLD, STATUS )
\end{terminalv}
\normalsize
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{AST\_TRAN2}{AST\_TRAN2} to .FALSE..
To transform points in one dimension, use \htmlref{AST\_TRAN1}{AST\_TRAN1}. In any other
number of dimensions (or if the number of dimensions is initially
unknown), use \htmlref{AST\_TRANN}{AST\_TRANN}. These routines 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}
INTEGER FRAME
LOGICAL ISSKY
...
* Obtain a pointer to the current Frame and determine if it is a
* SkyFrame.
FRAME = AST_GETFRAME( WCSINFO, AST__CURRENT, STATUS )
ISSKY = AST_ISASKYFRAME( FRAME, STATUS )
CALL AST_ANNUL( FRAME, STATUS )
\end{terminalv}
\end{small}
This will set ISSKY to .TRUE.\ if the WCS is a celestial coordinate
system, and to .FALSE.\ 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
AST\_ISASPECFRAME routine
in place of the
AST\_ISASKYFRAME routine.
\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}
CHARACTER * ( 20 ) XTEXT, YTEXT
DOUBLE PRECISION XW, YW
...
XTEXT = AST_FORMAT( WCSINFO, 1, XW, STATUS )
YTEXT = AST_FORMAT( WCSINFO, 2, YW, STATUS )
WRITE ( *, 199 ) XTEXT, YTEXT
199 FORMAT( 'Position = ', A, ', ', A )
\end{terminalv}
\end{small}
Here, the second argument to \htmlref{AST\_FORMAT}{AST\_FORMAT} 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}
CALL AST_SET( WCSINFO, 'Report=1', STATUS )
CALL AST_TRAN2( WCSINFO, N, XPIXEL, YPIXEL, .TRUE.,
: XWORLD, YWORLD, STATUS )
\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}
CHARACTER TEXT * ( 80 )
DOUBLE PRECISION COORD( 10 )
INTEGER IAXIS, N, NAXES, T
...
* Obtain the number of coordinate axes (if not already known).
NAXES = AST_GETI( WCSINFO, 'Naxes', STATUS )
* Loop to read each line of input text, in this case from the
* standard input channel (your programming environment will probably
* provide a better way of reading text than this). Set the index T to
* the start of each line read.
2 CONTINUE
READ( *, '(A)', END=99 ) TEXT
T = 1
* Attempt to read a coordinate for each axis.
DO 3 IAXIS = 1, NAXES
N = AST_UNFORMAT( WCSINFO, IAXIS, TEXT( T : ), COORD( IAXIS ),
: STATUS )
* If nothing was read and this is not the first axis and the end of
* the text has not been reached, try stepping over a separator and
* reading again.
IF ( ( N .EQ. 0 ) .AND. ( IAXIS .GT. 1 ) .AND.
: ( T .LT. LEN( STRING ) ) ) THEN
T = T + 1
N = AST_UNFORMAT( WCSINFO, IAXIS, TEXT( T : ),
COORD( IAXIS ), STATUS )
END IF
* Quit if nothing was read, otherwise move on to the next coordinate.
IF ( N .EQ. 0 ) GO TO 4
T = T + N
3 CONTINUE
4 CONTINUE
* Test for the possible errors that may occur...
* Error detected by AST (a message will have been issued).
IF ( STATUS .NE. 0 ) THEN
GO TO 99
* Error in input data at character TEXT( T + N : T + N ).
ELSE IF ( ( T .LT. LEN( STRING ) ) .OR. ( N .EQ. 0 ) ) THEN
<handle the error, or report your own message here>
GO TO 99
ELSE
<coordinates were read OK>
END IF
* Return to read the next input line.
GO TO 2
99 CONTINUE
\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{AST\_UNFORMAT}{AST\_UNFORMAT} function, see \secref{ss:unformattingaxisvalues}. For
details of how sexagesimal formats are handled, and the forms of input
that may be used for 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 $<i>$):
\begin{description}
\item[CRPIX<i>]\mbox{}\\
hold the pixel coordinates at a reference point
\item[CRVAL<i>]\mbox{}\\
hold the corresponding WCS coordinates at the reference point
\item[CTYPE<i>]\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<i>\_<j>]\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 PRECISION XNEW, XOLD, YNEW, YOLD
DOUBLE PRECISION M( 4 ), Z( 2 )
...
XNEW = XOLD * M( 1 ) + YOLD * M( 2 ) + Z( 1 )
YNEW = XOLD * M( 3 ) + YOLD * M( 4 ) + Z( 2 )
\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}
DOUBLE PRECISION INA( 2 ), INB( 2 ), OUTA( 2 ), OUTB( 2 )
INTEGER MATRIXMAP, WINMAP
...
* Set up the corners of a unit square.
DATA INA / 2 * 0.0D0 /
DATA INB / 2 * 1.0D0 /
* The MatrixMap may be constructed directly from the matrix M.
MATRIXMAP = AST_MATRIXMAP( 2, 2, 0, M, ' ', STATUS )
* For the WinMap, we take the coordinates of the corners of a unit
* square (window) and then shift them by the required amounts.
OUTA( 1 ) = INA( 1 ) + Z( 1 )
OUTA( 2 ) = INA( 2 ) + Z( 2 )
OUTB( 1 ) = INB( 1 ) + Z( 1 )
OUTB( 2 ) = INB( 2 ) + Z( 2 )
* The WinMap will then implement this shift.
WINMAP = AST_WINMAP( 2, INA, INB, OUTA, OUTB, ' ', STATUS )
* Join the two Mappings together, so that they are applied one after
* the other.
NEWMAP = AST_CMPMAP( MATRIXMAP, WINMAP, 1, ' ', STATUS )
\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}
INTEGER WCSINFO1, WCSINFO2
...
* If necessary, make a copy of the WCS calibration, since we are
* about to alter it.
WCSINFO2 = AST_COPY( WCSINFO1, STATUS )
* Re-map the base Frame so that it refers to the new data grid
* instead of the old one.
CALL AST_REMAPFRAME( WCSINFO2, AST__BASE, NEWMAP, STATUS )
\end{terminalv}
\end{small}
This will produce a pointer, WCSINFO2, to a new FrameSet in which all
the coordinate systems associated with the original image are modified
so that they are correctly registered with your 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}
INTEGER FITSCHAN1, WCSINFO1
CHARACTER * ( 20 ) 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 AST_PUTCARDS in
* place of AST_PUTFITS.
FITSCHAN1 = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS )
DO 1 ICARD = 1, NCARD
CALL AST_PUTFITS( FITSCHAN1, CARDS( ICARD ), .FALSE., STATUS )
1 CONTINUE
* Note which encoding has been used for the WCS information.
ENCODE = AST_GETC( FITSCHAN1, 'Encoding', STATUS );
* Rewind the input FitsChan and read the WCS information from it.
CALL AST_CLEAR( FITSCHAN1, 'Card', STATUS )
WCSINFO1 = AST_READ( FITSCHAN1, STATUS )
\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 the resulting string in
the ENCODE variable. This must be done \textbf{before} actually reading
the WCS calibration.
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}
INTEGER FITSCHAN2, JUNK, 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 WCS calibration.
FITSCHAN2 = AST_COPY( FITSCHAN1, STATUS )
* 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.
<details not shown - see below>
* 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.
<this stage depends on your data system, so is not shown>
* 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 )
<maybe some more AST graphics here>
* 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
<the Report attribute is set>
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
<an error has occurred>
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
<an error has occurred>
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
<an error has occurred>
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
ChebyMap
SlaMap
SpecMap
TimeMap
UnitMap
WcsMap
ZoomMap
Frame
<various types of 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)
(<bad>, 2) --> (<bad>, 10)
(2, 4) --> (10, 20)
(3, 6) --> (15, 30)
(4, <bad>) --> (20, <bad>)
(5, 10) --> (25, 50)
(<bad>, <bad>) --> (<bad>, <bad>)
(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
<error in input data>
ELSE
<value read correctly>
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
<error in input data>
ELSE
<values read correctly>
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) --> (<bad>, 2, 3)
(6, 4) --> (<bad>, 4, 6)
(9, 6) --> (<bad>, 6, 9)
(12, 8) --> (<bad>, 8, 12)
(15, 10) --> (<bad>, 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
<conversion is not possible>
ELSE
<conversion is possible>
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
<conversion is not possible>
ELSE
<conversion is possible>
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
<no conversion was possible>
ELSE
<conversion was possible>
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 <file
\end{terminalv}
\normalsize
Alternatively, we could have assigned a value to the SinkFile attribute
before invoking
AST\_READ.
\subsection{Saving and Restoring Multiple Objects}
I/O operations performed on a basic \htmlref{Channel}{Channel} are sequential. This
means that if you write more than one \htmlref{Object}{Object} to a Channel,
each new Object's textual description is simply appended to the
previous one. You can store any number of Objects in this way,
subject only to the storage space you have available.
After you read an Object back from a basic Channel, the
Channel is ``positioned'' at the end of that Object's
textual description. If you then perform another read, you will
read the next Object's textual description and therefore
retrieve the next Object. This process may be repeated to read
each Object in turn. When there are no more Objects to be
read, \htmlref{AST\_READ}{AST\_READ} will return the value AST\_\_NULL to indicate an
\emph{end-of-file}.
\subsection{\label{ss:validatinginput}Validating Input}
The pointer returned by \htmlref{AST\_READ}{AST\_READ} (\secref{ss:readingfromachannel})
could identify any class of \htmlref{Object}{Object}---this is determined entirely by
the external data being read. If it is necessary to test for a
particular class (say a \htmlref{Frame}{Frame}), this may be done as follows using the
appropriate member of the \htmlref{AST\_ISA$<$CLASS$>$}{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
<the Calibration Object has been read>
ELSE
<some other Object has been read>
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 )
<access the current card>
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
<process the card's contents>
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
<the Object is a FrameSet, so use it>
ELSE
<something unexpected was read>
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}
<Frame xmlns="http://www.starlink.ac.uk/ast/xml/"
desc="Coordinate system description">
<_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"/>
<Axis label="Ax1" desc="Coordinate axis">
<!--Axis number 1-->
<_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/>
</Axis>
</Frame>
\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}
<Frame xmlns="http://www.starlink.ac.uk/ast/xml/">
<_attribute name="Naxes" value="1"/>
<_attribute name="Domain" quoted="true" value="SCREEN"/>
<Axis label="Ax1">
<_attribute name="Unit" quoted="true" value="cm"/>
</Axis>
</Frame>
\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
ChebyMap - N-dimensional Chebyshev 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\_CHEBYDOMAIN
}{
Returns the bounding box of the domain of a ChebyMap
}{
\sstdescription{
This routine
returns the upper and lower limits of the box defining the domain
of either the forward or inverse transformation of a \htmlref{ChebyMap}{ChebyMap}. These
are the values that were supplied when the ChebyMap was created.
}
\sstinvocation{
CALL AST\_CHEBYDOMAIN( THIS, FORWARD, LBND, UBND, STATUS )
}
\sstarguments{
\sstsubsection{
THIS = INTEGER (Given)
}{
Pointer to the ChebyMap.
}
\sstsubsection{
FORWARD = LOGICAL (Given)
}{
A .TRUE.
value indicates that the domain of the ChebyMap\texttt{'} s
forward transformation is to be returned, while a zero
value indicates that the domain of the inverse transformation
should be returned.
}
\sstsubsection{
LBND() = DOUBLE PRECISION (Returned)
}{
An
array in which to return the lower axis bounds of the ChebyMap
domain. The number of elements should be at least equal to the
number of ChebyMap inputs (if
FORWARD is .TRUE.), or outputs (if FORWARD is .FALSE.).
}
\sstsubsection{
UBND() = DOUBLE PRECISION (Returned)
}{
An
array in which to return the upper axis bounds of the ChebyMap
domain. The number of elements should be at least equal to the
number of ChebyMap inputs (if
FORWARD is .TRUE.), or outputs (if FORWARD is .FALSE.).
}
\sstsubsection{
STATUS = INTEGER (Given and Returned)
}{
The global status.
}
}
\sstnotes{
\sstitemlist{
\sstitem
If the requested transformation is undefined (i.e. no
transformation coefficients were specified when the ChebyMap was
created), this method returns a box determined using the
\htmlref{AST\_MAPBOX}{AST\_MAPBOX}
method on the opposite transformation, if the opposite
transformation is defined.
\sstitem
If the above procedure fails to determine a bounding box, the supplied
arrays are filled with AST\_\_BAD values but no error is reported.
}
}
}
\sstroutine{
AST\_CHEBYMAP
}{
Create a ChebyMap
}{
\sstdescription{
This function creates a new \htmlref{ChebyMap}{ChebyMap} and optionally initialises
its attributes.
A ChebyMap is a form of \htmlref{Mapping}{Mapping} which performs a Chebyshev polynomial
transformation. Each output coordinate is a linear combination of
Chebyshev polynomials of the first kind, of order zero up to a
specified maximum order, evaluated at the input coordinates. The
coefficients to be used in the linear combination are specified
separately for each output coordinate.
For a 1-dimensional ChebyMap, the forward transformation is defined
as follows:
f(x) = c0.T0(x\texttt{'} ) $+$ c1.T1(x\texttt{'} ) $+$ c2.T2(x\texttt{'} ) $+$ ...
where:
\sstitemlist{
\sstitem
Tn(x\texttt{'} ) is the nth Chebyshev polynomial of the first kind:
\sstitem
T0(x\texttt{'} ) = 1
\sstitem
T1(x\texttt{'} ) = x\texttt{'}
\sstitem
Tn$+$1(x\texttt{'} ) = 2.x\texttt{'} .Tn(x\texttt{'} ) $+$ Tn-1(x\texttt{'} )
\sstitem
x\texttt{'} is the inpux axis value, x, offset and scaled to the range
[-1, 1] as x ranges over a specified bounding box, given when the
ChebyMap is created. The input positions, x, supplied to the
forward transformation must fall within the bounding box - bad
axis values (AST\_\_BAD) are generated for points outside the
bounding box.
}
For an N-dimensional ChebyMap, the forward transformation is a
generalisation of the above form. Each output axis value is the sum
of NCOEFF
terms, where each term is the product of a single coefficient
value and N factors of the form Tn(x\texttt{'} \_i), where \texttt{"} x\texttt{'} \_i\texttt{"} is the
normalised value of the i\texttt{'} th input axis value.
The forward and inverse transformations are defined independantly
by separate sets of coefficients, supplied when the ChebyMap is
created. If no coefficients are supplied to define the inverse
transformation, the
\htmlref{AST\_POLYTRAN}{AST\_POLYTRAN}
method of the parent \htmlref{PolyMap}{PolyMap} class can instead be used to create an
inverse transformation. The inverse transformation so generated
will be a Chebyshev polynomial with coefficients chosen to minimise
the residuals left by a round trip (forward transformation followed
by inverse transformation).
}
\sstinvocation{
RESULT = AST\_CHEBYMAP( NIN, NOUT, NCOEFF\_F, COEFF\_F, NCOEFF\_I, COEFF\_I,
LBND\_F, UBND\_F, LBND\_I, UBND\_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 ChebyMap. 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
ChebyMap output which uses the coefficient within its defining
expression (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 ChebyMap 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 the Chebyshev
polynomial of power 1 evaluated at input coordinate 1, and the
value of the Chebyshev polynomial of power 3 evaluated at input
coordinate 2. 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{"} 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 ChebyMap. 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{
LBND\_F( $*$ ) = DOUBLE PRECISION (Given)
}{
An array containing the lower bounds of the input bounding box within
which the ChebyMap is defined. This argument is not used or
accessed if
NCOEFF\_F is zero.
If supplied, the array should contain
\texttt{"} NIN\texttt{"} elements.
}
\sstsubsection{
UBND\_F( $*$ ) = DOUBLE PRECISION (Given)
}{
An array containing the upper bounds of the input bounding box within
which the ChebyMap is defined. This argument is not used or
accessed if
NCOEFF\_F is zero.
If supplied, the array should contain
\texttt{"} NIN\texttt{"} elements.
}
\sstsubsection{
LBND\_I( $*$ ) = DOUBLE PRECISION (Given)
}{
An array containing the lower bounds of the output bounding box within
which the ChebyMap is defined. This argument is not used or
accessed if
NCOEFF\_I is zero.
If supplied, the array should contain
\texttt{"} NOUT\texttt{"} elements.
}
\sstsubsection{
UBND\_I( $*$ ) = DOUBLE PRECISION (Given)
}{
An array containing the upper bounds of the output bounding box within
which the ChebyMap is defined. This argument is not used or
accessed if
NCOEFF\_I is zero.
If supplied, the array should contain
\texttt{"} NOUT\texttt{"} elements.
}
\sstsubsection{
OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
}{
A character string containing an optional comma-separated
list of attribute assignments to be used for initialising the
new ChebyMap. 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\_CHEBYMAP = INTEGER
}{
A pointer to the new ChebyMap.
}
}
\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\_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
If a Mapping output is found to have a bad value (AST\_\_BAD) at
one or more of the test points used in the linearity test, then all
the values in the returned fit that correspond to that output are
set to AST\_\_BAD. However, this does not affect the linearity tests
on the other Mapping outputs - if they are all found to be linear
then usable coefficients will be returned for them in the fit, and
the function will return a
.TRUE. value.
Consequently, it may be necessary to check that the values in the
returned fit are not AST\_\_BAD before using them. If all Mapping
outputs generate bad values, then
.FALSE. is returned as the function value.
\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\_MAPGETC
}{
Get a scalar or vector value from a KeyMap as a single string
}{
\sstdescription{
This function gets a named value from a \htmlref{KeyMap}{KeyMap} as a single string.
For scalar values it is equivalent to
AST\_MAPGET0C.
If the value is a vector, the returned string is a comma-separated
list of the vector elements, enclosed in parentheses.
}
\sstinvocation{
RESULT = AST\_MAPGETC( 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 = CHARACTER $*$ ( $*$ ) (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 supplied string
are 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\_MAPGETC = 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.
}
}
}
\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 that a character variable
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} (so long as the Frames encapsulated by
the two NormMaps are equal - i.e. have the same class and the same
attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains
a NormMap, the CmpMap will still cancel with its own inverse.
}
\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\_POLYCOEFFS
}{
Retrieve the coefficient values used by a PolyMap
}{
\sstdescription{
This function returns the coefficient values used by either the
forward or inverse transformation of a \htmlref{PolyMap}{PolyMap}, in the same form
that they are supplied to the PolyMap constructor.
Usually, you should call this method first with
NEL
set to zero to determine the number of coefficients used by the
PolyMap. This allows you to allocate an array of the correct size to
hold all coefficient data. You should then call this method a
second time to get the coefficient data.
}
\sstinvocation{
CALL AST\_POLYCOEFFS( THIS, FORWARD, NEL, COEFFS, NCOEFF, STATUS )
}
\sstarguments{
\sstsubsection{
THIS = INTEGER (Given)
}{
Pointer to the original \htmlref{Mapping}{Mapping}.
}
\sstsubsection{
FORWARD = LOGICAL (Given)
}{
If .TRUE.,
the coefficients of the forward PolyMap transformation are
returned. Otherwise the inverse transformation coefficients are
returned.
}
\sstsubsection{
NEL = INTEGER (Given)
}{
The length of the supplied
COEFFS
array. It should be at least \texttt{"} ncoeff$*$( nin $+$ 2 )\texttt{"} if
FORWARD is .TRUE.,
and \texttt{"} ncoeff$*$( nout $+$ 2 )\texttt{"} otherwise, where \texttt{"} ncoeff\texttt{"} is the
number of coefficients to be returned. If a value of zero
is supplied, no coefficient values are returned, but the
number of coefficients used by the transformation is still
returned in
NCOEFF.
}
\sstsubsection{
COEFFS( NEL ) = DOUBLE PRECISION (Returned)
}{
An array in which to return the coefficients used by the
requested transformation of the PolyMap. Ignored if
NEL is zero.
The coefficient data is returned in the form in which it is
supplied to the PolyMap constructor. That is, each group of
\texttt{"} 2 $+$ nin\texttt{"} or \texttt{"} 2 $+$ nout\texttt{"} adjacent elements describe a single
coefficient of the forward or inverse transformation. See the
PolyMap constructor documentation for further details.
If the supplied array is too short to hold all the coefficients,
trailing coefficients are excluded. If the supplied array is
longer than needed to hold all the coefficients, trailing
elements are filled with zeros.
}
\sstsubsection{
NCOEFF = INTEGER (Returned)
}{
The number of coefficients used by the requested transformation.
A value of zero is returned if the transformation does not
have any defining polynomials. A value is returned for this argument
even if
NEL is zero.
}
\sstsubsection{
STATUS = INTEGER (Given and Returned)
}{
The global status.
}
}
}
\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, the default behaviour is to use
an iterative method to evaluate the inverse based only on the forward
transformation (see attribute \htmlref{IterInverse}{IterInverse}).
}
\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
default behaviour is to use an iterative method to evaluate the
inverse based only on the forward transformation (see attribute
IterInverse).
}
\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, a NULL pointer is returned but no 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.
}
}
\sstapplicability{
\sstsubsection{
PolyMap
}{
All PolyMaps have this method.
}
\sstsubsection{
\htmlref{ChebyMap}{ChebyMap}
}{
The returned PolyMap will be a ChebyMap, and the new transformation
will be defined as a weighted sum of Chebyshev functions of the
first kind.
}
}
\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
The \htmlref{IterInverse}{IterInverse} attribute is always cleared in the returned PolyMap.
This means that the returned PolyMap will always use the new fit by
default, rather than the iterative inverse, regardless of the setting
of IterInverse in the supplied PolyMap.
\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. See also AST\_\_PARWGT.
\sstitem
AST\_\_PARWGT: Indicates that a constant weight should be used when
pasting each pixel of the supplied input array into the returned
arrays. This extra weight value should be inserted at the start of the
\texttt{'} PARAMS
array (which should consequently be one element longer than specified in
the \texttt{"} Pixel Spreading Schemes\texttt{"} section in the description of the
AST\_REBIN$<$X$>$ routines).
If the AST\_\_VARWGT flag is also specified, the total weight for
each pixel is the product of the reciprocal of the pixel variance
and the value supplied in the last element of the
\texttt{'} PARAMS array.
\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,
AST\_\_PARWGT 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\_SETPUTERR
}{
Register an error handling routine for use by the AST error model
}{
\sstdescription{
This function can be used to register an external function to be
used to deliver an error message and (optionally) an accompanying
status value to the user.
If this function is not called prior to the first error occuring
within AST, then the external error handling function selected at
link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use an
alternative error handler, call this function before using any other
AST functions, specifying the external error handling function to be
used. This will register the function for future use.
}
\sstinvocation{
CALL \htmlref{AST\_GRFSET}{AST\_GRFSET}( FUN, STATUS )
}
\sstarguments{
\sstsubsection{
FUN = INTEGER FUNCTION (Given)
}{
The name of the routine to be used to handle errors (the name
should also appear in a Fortran EXTERNAL statement in the
routine which invokes AST\_SETPUTERR).
Once a routine has been provided, the \texttt{"} null\texttt{"} routine AST\_NULL can
be supplied in a subsequent call to astSetPutErr to reset the routine
to the corresponding routine 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 Interface
}{
The supplied external function should deliver the supplied error message
and (optionally) the supplied status value to the user or to some
underlying error system. It requires the following interface:
SUBROUTINE PUTERR( STATUS\_VALUE, MESSAGE )
\sstitemlist{
\sstitem
STATUS\_VALUE = INTEGER (Given) -
The error status value.
\sstitem
MESSAGE = CHARACTER $*$ ( $*$ ) (Given) - The error message to be delivered.
}
}
}
\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, NARG, 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{
NARG = INTEGER (Given)
}{
The number of argument values supplied in the
ARGS array.
}
\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, NARG, 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{
NARG = INTEGER (Given)
}{
The number of argument values supplied in the
ARGS array.
}
\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 usual inherited 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 (otherwise zero
should be returned).
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. If
a single dot \texttt{'} .\texttt{'}
is supplied, the current card is tested.
}
\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, NARG, 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{
NARG = INTEGER (Given)
}{
The number of argument values supplied in the
ARGS array.
}
\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,DTAI): Convert a TAI MJD to a UTC MJD.
\sstitem
\texttt{"} UTCTOTAI\texttt{"} (MJDOFF,DTAI): 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,DTAI): Convert a TT MJD to a TDB MJD.
\sstitem
\texttt{"} TDBTOTT\texttt{"} (MJDOFF,OBSLON,OBSLAT,OBSALT,DTAI): 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
DTAI: The value of TAI-UTC (the value returned by astDat is used if
DTAI is AST\_\_BAD).
\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.
If the norm is 0, then the output of the forward transformation is AST\_\_BAD
for each component of the unit vector and 0 for the norm (the final value).
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.
If the provided norm is 0 then the other input values are ignored,
and the output vector is the centre.
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 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 attribute 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{
Dtai
}{
The TAI-UTC correction
}{
\sstdescription{
This attribute specifies the difference between TAI and UTC (i.e.
the number of leap seconds) at the moment corresponding to the
\htmlref{Frame}{Frame}\texttt{'} s \htmlref{Epoch}{Epoch} value. The default value of AST\_\_BAD causes the
number of leap seconds to be determined from an internal look-up
table, which is kept up-to-date manually by the AST development team.
Therefore it is only necessary to assign a value to this attribute
if the version of AST in use is so old that it does not include all
leap seconds that occurred prior to the time represented by the
Frame\texttt{'} s Epoch value.
}
\sstattributetype{
Floating point.
}
\sstapplicability{
\sstsubsection{
Frame
}{
All Frames have this 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 change 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{
FitsTol
}{
Maximum non-linearity allowed when exporting to FITS-WCS
}{
\sstdescription{
This attribute is used when attempting to write a \htmlref{FrameSet}{FrameSet} to a
\htmlref{FitsChan}{FitsChan} using a foreign encoding. It specifies the maximum
departure from linearity allowed on any axis within the mapping
from pixel coordinates to Intermediate World Coordinates. It is
expressed in units of pixels. If an axis of the \htmlref{Mapping}{Mapping} is found
to deviate from linearity by more than this amount, the write
operation fails. If the linearity test succeeds, a linear
approximation to the mapping is used to determine the FITS keyword
values to be placed in the FitsChan.
The default value is one tenth of a pixel.
}
\sstattributetype{
Floating point.
}
\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 original 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.
Note, the term \texttt{"} inverse transformation\texttt{"} here refers to the inverse
transformation of the original PolyMap, ignoring any subsequent
inversions. Also, \texttt{"} input\texttt{"} and \texttt{"} output\texttt{"} refer to the inputs and
outputs of the original PolyMap.
The \htmlref{NiterInverse}{NiterInverse} and \htmlref{TolInverse}{TolInverse} attributes provide parameters that
control the behaviour of the inverse approximation method.
The iterative inverse returns AST\_\_BAD axis values at positions
for which the inverse transformation is undefined. For instance,
if the forward transformation is y = x$*$x, the iterative inverse
will return x = AST\_\_BAD at y = -1. If the inverse transformation
is multiply defined, the position returned by the iterative inverse
will be the position of the solution that is closest to the
supplied position. For instance, using the above example, y = x$*$x,
the iterative inverse will return x = $+$2 at y = 4, because x = $+$2
is the closest solution to 4 (the other solution is x = -2).
}
\sstattributetype{
Integer (boolean).
}
\sstapplicability{
\sstsubsection{
PolyMap
}{
All PolyMaps have this attribute.
}
\sstsubsection{
\htmlref{ChebyMap}{ChebyMap}
}{
The ChebyMap class does not currently provide an option for an
iterative inverse, and so the IterInverse value is always zero.
Setting or clearing the IterInverse attribute of a ChebyMap has
no effect.
}
}
\sstnotes{
\sstitemlist{
\sstitem
The transformation replaced by the iterative algorithm is the
transformation from the original PolyMap output space to the
original PolyMap input space (i.e. the input and output spaces as
defined by the arguments of the PolyMap constructor). This is still
the case even if the PolyMap has subsequently been inverted. In
other words if a PolyMap is created and then inverted, setting
the IterInverse to a non-zero value will replace the forward
transformation of the inverted PolyMap (i.e. the inverse
transformation of the original PolyMap). It is not possible to
replace the other transformation (i.e. from the original PolyMap
input space to the original PolyMap output space) with an iterative
algorithm.
\sstitem
If a PolyMap that has an iterative inverse transformation is
subsequently inverted, the inverted PolyMap will have an iterative
forward transformation.
\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 attribute 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{
Floating point.
}
\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, this
scheme has now been added to the registry of FITS conventions
(http://fits.gsfc.nasa.gov/registry/tpvwcs.html) and headers
that use this convention are created by the SCAMP utility
(http://www.astromatic.net/software/scamp) and the Dark Energy
Camera at NOAO.
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.
}
\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{
SipOK
}{
Use Spitzer Space Telescope keywords to define distortion?
}{
\sstdescription{
This attribute is a boolean value which specifies whether to include
support for the \texttt{"} SIP\texttt{"} scheme, which can be used to add distortion to
basic FITS-WCS projections. This scheme was first defined by the
Spitzer Space Telescope and is described in the following document:
http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf
The default for SipOK is 1.
When using
\htmlref{AST\_READ}{AST\_READ}
to read a FITS-WCS encoded header, a suitable \htmlref{PolyMap}{PolyMap} will always be
included in the returned \htmlref{FrameSet}{FrameSet} if the header contains SIP
keywords, regardless of the value of the SipOK attribute. The PolyMap
will be immediately before the \htmlref{MatrixMap}{MatrixMap} that corresponds to the FITS-WCS
PC or CD matrix.
When using
\htmlref{AST\_WRITE}{AST\_WRITE}
to write a FrameSet to a FITS-WCS encoded header, suitable SIP
keywords will be included in the header if the FrameSet contains a
PolyMap immediately before the MatrixMap that corresponds to the
FITS-WCS PC or CD matrix, but only if the SipOK attribute is non-zero.
If the FrameSet contains a PolyMap but SipOK is zero, then an attempt
will be made to write out the FrameSet without SIP keywords using a
linear approximation to the pixel-to-IWC mapping. If this fails
because the \htmlref{Mapping}{Mapping} exceeds the linearity requirement specified by
attribute \htmlref{FitsTol}{FitsTol},
AST\_WRITE
will return zero, indicating that the FrameSet could not be written
out. Note, SIP headers can only be produced for axes that form part
of a \htmlref{SkyFrame}{SkyFrame}.
Note, the SIP distortion scheme is independent of the TPV/TPN
distortion schemes (see attribute \htmlref{PolyTan}{PolyTan}). A FITS-WCS header could
in principle, contain keywords for both schemes although this is unlikely.
}
\sstattributetype{
Integer (boolean).
}
\sstapplicability{
\sstsubsection{
\htmlref{FitsChan}{FitsChan}
}{
All FitsChans have this attribute.
}
}
}
\sstroutine{
SipReplace
}{
Replace SIP inverse transformation?
}{
\sstdescription{
This attribute is a boolean value which specifies how SIP keywords
should be handled when reading a FITS-WCS encoded header using the
\htmlref{AST\_READ}{AST\_READ}
function. See
http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf
for more information about SIP headers. If SipReplace is non-zero,
then any SIP keywords describing the inverse transformation (i.e. from
WCS to pixel coordinates) are ignored. Instead a new inverse
transformation is found by performing a fit to the forward
transformation. The SipReplace attribute can be set to zero to prevent
this happening. If SipReplace is zero, any SIP keywords describing the
inverse transformation are used as supplied, rather than being
replaced using a new fit. The default value is 1.
}
\sstattributetype{
Integer (boolean).
}
\sstapplicability{
\sstsubsection{
\htmlref{FitsChan}{FitsChan}
}{
All FitsChans have this attribute.
}
}
}
\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 to 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 the 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{
ChebyMap
}{
Map coordinates using Chebyshev polynomial functions
}{
\sstdescription{
A ChebyMap is a form of \htmlref{Mapping}{Mapping} which performs a Chebyshev polynomial
transformation. Each output coordinate is a linear combination of
Chebyshev polynomials of the first kind, of order zero up to a
specified maximum order, evaluated at the input coordinates. The
coefficients to be used in the linear combination are specified
separately for each output coordinate.
For a 1-dimensional ChebyMap, the forward transformation is defined
as follows:
f(x) = c0.T0(x\texttt{'} ) $+$ c1.T1(x\texttt{'} ) $+$ c2.T2(x\texttt{'} ) $+$ ...
where:
\sstitemlist{
\sstitem
Tn(x\texttt{'} ) is the nth Chebyshev polynomial of the first kind:
\sstitem
T0(x\texttt{'} ) = 1
\sstitem
T1(x\texttt{'} ) = x\texttt{'}
\sstitem
Tn$+$1(x\texttt{'} ) = 2.x\texttt{'} .Tn(x\texttt{'} ) $+$ Tn-1(x\texttt{'} )
\sstitem
x\texttt{'} is the inpux axis value, x, offset and scaled to the range
[-1, 1] as x ranges over a specified bounding box, given when the
ChebyMap is created. The input positions, x, supplied to the
forward transformation must fall within the bounding box - bad
axis values (AST\_\_BAD) are generated for points outside the
bounding box.
}
For an N-dimensional ChebyMap, the forward transformation is a
generalisation of the above form. Each output axis value is the sum
of NCOEFF
terms, where each term is the product of a single coefficient
value and N factors of the form Tn(x\texttt{'} \_i), where \texttt{"} x\texttt{'} \_i\texttt{"} is the
normalised value of the i\texttt{'} th input axis value.
The forward and inverse transformations are defined independantly
by separate sets of coefficients, supplied when the ChebyMap is
created. If no coefficients are supplied to define the inverse
transformation, the
\htmlref{AST\_POLYTRAN}{AST\_POLYTRAN}
method of the parent \htmlref{PolyMap}{PolyMap} class can instead be used to create an
inverse transformation. The inverse transformation so generated
will be a Chebyshev polynomial with coefficients chosen to minimise
the residuals left by a round trip (forward transformation followed
by inverse transformation).
}
\sstconstructor{
\htmlref{AST\_CHEBYMAP}{AST\_CHEBYMAP}
}
\sstdiytopic{
Inheritance
}{
The ChebyMap class inherits from the PolyMap class.
}
\sstdiytopic{
Attributes
}{
The ChebyMap class does not define any new attributes beyond those
which are applicable to all PolyMaps.
}
\sstdiytopic{
Functions
}{
In addition to those routines applicable to all PolyMap, the
following routines may also be applied to all ChebyMaps:
\sstitemlist{
\sstitem
\htmlref{AST\_CHEBYDOMAIN}{AST\_CHEBYDOMAIN}: Get the bounds of the domain of the ChebyMap
}
}
}
\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{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection?
\sstitem
\htmlref{SipReplace}{SipReplace}: Replace SIP inverse transformation?
\sstitem
\htmlref{SipOK}{SipOK}: Use Spitzer Space Telescope keywords to define distortion?
\sstitem
\htmlref{SipReplace}{SipReplace}: Replace SIP inverse transformation?
\sstitem
\htmlref{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"} algorithm be recognised?
\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{Dtai}{Dtai}: Difference between the TAI and UTC timescale
\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 stored 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\_MAPGETC}{AST\_MAPGETC}: Get a scalar or vector entry as a single string.
\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} (so long as the Frames encapsulated by
the two NormMaps are equal - i.e. have the same class and the same
attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains
a NormMap, the CmpMap will still cancel with its own inverse.
}
\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, the default behaviour is to use
an iterative method to evaluate the inverse based only on the forward
transformation (see attribute \htmlref{IterInverse}{IterInverse}).
}
\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\_POLYCOEFFS}{AST\_POLYCOEFFS}: Retrieve the coefficients of a PolyMap transformation
\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.
If the norm is 0, then the output of the forward transformation is AST\_\_BAD
for each component of the unit vector and 0 for the norm (the final value).
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.
If the provided norm is 0 then the other input values are ignored,
and the output vector is the centre.
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 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<X>)
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<X>/astRebin<X>) has been added to
the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing
AST\_RESAMPLE<X>/astResample<X> 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<X>/astResample<X>
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<X> 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<X>
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<X>, 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 ``<bad>'' 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 ``<bad>'' 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<X>
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<X>
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<X>
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
``$<major>.<minor>-<release>$'' to ``$<major>.<minor>.<release>$''.
\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<X> 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<X>.
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<X> 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<X> 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{Changes Introduced in V8.3}
The following describes the most significant changes which
occurred in the AST library between versions V8.2.0 and V8.3.0:
\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}
\subsection{Changes Introduced in V8.4}
The following describes the most significant changes which
occurred in the AST library between versions V8.3.0 and V8.4.0:
\begin{enumerate}
\item The PAL library files included in the AST distribution have been updated
to PAL version 0.9.7.
\item Multiple identical NormMaps in series will now be simplified to a
single \htmlref{NormMap}{NormMap}.
\item A NormMap that encapsulates a basic \htmlref{Frame}{Frame} will now be simplified to a
\htmlref{UnitMap}{UnitMap}.
\item The \htmlref{AST\_TIMEADD}{AST\_TIMEADD}
method of the \htmlref{TimeMap}{TimeMap} class now include an extra argument that gives the
number of values supplied in the arguments array. Note, any existing code
that uses this method will need to be changed.
\item The \htmlref{AST\_SLAADD}{AST\_SLAADD}
method of the \htmlref{SlaMap}{SlaMap} class now include an extra argument that gives the
number of values supplied in the arguments array. Note, any existing code
that uses this method will need to be changed.
\item The \htmlref{AST\_SPECADD}{AST\_SPECADD}
method of the \htmlref{SpecMap}{SpecMap} class now include an extra argument that gives the
number of values supplied in the arguments array. Note, any existing code
that uses this method will need to be changed.
\item Multiple identical NormMaps in series will now be simplified to a
single NormMap.
\item A NormMap that encapsulates a basic Frame will now be simplified to a
UnitMap.
\item If the
\htmlref{AST\_MAPREGION}{AST\_MAPREGION}
method is used to map a \htmlref{Region}{Region} into a new Frame that has fewer axes than
the original Region, and if the inverse transformation of the supplied
\htmlref{Mapping}{Mapping} does not specify a value for the missing axes, then those axes
are removed entirely from the Region. Previously they were retained, but
automatically supplied with bad values. This affects the number of mesh
points per axes for such Regions, and so affects the accuracy of overlap
determination.
\end{enumerate}
\subsection{Changes Introduced in V8.5}
The following describes the most significant changes which
occurred in the AST library between versions V8.4.0 and V8.5.1:
\begin{enumerate}
\item - A new class of \htmlref{Mapping}{Mapping} called \htmlref{ChebyMap}{ChebyMap} has been added. This is a
Mapping that implements Chebyshev polynomial transformations.
\item A bug has been fixed in the \htmlref{PolyMap}{PolyMap} class that caused incorrect values
to be returned for the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes if the PolyMap
has been inverted.
\item The \htmlref{KeyMap}{KeyMap} class has a new method called
\htmlref{AST\_MAPGETC}{AST\_MAPGETC}
which returns a named entry as a single string. If the entry is a vector
the returned string is a comma-separated list of its elements, enclosed
in parentheses.
\item If the
routine that delivers error messages to the user (AST\_PUTERR)
is re-implemented, the new version can now be registered at run-time using
the new
\htmlref{AST\_SETPUTERR}{AST\_SETPUTERR} routine.
Previously, the new version needed to be linked into the application at
build time.
\item The \htmlref{Frame}{Frame} class now has a new attribute caled DTAI, which can be used
to specify the number of leap seconds at the moment represented by the
Frame's \htmlref{Epoch}{Epoch} attribute. By default, the internal look-up table of leap
seconds contained within AST is used. The DTAI attribute allows old
versions of AST, which may not include the most recent leap seconds, to
be used with new data.
\item The \htmlref{TimeMap}{TimeMap} class has been changed so that some conversions now require
a ``\htmlref{Dtai}{Dtai}'' value (\emph{i.e.} the number of leap seconds) to be supplied by the
caller. If AST\_\_BAD is supplied for ``Dtai'', the internal look-up table of
leap seconds contained withn AST will be used. The conversions affected
are those between TAI and UTC, and those between TT and TDB.
\end{enumerate}
\subsection{Changes Introduced in V8.6.2}
The following describes the most significant changes which
occurred in the AST library between versions V8.5.1 and V8.6.2:
\begin{enumerate}
\item The astRebinSeq<X> functions accepts a new flag, AST\_\_PARWGT, which
allows the initial weight to be given for the data being pasted into the
output arrays (the initial weight to use should be include in the "params"
array). This initial weight defaults to 1.0 if the AST\_\_PARWGT flag is not
given.
\item The behaviour of the astLinearApprox method of the \htmlref{Mapping}{Mapping} class has
been changed in cases where the Mapping being approximated generates bad
(AST\_\_BAD) values for one or more of its outputs. Previously, any such
Mapping would be deemed non-linear and no fit would be returned. Now, a
fit is returned, provided the other outputs of the Mapping are linear,
but the fit contains AST\_\_BAD values for the coefficients describing the
bad Mapping output.
\item The astWrite method of the \htmlref{FitsChan}{FitsChan} class can now create FITS-WCS headers
that include keyords describing focal plane distortion using the
conventions of the Spitzer SIP scheme. This is however only possible if
the \htmlref{SipOK}{SipOK} attribute of the FitsChan is set to a non-zero value (which is
the default), and the \htmlref{FrameSet}{FrameSet} being written out contains an appropriate
\htmlref{PolyMap}{PolyMap} that conforms to the requirements of the SIP convention.
\item A new function call astCreatedAt is now available that returns the
function name, file path and line number at which an AST object was first
created. Note, there is no Fortran equivalent to this new C function.
\item The number of digits used to format floating point values has been
increased in order to avoid loss of precision when converting from binary
to string and back to binary. This could cause very small changes in numerical
values returned by AST functions.
\item If a FrameSet is supplied as the ``map'' argument to astAddFrame, it now
extracts and stores the base->current Mapping from the supplied FrameSet.
Previously, the entire FrameSet was stored as the Mapping.
\end{enumerate}
\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
Introduced in V8.6.3}
The following describes the most significant changes which have
occurred in the AST library between versions V8.6.2 and V8.6.3 (the
current version):
\begin{enumerate}
\item Small memory leaks in \htmlref{Region}{Region} and \htmlref{FitsChan}{FitsChan} classes have been fixed.
\item A bug that could cause an internal buffer overrun within the FitsChan
class when writing out a FITS-WCS spectral axis with the ``-LOG'' algorithm
has been fixed.
\item The test that a \htmlref{Mapping}{Mapping} conforms to the requirements of the SIP FITS
distortion scheme has been improved.
\item The astRebinSeq method of the Mapping class can now use a different
weight when pasting each separate input data array into the output mosaic.
\end{enumerate}
Programs which are statically linked will need to be re-linked in
order to take advantage of these new facilities.
\end{document}
|