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
|
[IUCr Home Page] [CIF Home Page] [CBF/imgCIF]
----------------------------------------------------------------------
| IUCr Home Page | CIF Home Page | CBF/imgCIF | CBFlib |
| NOTICE | GPL | LGPL | imgCIF dictionary |
| Click Here to Make a Donation |
CBFlib
An API for CBF/imgCIF
Crystallographic Binary Files with ASCII Support
Version 0.9.5
27 April 2014
rev 22 February 2015
by
Paul J. Ellis
Stanford Synchrotron Radiation Laboratory
and
Herbert J. Bernstein
Bernstein + Sons
yaya at bernstein-plus-sons dot com
(c) Copyright 2006, 2007, 2008, 2011, 2013, 2014 Herbert J. Bernstein
----------------------------------------------------------------------
YOU MAY REDISTRIBUTE THE CBFLIB PACKAGE UNDER THE TERMS OF THE GPL.
ALTERNATIVELY YOU MAY REDISTRIBUTE THE CBFLIB API UNDER THE TERMS OF THE
LGPL.
----------------------------------------------------------------------
Before using this software, please read the
NOTICE
for important disclaimers and the IUCr Policy on the Use of the Crystallographic
Information File (CIF) and for other important information.
Work on imgCIF and CBFlib supported in part by the U. S. Department of
Energy (DOE) under grants ER63601-1021466-0009501 and
ER64212-1027708-0011962, by the U. S. National Science Foundation (NSF)
under grants DBI-0610407, DBI-0315281 and EF-0312612, the U. S. National
Institutes of Health (NIH) under grants 1R15GM078077 from NIGMS and
1R13RR023192 from NCRR and funding from the International Union for
Crystallographyn (IUCr). The content is solely the responsibility of the
authors and does not necessarily represent the official views of DOE, NSF,
NIH, NIGMS, NCRR or IUCr. Recent work on integration among CBF, HDF5 and
NeXus supported in part by Pandata ODI (EU 7th Framework Programme)
----------------------------------------------------------------------
Version History
Version Date By Description
0.1 Apr. 1998 PJE This was the first CBFlib release.
It supported binary CBF files using
binary strings.
0.2 Aug. 1998 HJB This release added ascii imgCIF
support using MIME-encoded binary
sections, added the option of MIME
headers for the binary strings was
well. MIME code adapted from mpack
1.5. Added hooks needed for DDL1-style
names without categories.
0.3 Sep. 1998 PJE This release cleaned up the changes
made for version 0.2, allowing
multi-threaded use of the code, and
removing dependence on the mpack
package.
0.4 Nov. 1998 HJB This release merged much of the
message digest code into the general
file reading and writing to reduce the
number of passes. More consistency
checking between the MIME header and
the binary header was introduced. The
size in the MIME header was adjusted
to agree with the version 0.2
documentation.
0.5 Dec. 1998 PJE This release greatly increased the
speed of processing by allowing for
deferred digest evaluation.
0.6 Jan. 1999 HJB This release removed the redundant
information (binary id, size,
compression id) from a binary header
when there is a MIME header, removed
the unused repeat argument, and made
the memory allocation for buffering
and tables with many rows sensitive to
the current memory allocation already
used.
0.6.1 Feb. 2001 HP (per This release fixed a memory leak due
HJB) to misallocation by size of cbf_handle
instead of cbf_handle_struct
0.7 Mar. 2001 PJE This release added high-level
instructions based on the imgCIF
dictionary version 1.1.
0.7.1 Mar. 2001 PJE The high-level functions were
revised to permit future expansion to
files with multiple images.
0.7.2 Apr. 2001 HJB This release adjusted cbf_cimple.c
to conform to cif_img.dic version
1.1.3
0.7.2.1 May 2001 PJE This release corrected an if nesting
error in the prior mod to
cbf_cimple.c.
0.7.3 Oct. 2002 PJE This release modified cbf_simple.c
to reorder image data on read so that
the indices are always increasing in
memory (this behavior was undefined
previously).
0.7.4 Jan 2004 HJB This release fixes a parse error for
quoted strings, adds code to get and
set character string types, and
removes compiler warnings
0.7.5 Apr 2006 HJB This release cleans up some compiler
warnings, corrects a parse error on
quoted strings with a leading blank as
adds the new routines for support of
aliases, dictionaries and real arrays,
higher level routines to get and set
pixel sizes, do cell computations, and
to set beam centers, improves support
for conversion of images, picking up
more data from headers.
0.7.6 Jul 2006 HJB This release reorganizes the kit
into two pieces:
CBFlib_0.7.6_Data_Files and
CBFlib_0.7.6. An optional local copy
of getopt is added. The 1.4 draft
dictionary has been added. cif2cbf
updated to support vcif2 validation.
convert_image and cif2cbf updated to
report text of error messages.
convert_image updated to support tag
and category aliases, default to adxv
images. convert_image and img updated
to support row-major images. Support
added for binning. API Support added
for validation, wide files and line
folding. Logic changed for beam center
reporting. Added new routines:
cbf_validate, cbf_get_bin_sizes,
cbf_set_bin_sizes,
cbf_find_last_typed_child,
cbf_compose_itemname,
cbf_set_cbf_logfile,
cbf_make_widefile, cbf_read_anyfile,
cbf_read_widefile,
cbf_write_local_file,
cbf_write_widefile, cbf_column_number,
cbf_blockitem_number, cbf_log,
cbf_check_category_tags,
cbf_set_beam_center
0.7.7 February 2007 HJB This release reflects changes for
base 32K support developed by G.
Darakev, and changes for support of
reals, 3d arrays, byte_offset
compression and J. P. Abrahams packed
compression made in consultation with
(in alphabetic order) E. Eikenberry,
A. Hammerley, W. Kabsch, M. Kobas, J.
Wright and others at PSI and ESRF in
January 2007, as well accumulated
changes fixing problems in release
0.7.6.
0.7.7.1 February 2007 HJB This release is a patch to 0.7.7 to
change the treatment of the byteorder
parameter from strcpy semantics to
return of a pointer to a string
constant. Our thanks to E. Eikenberry
for pointing out the problem.
0.7.7.2 February 2007 HJB This release is a patch to 0.7.7.1
to add testing for JPA packed
compression and to respect signs
declared in the MIME header.
0.7.7.3 April 2007 HJB This release is a patch to 0.7.7.3
to add f90 support for reading of CBF
byte-offset and packed compression, to
fix problems with gcc 4.4.1 and to
correct errors in multidimensional
packed compression.
0.7.7.4 May 2007 HJB Corrects in handling SLS detector
mincbfs and reorder dimensions versus
arrays for some f90 compilers as per
H. Powell.
0.7.7.5 May 2007 HJB Fix to cbf_get_image for bug
reported by F. Remacle, fixes for
windows builds as per J. Wright and F.
Remacle.
0.7.7.6 Jun 2007 HJB Fix to CBF byte-offset compression
writes, fix to Makefiles and m4 for
f90 test programs to allow adjustable
record length.
0.7.8 Jul 2007 HJB Release for full support of SLS data
files with updated convert_minicbf,
and support for gfortran from gcc 4.2.
0.7.8.1 Jul 2007 HJB Update to 0.7.8 release to fix
memory leaks reported by N. Sauter and
to update validation checks for recent
changes.
0.7.8.2 Dec 2007 CN, HJB Update to 0.7.8.1 to add ADSC jiffie
by Chris Nielsen, and to add ..._fs
and ..._sf macros.
0.7.9 Dec 2007 CN, HJB Identical to 0.7.8.2 except for a
cleanup of deprecated examples, e.g.
diffrn_frame_data
0.7.9.1 Jan 2008 CN, HJB Update to 0.7.8.2 to add inverse
ADSC jiffie by Chris Nielsen, to clean
up problems in handling maps for
RasMol.
0.8.0 Jul 2008 GT, HJB Cleanup of 0.7.9.1 to start 0.8
series.
0.8.1 Jul 2009 EZ, CN, Release with EZ's 2008 DDLm support
PC, GW, using JH's PyCifRW, also cbff f95
JH, HJB wrapper code, PC's java bindings.
0.9.1 Aug 2010 PC, EE, Release with EE's Dectris template
JLM, NS, software, also with vcif3, new
EZ, HJB arvai_test, sequence_match.
0.9.2 Feb 2011 PC, EE, New default release with updated
JLM, NS, pycbf, tiff support, removal of
EZ, HJB default use of PyCifRW to avoid Fedora
license issue.
0.9.3 Oct 2013 JS, HJB Added low-level 'cbf_H5*' functions
for interacting with HDF5, higher
level functions for converting CBF or
miniCBF files to NeXus format, two
utility programs to convert CBF or
miniCBF files to NeXus format and some
unit tests for the low-level 'cbf_H5*'
functions. Add initial FEL detector
support.
0.9.4 March 2014 JS, HJB Refactored implementation of the
NXMX application defintion functional
mapping with improvements to cmake
support and a preliminary effort at
handling Stokes polarization mapping.
This release had serious issues in the
functional mapping axis mapping and
should not be used for production
involving NeXus files.
0.9.5 April 2014 HJB This is a production release for
single detector module single crystal
MX NeXus support.
----------------------------------------------------------------------
Known Problems
The example program tiff2cbf needs the enviroment variable LD_LIBRARY_PATH
set to the location of the lib directory in CBFlib_0.9.2.11, unless a
system install of tiff-3.9.4-rev-6Feb11 has been done.
Due to license issues, PyCifRW is not included with default releases of
CBFlib. Users can download PyCifRW separately.
There are some issues with Peter Chang's lastest java wrapper under the
CBFlib 0.9.2.11 release. Until they are resolved, the CBFlib 0.8.1 release
should be used for Java applications.
This version does not have support for predictor compression.
Code is needed to support array sub-sections.
Foreword
In order to work with CBFlib, you need:
* the source code, in the form of a "gzipped" tar, CBFlib_0.9.5.tar.gz;
and
* the test data:
* CBFlib_0.9.5_Data_Files_Input.tar.gz (17 MB) a "gzipped" tar of
the input data files needed to test the API;
* CBFlib_0.9.5_Data_Files_Output.tar.gz (36 MB) a "gzipped" tar of
the output data files needed to test the API, or, if space is at
a premium;
* CBFlib_0.9.5_Data_Files_Output_Sigs_Only.tar.gz (1 KB) is a
"gzipped" tar of only the MD5 signatures of the output data files
needed to test the API.
If your system has the program wget, you only need the source code. The
download of the other tar balls will be handled automatically.
Be careful about space. A full build and test can use 450 MB or more. If
space is tight, be sure to read the instructions below on using only the
signatures of the test files.
Uncompress and unpack :
* gunzip < CBFlib_0.9.5.tar.gz | tar xvf -
To run the test programs, you will also need Paul Ellis's sample MAR345
image, example.mar2300, Chris Nielsen's sample ADSC Quantum 315 image,
mb_LP_1_001.img, and Eric Eikenberry's SLS sample Pilatus 6m image,
insulin_pilatus6m, as sample data. In addition there are is a PDB mmCIF
file, 9ins.cif, and 3 special test files testflatin.cbf,
testflatpackedin.cbf and testrealin.cbf. All these files will be dowloaded
and extracted by the Makefile from CBFlib_0.9.2.11_Data_Files_Input. Do
not download copies into the top level directory.
In addition, the kit will need tiff and hdf5 libraries.
Thare are various sample Makefiles for common configurations. The
Makefile_OSX samples is for systems with gfortran from prior to the
release of gcc 4.2. For the most recent gfortran, use Makefile_OSX_gcc42.
All the Makefiles are generated from m4/Makefile.m4. For newer OS X
systems, the default Makefile should work.
The Makefiles use GNU make constructs, such as ifeq and ifneq. If you need
to use a different version of make, you will need to edit out the
conditionals
The operation of the Makefiles is sensitive to the following environment
variables:
* CBFLIB_USE_PYCIFRW If you define this environment variable, you may
rebuild the Makefiles to include James Hester's PyCifRW. The process
under bash is:
export CBFLIB_USE_PYCIFRW=yes
cd CBFlib_0.9.5
touch m4/Makefile.m4
make Makefiles
* CBF_DONT_USE_LONG_LONG If you define this environment variable, use of
the long long data type in CBFlib is replaced by use of a struct. The
Makefiles do not need to be rebuilt. Makefile_MINGW does not use the
long long data type even without defining this variable.
* NOFORTRAN If you define this environment variable, use of the fortran
compiler is suppressed.
If necessary, adjust the definition of CC and C++ and other defintions in
Makefile to point to your compilers. Set the definition of CFLAGS to an
appropriate value for your C and C++ compilers, the definition of F90C to
point to your Fortan-90/95 compiler, and the definitions of F90FLAGS and
F90LDFLAGS to approriate values for your Fortan-90/95 compilers, and then
make all
make tests
or, if space is at a premium:
make all
make tests_sigs_only
If you do not have a fortran compiler, you will need edit the Makefile or
to define the variable NOFORTRAN, either in the Makefile or in the
environment
We have included examples of CBF/imgCIF files produced by CBFlib in the
test data CBFlib_0.9.5_Data_Files_Output.tar.gz, the current best draft of
the CBF Extensions Dictionary, and of Andy Hammersley's CBF definition,
updated to become a DRAFT CBF/ImgCIF DEFINITION.
CBFlib 0.9.5 includes a program, tiff2cbf, to convert from tiff files to
CBF files, that requires an augmented version of tiff-3.9.4 called
tiff-3.9.4-rev-6Feb11, that installs into the CBFlib_0.9.2.11 directory.
If a system copy is desired, download and install
http://downloads.sf.net/cbflib/tiff-3.9.4-rev-6Feb11.tar.gz
----------------------------------------------------------------------
Contents
* 1. Introduction
* 2. Function descriptions
* 2.1 General description
* 2.1.1 CBF handles
* 2.1.2 CBF goniometer handles
* 2.1.3 CBF detector handles
* 2.1.4 CBF positioner handles
* 2.1.5 Return values
* 2.2 Reading and writing files containing binary sections
* 2.2.1 Reading binary sections
* 2.2.2 Writing binary sections
* 2.2.3 Summary of reading and writing files containing binary
sections
* 2.2.4 Ordering of array indices
* 2.3 Low-level function prototypes
* 2.3.1 cbf_make_handle
* 2.3.2 cbf_free_handle
* 2.3.3 cbf_read_file, cbf_read_widefile
* 2.3.4 cbf_write_file, cbf_write_widefile
* 2.3.5 cbf_new_datablock, cbf_new_saveframe
* 2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
* 2.3.7 cbf_new_category
* 2.3.8 cbf_force_new_category
* 2.3.9 cbf_new_column
* 2.3.10 cbf_new_row
* 2.3.11 cbf_insert_row
* 2.3.12 cbf_delete_row
* 2.3.13 cbf_set_datablockname, cbf_set_saveframename
* 2.3.14 cbf_reset_datablocks
* 2.3.15 cbf_reset_datablock, cbf_reset_saveframe
* 2.3.16 cbf_reset_category
* 2.3.17 cbf_remove_datablock, cbf_remove_saveframe
* 2.3.18 cbf_remove_category
* 2.3.19 cbf_remove_column
* 2.3.20 cbf_remove_row
* 2.3.21 cbf_rewind_datablock
* 2.3.22 cbf_rewind_category, cbf_rewind_saveframe,
cbf_rewind_blockitem
* 2.3.23 cbf_rewind_column
* 2.3.24 cbf_rewind_row
* 2.3.25 cbf_next_datablock
* 2.3.26 cbf_next_category, cbf_next_saveframe,
cbf_next_blockitem
* 2.3.27 cbf_next_column
* 2.3.28 cbf_next_row
* 2.3.29 cbf_find_datablock
* 2.3.30 cbf_find_category, cbf_find_saveframe,
cbf_find_blockitem
* 2.3.31 cbf_find_column
* 2.3.32 cbf_find_row
* 2.3.33 cbf_find_nextrow
* 2.3.34 cbf_count_datablocks
* 2.3.35 cbf_count_categories, cbf_count_saveframes,
cbf_count_blockitems
* 2.3.36 cbf_count_columns
* 2.3.37 cbf_count_rows
* 2.3.38 cbf_select_datablock
* 2.3.39 cbf_select_category, cbf_select_saveframe,
cbf_select_blockitem
* 2.3.40 cbf_select_column
* 2.3.41 cbf_select_row
* 2.3.42 cbf_datablock_name
* 2.3.43 cbf_category_name
* 2.3.44 cbf_column_name, cbf_set_column_name
* 2.3.45 cbf_row_number
* 2.3.46 cbf_get_value, cbf_require_value
* 2.3.47 cbf_set_value
* 2.3.48 cbf_get_typeofvalue
* 2.3.49 cbf_set_typeofvalue
* 2.3.50 cbf_get_integervalue, cbf_require_integervalue
* 2.3.51 cbf_set_integervalue
* 2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
* 2.3.53 cbf_set_doublevalue
* 2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims,
cbf_get_integerarrayparameters_wdims_fs,
cbf_get_integerarrayparameters_wdims_sf
cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims,
cbf_get_realarrayparameters_wdims_fs,
cbf_get_realarrayparameters_wdims_sf
* 2.3.55 cbf_get_integerarray, cbf_get_realarray
* 2.3.56 cbf_set_integerarray,
cbf_set_integerarray_wdims,
cbf_set_integerarray_wdims_fs,
cbf_set_integerarray_wdims_sf,
cbf_set_realarray,
cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs,
cbf_set_realarray_wdims_sf
* 2.3.57 cbf_failnez
* 2.3.58 cbf_onfailnez
* 2.3.59 cbf_require_datablock
* 2.3.60 cbf_require_category
* 2.3.61 cbf_require_column
* 2.3.62 cbf_require_column_value
* 2.3.63 cbf_require_column_integervalue
* 2.3.64 cbf_require_column_doublevalue
* 2.3.65 cbf_get_local_integer_byte_order,
cbf_get_local_real_byte_order, cbf_get_local_real_format
* 2.3.66 cbf_get_dictionary, cbf_set_dictionary,
cbf_require_dictionary
* 2.3.67 cbf_convert_dictionary
* 2.3.68 cbf_find_tag, cbf_find_local_tag
* 2.3.69 cbf_find_category_root, cbf_set_category_root,
cbf_require_category_root
* 2.3.70 cbf_find_tag_root, cbf_set_tag_root,
cbf_require_tag_root
* 2.3.71 cbf_find_tag_category, cbf_set_tag_category
* 2.4 High-level function prototypes (new for version 0.7)
* 2.4.1 cbf_read_template
* 2.4.2 cbf_get_diffrn_id, cbf_require_diffrn_id
* 2.4.3 cbf_set_diffrn_id
* 2.4.4 cbf_get_crystal_id
* 2.4.5 cbf_set_crystal_id
* 2.4.6 cbf_get_wavelength
* 2.4.7 cbf_set_wavelength
* 2.4.8 cbf_get_polarization
* 2.4.9 cbf_set_polarization
* 2.4.10 cbf_get_divergence
* 2.4.11 cbf_set_divergence
* 2.4.12 cbf_count_elements
* 2.4.13 cbf_get_element_number, cbf_get_element_id
* 2.4.14 cbf_get_gain
* 2.4.15 cbf_set_gain
* 2.4.16 cbf_get_overload
* 2.4.17 cbf_set_overload
* 2.4.18 cbf_get_integration_time
* 2.4.19 cbf_set_integration_time
* 2.4.20 cbf_get_time
* 2.4.21 cbf_set_time
* 2.4.22 cbf_get_date
* 2.4.23 cbf_set_date
* 2.4.24 cbf_set_current_time
* 2.4.25 cbf_get_image_size, cbf_get_image_size_fs,
cbf_get_image_size_fs,
cbf_get_3d_image_size, cbf_get_3d_image_size_fs,
cbf_get_3d_image_size_sf
* 2.4.26 cbf_get_image, cbf_get_image_fs, cbf_get_image_sf,
cbf_get_real_image, cbf_get_real_image_fs,
cbf_get_real_image_sf,
cbf_get_3d_image, cbf_get_3d_image_fs,
cbf_get_3d_image_sf,
cbf_get_real_3d_image, cbf_get_real_3d_image_fs,
cbf_get_real_3d_image_sf
* 2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,
cbf_set_real_image, cbf_set_real_image_fs,
cbf_set_real_image_sf,
cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,
cbf_set_real_3d_image, cbf_set_real_3d_image_fs,
cbf_set_real_3d_image_sf
* 2.4.28 cbf_get_axis_ancestor, cbf_get_axis_depends_on,
cbf_get_axis_equipment, cbf_get_axis_equipment_component,
cbf_get_axis_offset, cbf_get_axis_rotation,
cbf_get_axis_rotation_axis, cbf_get_axis_setting,
cbf_get_axis_type, cbf_get_axis_vector
* 2.4.29 cbf_set_axis_setting
* 2.4.30 cbf_construct_goniometer
* 2.4.31 cbf_free_goniometer
* 2.4.32 cbf_get_rotation_axis
* 2.4.33 cbf_get_rotation_range
* 2.4.34 cbf_rotate_vector
* 2.4.35 cbf_get_reciprocal
* 2.4.36 cbf_construct_detector,
cbf_construct_reference_detector,
cbf_require_reference_detector
* 2.4.37 cbf_free_detector
* 2.4.38 cbf_construct_positioner,
cbf_construct_reference_positioner
* 2.4.39 cbf_free_positioner
* 2.4.40 cbf_get_beam_center, cbf_get_beam_center_fs,
cbf_get_beam_center_sf,
cbf_set_beam_center, cbf_set_beam_center_fs,
cbf_set_beam_center_sf,
cbf_set_reference_beam_center,
cbf_set_reference_beam_center_fs,
cbf_set_reference_beam_center_sf
* 2.4.41 cbf_get_detector_distance
* 2.4.42 cbf_get_detector_normal
* 2.4.43 cbf_get_detector_axis_slow,
cbf_get_detector_axis_fast, cbf_get_detector_axes,
cbf_get_detector_axes_fs, cbf_get_detector_axes_sf,
cbf_get_detector_surface_axes
* 2.4.44 cbf_get_pixel_coordinates,
cbf_get_pixel_coordinates_fs, cbf_get_pixel_coordinates_sf
* 2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs,
cbf_get_pixel_normal_sf
* 2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs,
cbf_get_pixel_area_sf
* 2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs,
cbf_get_pixel_size_sf
* 2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs,
cbf_set_pixel_size_sf
* 2.4.49 cbf_get_inferred_pixel_size,
cbf_get_inferred_pixel_size_fs,
cbf_get_inferred_pixel_size_sf
* 2.4.50 cbf_get_unit_cell
* 2.4.51 cbf_set_unit_cell
* 2.4.52 cbf_get_reciprocal_cell
* 2.4.53 cbf_set_reciprocal_cell
* 2.4.54 cbf_compute_cell_volume
* 2.4.55 cbf_compute_reciprocal_cell
* 2.4.56 cbf_get_orientation_matrix,
cbf_set_orientation_matrix
* 2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes
* 2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise,
cbf_get_axis_reference_poise
* 2.5 F90 function interfaces
* 2.5.1 FCB_ATOL_WCNT
* 2.5.2 FCB_CI_STRNCMPARR
* 2.5.3 FCB_EXIT_BINARY
* 2.5.4 FCB_NBLEN_ARRAY
* 2.5.5 FCB_NEXT_BINARY
* 2.5.6 FCB_OPEN_CIFIN
* 2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2,
FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
FCB_DECOMPRESS_PACKED_3D_I4
* 2.5.8 FCB_READ_BITS
* 2.5.9 FCB_READ_BYTE
* 2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4,
FCB_READ_IMAGE_3D_I2, FCB_READ_IMAGE_3D_I4
* 2.5.11 FCB_READ_LINE
* 2.5.12 FCB_READ_XDS_I2
* 2.5.13 FCB_SKIP_WHITESPACE
* 2.6 HDF5 abstraction layer and convenience functions
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
* 2.6.21 cbf_H5Fopen
* 2.6.22 cbf_H5Fclose
* 2.6.23 cbf_H5Gcreate
* 2.6.24 cbf_H5Gfind
* 2.6.25 cbf_H5Grequire
* 2.6.26 cbf_H5Gfree
* 2.6.27 cbf_H5Ivalid
* 2.6.28 cbf_H5Ocmp
* 2.6.29 cbf_H5Ofree
* 2.6.30 cbf_H5Screate
* 2.6.31 cbf_H5Sfree
* 2.6.32 cbf_H5Tcreate_string
* 2.6.33 cbf_H5Tfree
* 2.7 High-level NeXus-related functions
* 2.7.1 cbf_h5handle_get_file
* 2.7.2 cbf_h5handle_set_file
* 2.7.3 cbf_h5handle_get_entry
* 2.7.4 cbf_h5handle_set_entry
* 2.7.5 cbf_h5handle_require_entry
* 2.7.6 cbf_h5handle_require_entry_definition
* 2.7.7 cbf_h5handle_get_sample
* 2.7.8 cbf_h5handle_set_sample
* 2.7.9 cbf_h5handle_require_sample
* 2.7.10 cbf_h5handle_get_beam
* 2.7.11 cbf_h5handle_set_beam
* 2.7.12 cbf_h5handle_require_beam
* 2.7.13 cbf_h5handle_get_instrument
* 2.7.14 cbf_h5handle_set_instrument
* 2.7.15 cbf_h5handle_find_instrument
* 2.7.16 cbf_h5handle_require_instrument
* 2.7.17 cbf_h5handle_get_detector
* 2.7.18 cbf_h5handle_set_detector
* 2.7.19 cbf_h5handle_find_detector
* 2.7.20 cbf_h5handle_require_detector
* 2.7.21 cbf_h5handle_get_goniometer
* 2.7.22 cbf_h5handle_set_goniometer
* 2.7.23 cbf_h5handle_require_goniometer
* 2.7.24 cbf_h5handle_get_monochromator
* 2.7.25 cbf_h5handle_set_monochromator
* 2.7.26 cbf_h5handle_require_monochromator
* 2.7.27 cbf_h5handle_get_source
* 2.7.28 cbf_h5handle_set_source
* 2.7.29 cbf_h5handle_require_source
* 2.7.30 cbf_free_h5handle
* 2.7.31 cbf_create_h5handle3
* 2.7.32 cbf_write_cbf_h5file
* 2.7.33 cbf_write_cbf2nx
* 2.7.34 cbf_write_minicbf_h5file
* 2.7.35 cbf_write_nx2cbf
* 2.7.36 cbf_config_create
* 2.7.37 cbf_config_parse
* 2.7.38 cbf_config_free
* 2.7.39 cbf_config_strerror
* 3. File format
* 3.1 General description
* 3.2 Format of the binary sections
* 3.2.1 Format of imgCIF binary sections
* 3.2.2 Format of CBF binary sections
* 3.3 Compression schemes
* 3.3.1 Canonical-code compression
* 3.3.2 CCP4-style compression
* 3.3.3 Byte_offset compression
* 3.3.4 Nibble_offset compression
* 3.4 Access to CBFlib compressions from HDF5
* 4. Installation
* 5. Example programs
1. Introduction
CBFlib (Crystallographic Binary File library) is a library of ANSI-C
functions providing a simple mechanism for accessing Crystallographic
Binary Files (CBF files) and Image-supporting CIF (imgCIF) files. The
CBFlib API is loosely based on the CIFPARSE API for mmCIF files. Like
CIFPARSE, CBFlib does not perform any semantic integrity checks; rather it
simply provides functions to create, read, modify and write CBF binary
data files and imgCIF ASCII data files.
Starting with version 0.7.7, an envolving FCBlib (Fortran Crystallographic
Binary library) has been added. As of this release it includes code for
reading byte-offset and packed compression image files created by CBFlib.
2. Function descriptions
2.1 General description
Almost all of the CBFlib functions receive a value of type cbf_handle (a
CBF handle) as the first argument. Several of the high-level CBFlib
functions dealing with geometry receive a value of type cbf_goniometer (a
handle for a CBF goniometer object) or cbf_detector (a handle for a CBF
detector object).
All functions return an integer equal to 0 for success or an error code
for failure.
2.1.1 CBF handles
CBFlib permits a program to use multiple CBF objects simultaneously. To
identify the CBF object on which a function will operate, CBFlib uses a
value of type cbf_handle.
All functions in the library except cbf_make_handle expect a value of type
cbf_handle as the first argument.
The function cbf_make_handle creates and initializes a new CBF handle.
The function cbf_free_handle destroys a handle and frees all memory
associated with the corresponding CBF object.
2.1.2 CBF goniometer handles
To represent the goniometer used to orient a sample, CBFlib uses a value
of type cbf_goniometer.
A goniometer object is created and initialized from a CBF object using the
function cbf_construct_goniometer.
The function cbf_free_goniometer destroys a goniometer handle and frees
all memory associated with the corresponding object.
2.1.3 CBF detector handles
To represent a detector surface mounted on a positioning system, CBFlib
uses a value of type cbf_detector.
A goniometer object is created and initialized from a CBF object using one
of the functions cbf_construct_detector, cbf_construct_reference_detector
or cbf_require_reference_detector.
The function cbf_free_detector destroys a detector handle and frees all
memory associated with the corresponding object.
2.1.4 CBF positioner handles
To represent an arbitrary positioning system designated by the terminal
axis, CBFlib uses a value of type cbf_positioner.
A positioner object is created and initialized from a CBF object using one
of the functions cbf_construct_positioner,
cbf_construct_reference_positioner or cbf_require_reference_positioner.
The function cbf_free_positioner destroys a positioner handle and frees
all memory associated with the corresponding object.
2.1.5 Return values
All of the CBFlib functions return 0 on success and an error code on
failure. The error codes are:
CBF_FORMAT The file format is invalid
CBF_ALLOC Memory allocation failed
CBF_ARGUMENT Invalid function argument
CBF_ASCII The value is ASCII (not binary)
CBF_BINARY The value is binary (not ASCII)
CBF_BITCOUNT The expected number of bits does
not match the actual number written
CBF_ENDOFDATA The end of the data was reached
before the end of the array
CBF_FILECLOSE File close error
CBF_FILEOPEN File open error
CBF_FILEREAD File read error
CBF_FILESEEK File seek error
CBF_FILETELL File tell error
CBF_FILEWRITE File write error
CBF_IDENTICAL A data block with the new name
already exists
CBF_NOTFOUND The data block, category, column or
row does not exist
CBF_OVERFLOW The number read cannot fit into the
destination argument. The destination has
been set to the nearest value.
CBF_UNDEFINED The requested number is not defined (e.g. 0/0; new for
version 0.7).
CBF_NOTIMPLEMENTED The requested functionality is not yet implemented (New
for version 0.7).
If more than one error has occurred, the error code is the logical OR of
the individual error codes.
2.2 Reading and writing files containing binary sections
2.2.1 Reading binary sections
The current version of CBFlib only decompresses a binary section from disk
when requested by the program.
When a file containing one or more binary sections is read, CBFlib saves
the file pointer and the position of the binary section within the file
and then jumps past the binary section. When the program attempts to
access the binary data, CBFlib sets the file position back to the start of
the binary section and then reads the data.
For this scheme to work:
1. The file must be a random-access file opened in binary mode (fopen ( ,"
rb")).
2. The program must not close the file. CBFlib will close the file using
fclose ( ) when it is no longer needed.
At present, this also means that a program cant read a file and then write
back to the same file. This restriction will be eliminated in a future
version.
When reading an imgCIF vs a CBF, the difference is detected automatically.
2.2.2 Writing binary sections
When a program passes CBFlib a binary value, the data is compressed to a
temporary file. If the CBF object is subsequently written to a file, the
data is simply copied from the temporary file to the output file.
The output file can be of any type. If the program indicates to CBFlib
that the file is a random-access and readable, CBFlib will conserve disk
space by closing the temporary file and using the output file as the
location at which the binary value is stored.
For this option to work:
1. The file must be a random-access file opened in binary update mode
(fopen ( , "w+b")).
2. The program must not close the file. CBFlib will close the file using
fclose ( ) when it is no longer needed.
If this option is not used:
1. CBFlib will continue using the temporary file.
2. CBFlib will not close the file. This is the responsibility of the main
program.
2.2.3 Summary of reading and writing files containing binary sections
1. Open disk files to read using the mode "rb".
2. If possible, open disk files to write using the mode "w+b" and tell
CBFlib that it can use the file as a buffer.
3. Do not close any files read by CBFlib or written by CBFlib with
buffering turned on.
4. Do not attempt to read from a file, then write to the same file.
2.2.4 Ordering of array indices
There are two major conventions in the ordering of array indices:
* fs: Fast to slow. The first array index (the one numbered "1") is the
one for which the values of that index change "fastest". That is, as
we move forward in memory, the value of this index changes more
rapidly than any other.
* sf: Slow to fast. The first array index (the one numbered "1") is the
one for which the values of that index change "slowest". That is as we
move forward in memory, the value of this index changes more slowly
than any other.
During the development of CBFlib, both conventions have been used. In
order to avoid confusion, the functions for which array indices are used
are available in three forms: a default version which may used either one
convention or the other, a form in which the name of the function has an
"_fs" suffix for the fast to slow convention and a form in which the name
of the function has a "_sf" suffix for the slow to fast convention.
Designers of applications are advised to use one of the two suffix
conventions. There is no burden on performance for using one convention or
the other. The differences are resolved at compile time by use of
preprocessor macros.
----------------------------------------------------------------------
----------------------------------------------------------------------
2.3 Low-level function prototypes
2.3.1 cbf_make_handle
PROTOTYPE
#include "cbf.h"
int cbf_make_handle (cbf_handle *handle);
DESCRIPTION
cbf_make_handle creates and initializes a new internal CBF object. All
other CBFlib functions operating on this object receive the CBF handle as
the first argument.
ARGUMENTS
handle Pointer to a CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.2 cbf_free_handle
----------------------------------------------------------------------
2.3.2 cbf_free_handle
PROTOTYPE
#include "cbf.h"
int cbf_free_handle (cbf_handle handle);
DESCRIPTION
cbf_free_handle destroys the CBF object specified by the handle and frees
all associated memory.
ARGUMENTS
handle CBF handle to free.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.1 cbf_make_handle
----------------------------------------------------------------------
2.3.3 cbf_read_file, cbf_read_widefile
PROTOTYPE
#include "cbf.h"
int cbf_read_file (cbf_handle handle, FILE *file, int flags);
int cbf_read_widefile (cbf_handle handle, FILE *file, int flags);
DESCRIPTION
cbf_read_file reads the CBF or CIF file file into the CBF object specified
by handle, using the CIF 1.0 convention of 80 character lines.
cbf_read_widefile reads the CBF or CIF file file into the CBF object
specified by handle, using the CIF 1.1 convention of 2048 character lines.
A warning is issued to stderr for ascii lines over the limit. No test is
performed on binary sections.
Validation is performed in three ways levels: during the lexical scan,
during the parse, and, if a dictionary was converted, against the value
types, value enumerations, categories and parent-child relationships
specified in the dictionary.
flags controls the interpretation of binary section headers, the parsing
of brackets constructs and the parsing of treble-quoted strings.
MSG_DIGEST: Instructs CBFlib to check that the digest of
the binary section matches any header digest
value. If the digests do not match, the call
will return CBF_FORMAT. This evaluation and
comparison is delayed (a "lazy" evaluation) to
ensure maximal processing efficiency. If an
immediately evaluation is required, see
MSG_DIGESTNOW, below.
MSG_DIGESTNOW: Instructs CBFlib to check that the digest of
the binary section matches any header digeste
value. If the digests do not match, the call
will return CBF_FORMAT. This evaluation and
comparison is performed during initial parsing
of the section to ensure timely error reporting
at the expense of processing efficiency. If a
more efficient delayed ("lazy") evaluation is
required, see MSG_DIGEST, above.
MSG_DIGESTWARN: Instructs CBFlib to check that the digest of
the binary section matches any header digeste
value. If the digests do not match, a warning
message will be sent to stderr, but processing
will attempt to continue. This evaluation and
comparison is first performed during initial
parsing of the section to ensure timely error
reporting at the expense of processing
efficiency. An mismatch of the message digest
usually indicates a serious error, but it is
sometimes worth continuing processing to try to
isolate the cause of the error. Use this option
with caution.
MSG_NODIGEST: Do not check the digest (default).
PARSE_BRACKETS: Accept DDLm bracket-delimited
[item,item,...item] or {item,item,...item} or
(item,item,...item) constructs as valid,
stripping non-quoted embedded whitespace and
comments. These constructs may span multiple
lines.
PARSE_LIBERAL_BRACKETS: Accept DDLm bracket-delimited
[item,item,...item] or {item,item,...item} or
(item,item,...item) constructs as valid,
stripping embedded non-quoted, non-separating
whitespace and comments. These constructs may
span multiple lines. In this case, whitespace
may be used as an alternative to the comma.
PARSE_TRIPLE_QUOTES: Accept DDLm triple-quoted
"""item,item,...item""" or
'''item,item,...item''' constructs as valid,
stripping embedded whitespace and comments.
These constructs may span multiple lines. If
this flag is set, then ''' will not be
interpreted as a quoted apoptrophe and """ will
not be interpreted as a quoted double quote mark
and
PARSE_NOBRACKETS: Do not accept DDLm bracket-delimited
[item,item,...item] or {item,item,...item} or
(item,item,...item) constructs as valid,
stripping non-quoted embedded whitespace and
comments. These constructs may span multiple
lines.
PARSE_NOTRIPLE_QUOTES: No not accept DDLm triple-quoted
"""item,item,...item""" or
'''item,item,...item''' constructs as valid,
stripping embedded whitespace and comments.
These constructs may span multiple lines. If
this flag is set, then ''' will be interpreted
as a quoted apostrophe and """ will be
interpreted as a quoted double quote mark.
CBFlib defers reading binary sections as long as possible. In the current
version of CBFlib, this means that:
1. The file must be a random-access file opened in binary mode (fopen ( ,
"rb")).
2. The program must not close the file. CBFlib will close the file using
fclose ( ) when it is no longer needed.
These restrictions may change in a future release.
ARGUMENTS
handle CBF handle.
file Pointer to a file descriptor.
headers Controls interprestation of binary section headers.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.4 cbf_write_file
----------------------------------------------------------------------
2.3.4 cbf_write_file
PROTOTYPE
#include "cbf.h"
int cbf_write_file (cbf_handle handle, FILE *file, int readable, int
ciforcbf, int flags, int encoding);
int cbf_write_widefile (cbf_handle handle, FILE *file, int readable, int
ciforcbf, int flags, int encoding);
DESCRIPTION
cbf_write_file writes the CBF object specified by handle into the file
file, following CIF 1.0 conventions of 80 character lines.
cbf_write_widefile writes the CBF object specified by handle into the file
file, following CIF 1.1 conventions of 2048 character lines. A warning is
issued to stderr for ascii lines over the limit, and an attempt is made to
fold lines to fit. No test is performed on binary sections.
If a dictionary has been provided, aliases will be applied on output.
Unlike cbf_read_file, the file does not have to be random-access.
If the file is random-access and readable, readable can be set to non-0 to
indicate to CBFlib that the file can be used as a buffer to conserve disk
space. If the file is not random-access or not readable, readable must be
0.
If readable is non-0, CBFlib will close the file when it is no longer
required, otherwise this is the responsibility of the program.
ciforcbf selects the format in which the binary sections are written:
CIF Write an imgCIF file.
CBF Write a CBF file (default).
flags selects the type of header used in CBF binary sections, selects
whether message digests are generated, and controls the style of output.
The value of flags can be a logical OR of any of:
MIME_HEADERS Use MIME-type headers (default).
MIME_NOHEADERS Use a simple ASCII headers.
MSG_DIGEST Generate message digests for binary data
validation.
MSG_NODIGEST Do not generate message digests (default).
PARSE_BRACKETS Do not convert bracketed strings to text fields
(default).
PARSE_LIBERAL_BRACKETS Do not convert bracketed strings to text fields
(default).
PARSE_NOBRACKETS Convert bracketed strings to text fields
(default).
PARSE_TRIPLE_QUOTES Do not convert triple-quoted strings to text
fields (default).
PARSE_NOTRIPLE_QUOTES Convert triple-quoted strings to text fields
(default).
PAD_1K Pad binary sections with 1023 nulls.
PAD_2K Pad binary sections with 2047 nulls.
PAD_4K Pad binary sections with 4095 nulls.
Note that on output, the types "prns&, "brcs" and "bkts" will be converted
to "text" fields if PARSE_NOBRACKETS has been set flags, and that the
types "tsqs" and "tdqs" will be converted to "text" fields if the flag
PARSE_NOTRIPLE_QUOTES has been set in the flags. It is an error to set
PARSE_NOBRACKETS and to set either PARSE_BRACKETS or
PARSE_LIBERAL_BRACKETS. It is an error to set both PARSE_NOTRIPLE_QUOTES
and PARSE_TRIPLE_QUOTES.
encoding selects the type of encoding used for binary sections and the
type of line-termination in imgCIF files. The value can be a logical OR of
any of:
ENC_BASE64 Use BASE64 encoding (default).
ENC_QP Use QUOTED-PRINTABLE encoding.
ENC_BASE8 Use BASE8 (octal) encoding.
ENC_BASE10 Use BASE10 (decimal) encoding.
ENC_BASE16 Use BASE16 (hexadecimal) encoding.
ENC_FORWARD For BASE8, BASE10 or BASE16 encoding, map bytes to words
forward (1234) (default on little-endian machines).
ENC_BACKWARD Map bytes to words backward (4321) (default on big-endian
machines).
ENC_CRTERM Terminate lines with CR.
ENC_LFTERM Terminate lines with LF (default).
ARGUMENTS
handle CBF handle.
file Pointer to a file descriptor.
readable If non-0: this file is random-access and readable and can be
used as a buffer.
ciforcbf Selects the format in which the binary sections are written
(CIF/CBF).
headers Selects the type of header in CBF binary sections and message
digest generation.
encoding Selects the type of encoding used for binary sections and the
type of line-termination in imgCIF files.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.3 cbf_read_file
----------------------------------------------------------------------
2.3.5 cbf_new_datablock, cbf_new_saveframe
PROTOTYPE
#include "cbf.h"
int cbf_new_datablock (cbf_handle handle, const char *datablockname);
int cbf_new_saveframe (cbf_handle handle, const char *saveframename);
DESCRIPTION
cbf_new_datablock creates a new data block with name datablockname and
makes it the current data block. cbf_new_saveframe creates a new save
frame with name saveframename within the current data block and makes the
new save frame the current save frame.
If a data block or save frame with this name already exists, the existing
data block or save frame becomes the current data block or save frame.
ARGUMENTS
handle CBF handle.
datablockname The name of the new data block.
saveframename The name of the new save frame.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.12 cbf_set_datablockname, cbf_set_saveframename
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
PROTOTYPE
#include "cbf.h"
int cbf_force_new_datablock (cbf_handle handle, const char
*datablockname);
int cbf_force_new_saveframe (cbf_handle handle, const char
*saveframename);
DESCRIPTION
cbf_force_new_datablock creates a new data block with name datablockname
and makes it the current data block. Duplicate data block names are
allowed. cbf_force_new_saveframe creates a new savew frame with name
saveframename and makes it the current save frame. Duplicate save frame
names are allowed.
Even if a save frame with this name already exists, a new save frame is
created and becomes the current save frame.
ARGUMENTS
handle CBF handle.
datablockname The name of the new data block.
saveframename The name of the new save frame.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.12 cbf_set_datablockname, cbf_set_saveframename
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.7 cbf_new_category
PROTOTYPE
#include "cbf.h"
int cbf_new_category (cbf_handle handle, const char *categoryname);
DESCRIPTION
cbf_new_category creates a new category in the current data block with
name categoryname and makes it the current category.
If a category with this name already exists, the existing category becomes
the current category.
ARGUMENTS
handle CBF handle.
categoryname The name of the new category.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.18 cbf_remove_category
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.8 cbf_force_new_category
PROTOTYPE
#include "cbf.h"
int cbf_force_new_category (cbf_handle handle, const char *categoryname);
DESCRIPTION
cbf_force_new_category creates a new category in the current data block
with name categoryname and makes it the current category. Duplicate
category names are allowed.
Even if a category with this name already exists, a new category of the
same name is created and becomes the current category. The allows for the
creation of unlooped tag/value lists drawn from the same category.
ARGUMENTS
handle CBF handle.
categoryname The name of the new category.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
2.3.7 cbf_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.18 cbf_remove_category
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.9 cbf_new_column
PROTOTYPE
#include "cbf.h"
int cbf_new_column (cbf_handle handle, const char *columnname);
DESCRIPTION
cbf_new_column creates a new column in the current category with name
columnname and makes it the current column.
If a column with this name already exists, the existing column becomes the
current category.
ARGUMENTS
handle CBF handle.
columnname The name of the new column.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.19 cbf_remove_column
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.10 cbf_new_row
PROTOTYPE
#include "cbf.h"
int cbf_new_row (cbf_handle handle);
DESCRIPTION
cbf_new_row adds a new row to the current category and makes it the
current row.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.11 cbf_insert_row
2.3.12 cbf_delete_row
2.3.20 cbf_remove_row
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.11 cbf_insert_row
PROTOTYPE
#include "cbf.h"
int cbf_insert_row (cbf_handle handle, unsigned int rownumber);
DESCRIPTION
cbf_insert_row adds a new row to the current category. The new row is
inserted as row rownumber and existing rows starting from rownumber are
moved up by 1. The new row becomes the current row.
If the category has fewer than rownumber rows, the function returns
CBF_NOTFOUND.
The row numbers start from 0.
ARGUMENTS
handle CBF handle.
rownumber The row number of the new row.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.12 cbf_delete_row
2.3.20 cbf_remove_row
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.12 cbf_delete_row
PROTOTYPE
#include "cbf.h"
int cbf_delete_row (cbf_handle handle, unsigned int rownumber);
DESCRIPTION
cbf_delete_row deletes a row from the current category. Rows starting from
rownumber +1 are moved down by 1. If the current row was higher than
rownumber, or if the current row is the last row, it will also move down
by 1.
The row numbers start from 0.
ARGUMENTS
handle CBF handle.
rownumber The number of the row to delete.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
2.3.18 cbf_remove_category
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.13 cbf_set_datablockname, cbf_set_saveframename
PROTOTYPE
#include "cbf.h"
int cbf_set_datablockname (cbf_handle handle, const char *datablockname);
int cbf_set_saveframename (cbf_handle handle, const char *saveframename);
DESCRIPTION
cbf_set_datablockname changes the name of the current data block to
datablockname. cbf_set_saveframename changes the name of the current save
frame to saveframename.
If a data block or save frame with this name already exists (comparison is
case-insensitive), the function returns CBF_IDENTICAL.
ARGUMENTS
handle CBF handle.
datablockname The new data block name.
datablockname The new save frame name.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.14 cbf_reset_datablocks
2.3.15 cbf_reset_datablock, cbf_reset_saveframe
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
2.3.42 cbf_datablock_name
----------------------------------------------------------------------
2.3.14 cbf_reset_datablocks
PROTOTYPE
#include "cbf.h"
int cbf_reset_datablocks (cbf_handle handle);
DESCRIPTION
cbf_reset_datablocks deletes all categories from all data blocks.
The current data block does not change.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.15 cbf_reset_datablock, cbf_reset_saveframe
2.3.18 cbf_remove_category
----------------------------------------------------------------------
2.3.15 cbf_reset_datablock, cbf_reset_datablock
PROTOTYPE
#include "cbf.h"
int cbf_reset_datablock (cbf_handle handle);
int cbf_reset_saveframe (cbf_handle handle);
DESCRIPTION
cbf_reset_datablock deletes all categories from the current data block.
cbf_reset_saveframe deletes all categories from the current save frame.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.14 cbf_reset_datablocks
2.3.18 cbf_remove_category
----------------------------------------------------------------------
2.3.16 cbf_reset_category
PROTOTYPE
#include "cbf.h"
int cbf_reset_category (cbf_handle handle);
DESCRIPTION
cbf_reset_category deletes all columns and rows from current category.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.16 cbf_reset_category
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row
----------------------------------------------------------------------
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
PROTOTYPE
#include "cbf.h"
int cbf_remove_datablock (cbf_handle handle);
int cbf_remove_saveframe (cbf_handle handle);
DESCRIPTION
cbf_remove_datablock deletes the current data block. cbf_remove_saveframe
deletes the current save frame.
The current data block becomes undefined.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.5 cbf_new_datablock, cbf_new_saveframe
2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
2.3.18 cbf_remove_category
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.18 cbf_remove_category
PROTOTYPE
#include "cbf.h"
int cbf_remove_category (cbf_handle handle);
DESCRIPTION
cbf_remove_category deletes the current category.
The current category becomes undefined.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.19 cbf_remove_column
PROTOTYPE
#include "cbf.h"
int cbf_remove_column (cbf_handle handle);
DESCRIPTION
cbf_remove_column deletes the current column.
The current column becomes undefined.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.9 cbf_new_column
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
2.3.18 cbf_remove_category
2.3.20 cbf_remove_row
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.20 cbf_remove_row
PROTOTYPE
#include "cbf.h"
int cbf_remove_row (cbf_handle handle);
DESCRIPTION
cbf_remove_row deletes the current row in the current category.
If the current row was the last row, it will move down by 1, otherwise, it
will remain the same.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.17 cbf_remove_datablock, cbf_remove_saveframe
2.3.18 cbf_remove_category
2.3.19 cbf_remove_column
2.3.12 cbf_delete_row
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.21 cbf_rewind_datablock
PROTOTYPE
#include "cbf.h"
int cbf_rewind_datablock (cbf_handle handle);
DESCRIPTION
cbf_rewind_datablock makes the first data block the current data block.
If there are no data blocks, the function returns CBF_NOTFOUND.
The current category becomes undefined.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
2.3.19 cbf_rewind_column
2.3.24 cbf_rewind_row
2.3.25 cbf_next_datablock
----------------------------------------------------------------------
2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
PROTOTYPE
#include "cbf.h"
int cbf_rewind_category (cbf_handle handle);
int cbf_rewind_saveframe (cbf_handle handle);
int cbf_rewind_blockitem (cbf_handle handle, CBF_NODETYPE * type);
DESCRIPTION
cbf_rewind_category makes the first category in the current data block the
current category. cbf_rewind_saveframe makes the first saveframe in the
current data block the current saveframe. cbf_rewind_blockitem makes the
first blockitem (category or saveframe) in the current data block the
current blockitem. The type of the blockitem (CBF_CATEGORY or
CBF_SAVEFRAME) is returned in type.
If there are no categories, saveframes or blockitems the function returns
CBF_NOTFOUND.
The current column and row become undefined.
ARGUMENTS
handle CBF handle.
type CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.21 cbf_rewind_datablock
2.3.19 cbf_rewind_column
2.3.24 cbf_rewind_row
2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
----------------------------------------------------------------------
2.3.23 cbf_rewind_column
PROTOTYPE
#include "cbf.h"
int cbf_rewind_column (cbf_handle handle);
DESCRIPTION
cbf_rewind_column makes the first column in the current category the
current column.
If there are no columns, the function returns CBF_NOTFOUND.
The current row is not affected.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.21 cbf_rewind_datablock
2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
2.3.24 cbf_rewind_row
2.3.27 cbf_next_column
----------------------------------------------------------------------
2.3.24 cbf_rewind_row
PROTOTYPE
#include "cbf.h"
int cbf_rewind_row (cbf_handle handle);
DESCRIPTION
cbf_rewind_row makes the first row in the current category the current
row.
If there are no rows, the function returns CBF_NOTFOUND.
The current column is not affected.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.21 cbf_rewind_datablock
2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
2.3.19 cbf_rewind_column
2.3.28 cbf_next_row
----------------------------------------------------------------------
2.3.25 cbf_next_datablock
PROTOTYPE
#include "cbf.h"
int cbf_next_datablock (cbf_handle handle);
DESCRIPTION
cbf_next_datablock makes the data block following the current data block
the current data block.
If there are no more data blocks, the function returns CBF_NOTFOUND.
The current category becomes undefined.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.21 cbf_rewind_datablock
2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
2.3.27 cbf_next_column
2.3.28 cbf_next_row
----------------------------------------------------------------------
2.3.26 cbf_next_category
PROTOTYPE
#include "cbf.h"
int cbf_next_category (cbf_handle handle);
DESCRIPTION
cbf_next_category makes the category following the current category in the
current data block the current category.
If there are no more categories, the function returns CBF_NOTFOUND.
The current column and row become undefined.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
2.3.25 cbf_next_datablock
2.3.27 cbf_next_column
2.3.27 cbf_next_row
----------------------------------------------------------------------
2.3.27 cbf_next_column
PROTOTYPE
#include "cbf.h"
int cbf_next_column (cbf_handle handle);
DESCRIPTION
cbf_next_column makes the column following the current column in the
current category the current column.
If there are no more columns, the function returns CBF_NOTFOUND.
The current row is not affected.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.19 cbf_rewind_column
2.3.25 cbf_next_datablock
2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
2.3.28 cbf_next_row
----------------------------------------------------------------------
2.3.28 cbf_next_row
PROTOTYPE
#include "cbf.h"
int cbf_next_row (cbf_handle handle);
DESCRIPTION
cbf_next_row makes the row following the current row in the current
category the current row.
If there are no more rows, the function returns CBF_NOTFOUND.
The current column is not affected.
ARGUMENTS
handle CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.24 cbf_rewind_row
2.3.25 cbf_next_datablock
2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
2.3.27 cbf_next_column
----------------------------------------------------------------------
2.3.29 cbf_find_datablock
PROTOTYPE
#include "cbf.h"
int cbf_find_datablock (cbf_handle handle, const char *datablockname);
DESCRIPTION
cbf_find_datablock makes the data block with name datablockname the
current data block.
The comparison is case-insensitive.
If the data block does not exist, the function returns CBF_NOTFOUND.
The current category becomes undefined.
ARGUMENTS
handle CBF handle.
datablockname The name of the data block to find.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.21 cbf_rewind_datablock
2.3.25 cbf_next_datablock
2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.42 cbf_datablock_name
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.30 cbf_find_category
PROTOTYPE
#include "cbf.h"
int cbf_find_category (cbf_handle handle, const char *categoryname);
DESCRIPTION
cbf_find_category makes the category in the current data block with name
categoryname the current category.
The comparison is case-insensitive.
If the category does not exist, the function returns CBF_NOTFOUND.
The current column and row become undefined.
ARGUMENTS
handle CBF handle.
categoryname The name of the category to find.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
2.3.29 cbf_find_datablock
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.43 cbf_category_name
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.31 cbf_find_column
PROTOTYPE
#include "cbf.h"
int cbf_find_column (cbf_handle handle, const char *columnname);
DESCRIPTION
cbf_find_column makes the columns in the current category with name
columnname the current column.
The comparison is case-insensitive.
If the column does not exist, the function returns CBF_NOTFOUND.
The current row is not affected.
ARGUMENTS
handle CBF handle.
columnname The name of column to find.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.19 cbf_rewind_column
2.3.27 cbf_next_column
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
2.3.32 cbf_find_row
2.3.44 cbf_column_name
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.32 cbf_find_row
PROTOTYPE
#include "cbf.h"
int cbf_find_row (cbf_handle handle, const char *value);
DESCRIPTION
cbf_find_row makes the first row in the current column with value value
the current row.
The comparison is case-sensitive.
If a matching row does not exist, the function returns CBF_NOTFOUND.
The current column is not affected.
ARGUMENTS
handle CBF handle.
value The value of the row to find.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.24 cbf_rewind_row
2.3.28 cbf_next_row
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
2.3.31 cbf_find_column
2.3.33 cbf_find_nextrow
2.3.46 cbf_get_value, cbf_require_value
2.3.48 cbf_get_typeofvalue
2.3.33 cbf_find_nextrow
PROTOTYPE
#include "cbf.h"
int cbf_find_nextrow (cbf_handle handle, const char *value);
DESCRIPTION
cbf_find_nextrow makes the makes the next row in the current column with
value value the current row. The search starts from the row following the
last row found with cbf_find_row or cbf_find_nextrow, or from the current
row if the current row was defined using any other function.
The comparison is case-sensitive.
If no more matching rows exist, the function returns CBF_NOTFOUND.
The current column is not affected.
ARGUMENTS
handle CBF handle.
value the value to search for.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.24 cbf_rewind_row
2.3.28 cbf_next_row
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.46 cbf_get_value, cbf_require_value
2.3.48 cbf_get_typeofvalue
----------------------------------------------------------------------
2.3.34 cbf_count_datablocks
PROTOTYPE
#include "cbf.h"
int cbf_count_datablocks (cbf_handle handle, unsigned int *datablocks);
DESCRIPTION
cbf_count_datablocks puts the number of data blocks in *datablocks .
ARGUMENTS
handle CBF handle.
datablocks Pointer to the destination data block count.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
2.3.36 cbf_count_columns
2.3.37 cbf_count_rows
2.3.38 cbf_select_datablock
----------------------------------------------------------------------
2.3.35 cbf_count_categories
PROTOTYPE
#include "cbf.h"
int cbf_count_categories (cbf_handle handle, unsigned int *categories);
DESCRIPTION
cbf_count_categories puts the number of categories in the current data
block in *categories.
ARGUMENTS
handle CBF handle.
categories Pointer to the destination category count.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.34 cbf_count_datablocks
2.3.36 cbf_count_columns
2.3.37 cbf_count_rows
2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem
----------------------------------------------------------------------
2.3.36 cbf_count_columns
PROTOTYPE
#include "cbf.h"
int cbf_count_columns (cbf_handle handle, unsigned int *columns);
DESCRIPTION
cbf_count_columns puts the number of columns in the current category in
*columns.
ARGUMENTS
handle CBF handle.
columns Pointer to the destination column count.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.34 cbf_count_datablocks
2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
2.3.37 cbf_count_rows
2.3.40 cbf_select_column
----------------------------------------------------------------------
2.3.37 cbf_count_rows
PROTOTYPE
#include "cbf.h"
int cbf_count_rows (cbf_handle handle, unsigned int *rows);
DESCRIPTION
cbf_count_rows puts the number of rows in the current category in *rows .
ARGUMENTS
handle CBF handle.
rows Pointer to the destination row count.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.34 cbf_count_datablocks
2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
2.3.36 cbf_count_columns
2.3.41 cbf_select_row
----------------------------------------------------------------------
2.3.38 cbf_select_datablock
PROTOTYPE
#include "cbf.h"
int cbf_select_datablock (cbf_handle handle, unsigned int datablock);
DESCRIPTION
cbf_select_datablock selects data block number datablock as the current
data block.
The first data block is number 0.
If the data block does not exist, the function returns CBF_NOTFOUND.
ARGUMENTS
handle CBF handle.
datablock Number of the data block to select.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.34 cbf_count_datablocks
2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem
2.3.40 cbf_select_column
2.3.41 cbf_select_row
----------------------------------------------------------------------
2.3.39 cbf_select_category
PROTOTYPE
#include "cbf.h"
int cbf_select_category (cbf_handle handle, unsigned int category);
DESCRIPTION
cbf_select_category selects category number category in the current data
block as the current category.
The first category is number 0.
The current column and row become undefined.
If the category does not exist, the function returns CBF_NOTFOUND.
ARGUMENTS
handle CBF handle.
category Number of the category to select.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.35 cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems
2.3.38 cbf_select_datablock
2.3.40 cbf_select_column
2.3.41 cbf_select_row
----------------------------------------------------------------------
2.3.40 cbf_select_column
PROTOTYPE
#include "cbf.h"
int cbf_select_column (cbf_handle handle, unsigned int column);
DESCRIPTION
cbf_select_column selects column number column in the current category as
the current column.
The first column is number 0.
The current row is not affected
If the column does not exist, the function returns CBF_NOTFOUND.
ARGUMENTS
handle CBF handle.
column Number of the column to select.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.36 cbf_count_columns
2.3.38 cbf_select_datablock
2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem
2.3.41 cbf_select_row
----------------------------------------------------------------------
2.3.41 cbf_select_row
PROTOTYPE
#include "cbf.h"
int cbf_select_row (cbf_handle handle, unsigned int row);
DESCRIPTION
cbf_select_row selects row number row in the current category as the
current row.
The first row is number 0.
The current column is not affected
If the row does not exist, the function returns CBF_NOTFOUND.
ARGUMENTS
handle CBF handle.
row Number of the row to select.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.37 cbf_count_rows
2.3.38 cbf_select_datablock
2.3.39 cbf_select_category, cbf_select_saveframe, cbf_select_blockitem
2.3.40 cbf_select_column
----------------------------------------------------------------------
2.3.42 cbf_datablock_name
PROTOTYPE
#include "cbf.h"
int cbf_datablock_name (cbf_handle handle, const char **datablockname);
DESCRIPTION
cbf_datablock_name sets *datablockname to point to the name of the current
data block.
The data block name will be valid as long as the data block exists and has
not been renamed.
The name must not be modified by the program in any way.
ARGUMENTS
handle CBF handle.
datablockname Pointer to the destination data block name pointer.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.29 cbf_find_datablock
----------------------------------------------------------------------
2.3.43 cbf_category_name
PROTOTYPE
#include "cbf.h"
int cbf_category_name (cbf_handle handle, const char **categoryname);
DESCRIPTION
cbf_category_name sets *categoryname to point to the name of the current
category of the current data block.
The category name will be valid as long as the category exists.
The name must not be modified by the program in any way.
ARGUMENTS
handle CBF handle.
categoryname Pointer to the destination category name pointer.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
----------------------------------------------------------------------
2.3.44 cbf_column_name, cbf_set_column_name
PROTOTYPE
#include "cbf.h"
int cbf_column_name (cbf_handle handle, const char **columnname);
int cbf_set_column_name (cbf_handle handle, const char *newcolumnname)
DESCRIPTION
cbf_column_name sets *columnname to point to the name of the current
column of the current category.
The column name will be valid as long as the column exists.
The name must not be modified by the program in any way.
cbf_set_column_name sets the name of the current column to newcolumnname
ARGUMENTS
handle CBF handle.
columnname Pointer to the destination column name pointer.
newcolumnname New column name pointer.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.31 cbf_find_column
----------------------------------------------------------------------
2.3.45 cbf_row_number
PROTOTYPE
#include "cbf.h"
int cbf_row_number (cbf_handle handle, unsigned int *row);
DESCRIPTION
cbf_row_number sets *row to the number of the current row of the current
category.
ARGUMENTS
handle CBF handle.
row Pointer to the destination row number.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.41 cbf_select_row
----------------------------------------------------------------------
2.3.46 cbf_get_value, cbf_require_value
PROTOTYPE
#include "cbf.h"
int cbf_get_value (cbf_handle handle, const char **value);
int cbf_require_value (cbf_handle handle, const char **value, const char
*defaultvalue );
DESCRIPTION
cbf_get_value sets *value to point to the ASCII value of the item at the
current column and row. cbf_require_value sets *value to point to the
ASCII value of the item at the current column and row, creating the data
item if necessary and initializing it to a copy of defaultvalue.
If the value is not ASCII, the function returns CBF_BINARY.
The value will be valid as long as the item exists and has not been set to
a new value.
The value must not be modified by the program in any way.
ARGUMENTS
handle CBF handle.
value Pointer to the destination value pointer.
defaultvalue Default value character string.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.50 cbf_get_integervalue, cbf_require_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims
2.3.55 cbf_get_integerarray, cbf_get_realarray
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.47 cbf_set_value
PROTOTYPE
#include "cbf.h"
int cbf_set_value (cbf_handle handle, const char *value);
DESCRIPTION
cbf_set_value sets the item at the current column and row to the ASCII
value value.
ARGUMENTS
handle CBF handle.
value ASCII value.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.51 cbf_set_integervalue
2.3.53 cbf_set_doublevalue
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.48 cbf_get_typeofvalue
PROTOTYPE
#include "cbf.h"
int cbf_get_typeofvalue (cbf_handle handle, const char **typeofvalue);
DESCRIPTION
cbf_get_value sets *typeofvalue to point an ASCII descriptor of the value
of the item at the current column and row. The strings that may be
returned are:
"null" for a null value indicated by a "." or a "?"
"bnry" for a binary value
"word" for an unquoted string
"dblq" for a double-quoted string
"sglq" for a single-quoted string
"text" for a semicolon-quoted string (multiline text field)
"prns" for a parenthesis-bracketed string (multiline text field)
"brcs" for a brace-bracketed string (multiline text field)
"bkts" for a square-bracket-bracketed string (multiline text field)
"tsqs" for a treble-single-quote quoted string (multiline text field)
"tdqs" for a treble-double-quote quoted string (multiline text field)
Not all types are valid for all type of CIF files. In partcular the types
"prns", "brcs", "bkts" were introduced with DDLm and are not valid in DDL1
or DDL2 CIFS. The types "tsqs" and "tdqs" are not formally part of the CIF
syntax. A field for which no value has been set sets *typeofvalue to NULL
rather than to the string "null".
The typeofvalue must not be modified by the program in any way.
ARGUMENTS
handle CBF handle.
typeofvalue Pointer to the destination type-of-value string pointer.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.47 cbf_set_value
2.3.49 cbf_set_typeofvalue
2.3.50 cbf_get_integervalue, cbf_require_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims
2.3.55 cbf_get_integerarray, cbf_get_realarray
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.49 cbf_set_typeofvalue
PROTOTYPE
#include "cbf.h"
int cbf_set_typeofvalue (cbf_handle handle, const char *typeofvalue);
DESCRIPTION
cbf_set_typeofvalue sets the type of the item at the current column and
row to the type specified by the ASCII character string given by
typeofvalue. The strings that may be used are:
"null" for a null value indicated by a "." or a "?"
"bnry" for a binary value
"word" for an unquoted string
"dblq" for a double-quoted string
"sglq" for a single-quoted string
"text" for a semicolon-quoted string (multiline text field)
"prns" for a parenthesis-bracketed string (multiline text field)
"brcs" for a brace-bracketed string (multiline text field)
"bkts" for a square-bracket-bracketed string (multiline text field)
"tsqs" for a treble-single-quote quoted string (multiline text field)
"tdqs" for a treble-double-quote quoted string (multiline text field)
Not all types may be used for all values. Not all types are valid for all
type of CIF files. In partcular the types "prns", "brcs", "bkts" were
introduced with DDLm and are not valid in DDL1 or DDL2 CIFS. The types
"tsqs" and "tdqs" are not formally part of the CIF syntax. No changes may
be made to the type of binary values. You may not set the type of a string
that contains a single quote followed by a blank or a tab or which
contains multiple lines to "sglq". You may not set the type of a string
that contains a double quote followed by a blank or a tab or which
contains multiple lines to "dblq".
ARGUMENTS
handle CBF handle.
typeofvalue ASCII string for desired type of value.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.51 cbf_set_integervalue
2.3.53 cbf_set_doublevalue
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.50 cbf_get_integervalue, cbf_require_integervalue
PROTOTYPE
#include "cbf.h"
int cbf_get_integervalue (cbf_handle handle, int *number);
int cbf_require_integervalue (cbf_handle handle, int *number, int
defaultvalue);
DESCRIPTION
cbf_get_integervalue sets *number to the value of the ASCII item at the
current column and row interpreted as a decimal integer.
cbf_require_integervalue sets *number to the value of the ASCII item at
the current column and row interpreted as a decimal integer, setting it to
defaultvalue if necessary.
If the value is not ASCII, the function returns CBF_BINARY.
ARGUMENTS
handle CBF handle.
number pointer to the number.
defaultvalue default number value.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.48 cbf_get_typeofvalue
2.3.51 cbf_set_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims
2.3.55 cbf_get_integerarray, cbf_get_realarray
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.51 cbf_set_integervalue
PROTOTYPE
#include "cbf.h"
int cbf_set_integervalue (cbf_handle handle, int number);
DESCRIPTION
cbf_set_integervalue sets the item at the current column and row to the
integer value number written as a decimal ASCII string.
ARGUMENTS
handle CBF handle.
number Integer value.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.50 cbf_get_integervalue, cbf_require_integervalue
2.3.51 cbf_set_integervalue
2.3.53 cbf_set_doublevalue
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
PROTOTYPE
#include "cbf.h"
int cbf_get_doublevalue (cbf_handle handle, double *number);
int cbf_require_doublevalue (cbf_handle handle, double *number, double
defaultvalue);
DESCRIPTION
cbf_get_doublevalue sets *number to the value of the ASCII item at the
current column and row interpreted as a decimal floating-point number.
cbf_require_doublevalue sets *number to the value of the ASCII item at the
current column and row interpreted as a decimal floating-point number,
setting it to defaultvalue if necessary.
If the value is not ASCII, the function returns CBF_BINARY.
ARGUMENTS
handle CBF handle.
number Pointer to the destination number.
defaultvalue default number value.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.50 cbf_get_integervalue, cbf_require_integervalue
2.3.53 cbf_set_doublevalue
2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims
2.3.55 cbf_get_integerarray, cbf_get_realarray
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.53 cbf_set_doublevalue
PROTOTYPE
#include "cbf.h"
int cbf_set_doublevalue (cbf_handle handle, const char *format, double
number);
DESCRIPTION
cbf_set_doublevalue sets the item at the current column and row to the
floating-point value number written as an ASCII string with the format
specified by format as appropriate for the printf function.
ARGUMENTS
handle CBF handle.
format Format for the number.
number Floating-point value.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.51 cbf_set_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims,
cbf_get_integerarrayparameters_wdims_fs,
cbf_get_integerarrayparameters_wdims_sf, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims,
cbf_get_realarrayparameters_wdims_fs, cbf_get_realarrayparameters_wdims_sf
PROTOTYPE
#include "cbf.h"
int cbf_get_integerarrayparameters (cbf_handle handle, unsigned int
*compression, int *binary_id, size_t *elsize, int *elsigned, int
*elunsigned, size_t *elements, int *minelement, int *maxelement);
int cbf_get_integerarrayparameters_wdims (cbf_handle handle, unsigned int
*compression, int *binary_id, size_t *elsize, int *elsigned, int
*elunsigned, size_t *elements, int *minelement, int *maxelement, const
char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
*padding);
int cbf_get_integerarrayparameters_wdims_fs (cbf_handle handle, unsigned
int *compression, int *binary_id, size_t *elsize, int *elsigned, int
*elunsigned, size_t *elements, int *minelement, int *maxelement, const
char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
*padding);
int cbf_get_integerarrayparameters_wdims_sf (cbf_handle handle, unsigned
int *compression, int *binary_id, size_t *elsize, int *elsigned, int
*elunsigned, size_t *elements, int *minelement, int *maxelement, const
char **byteorder, size_t *dimslow, size_t *dimmid, size_t *dimfast, size_t
*padding);
int cbf_get_realarrayparameters (cbf_handle handle, unsigned int
*compression, int *binary_id, size_t *elsize, size_t *elements);
int cbf_get_realarrayparameters_wdims (cbf_handle handle, unsigned int
*compression, int *binary_id, size_t *elsize, size_t *elements, const char
**byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
*padding);
int cbf_get_realarrayparameters_wdims_fs (cbf_handle handle, unsigned int
*compression, int *binary_id, size_t *elsize, size_t *elements, const char
**byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t
*padding);
int cbf_get_realarrayparameters_wdims_sf (cbf_handle handle, unsigned int
*compression, int *binary_id, size_t *elsize, size_t *elements, const char
**byteorder, size_t *dimslow, size_t *dimmid, size_t *dimfast, size_t
*padding);
DESCRIPTION
cbf_get_integerarrayparameters sets *compression, *binary_id, *elsize,
*elsigned, *elunsigned, *elements, *minelement and *maxelement to values
read from the binary value of the item at the current column and row. This
provides all the arguments needed for a subsequent call to
cbf_set_integerarray, if a copy of the array is to be made into another
CIF or CBF. cbf_get_realarrayparameters sets *compression, *binary_id,
*elsize, *elements to values read from the binary value of the item at the
current column and row. This provides all the arguments needed for a
subsequent call to cbf_set_realarray, if a copy of the arry is to be made
into another CIF or CBF.
The variants cbf_get_integerarrayparameters_wdims,
cbf_get_integerarrayparameters_wdims_fs,
cbf_get_integerarrayparameters_wdims_sf,
cbf_get_realarrayparameters_wdims, cbf_get_realarrayparameters_wdims_fs,
cbf_get_realarrayparameters_wdims_sf set **byteorder, *dimfast, *dimmid,
*dimslow, and *padding as well, providing the additional parameters needed
for a subsequent call to cbf_set_integerarray_wdims or
cbf_set_realarray_wdims.
The value returned in *byteorder is a pointer either to the string
"little_endian" or to the string "big_endian". This should be the byte
order of the data, not necessarily of the host machine. No attempt should
be made to modify this string. At this time only "little_endian" will be
returned.
The values returned in *dimfast, *dimmid and *dimslow are the sizes of the
fastest changing, second fastest changing and third fastest changing
dimensions of the array, if specified, or zero, if not specified.
The value returned in *padding is the size of the post-data padding, if
any and if specified in the data header. The value is given as a count of
octets.
If the value is not binary, the function returns CBF_ASCII.
ARGUMENTS
handle CBF handle.
compression Compression method used.
elsize Size in bytes of each array element.
binary_id Pointer to the destination integer binary identifier.
elsigned Pointer to an integer. Set to 1 if the elements can be
read as signed integers.
elunsigned Pointer to an integer. Set to 1 if the elements can be
read as unsigned integers.
elements Pointer to the destination number of elements.
minelement Pointer to the destination smallest element.
maxelement Pointer to the destination largest element.
byteorder Pointer to the destination byte order.
dimfast Pointer to the destination fastest dimension.
dimmid Pointer to the destination second fastest dimension.
dimslow Pointer to the destination third fastest dimension.
padding Pointer to the destination padding size.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.50 cbf_get_integervalue, cbf_require_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.55 cbf_get_integerarray, cbf_get_realarray
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.55 cbf_get_integerarray, cbf_get_realarray
PROTOTYPE
#include "cbf.h"
int cbf_get_integerarray (cbf_handle handle, int *binary_id, void *array,
size_t elsize, int elsigned, size_t elements, size_t *elements_read);
int cbf_get_realarray (cbf_handle handle, int *binary_id, void *array,
size_t elsize, size_t elements, size_t *elements_read);
DESCRIPTION
cbf_get_integerarray reads the binary value of the item at the current
column and row into an integer array. The array consists of elements
elements of elsize bytes each, starting at array. The elements are signed
if elsigned is non-0 and unsigned otherwise. *binary_id is set to the
binary section identifier and *elements_read to the number of elements
actually read. cbf_get_realarray reads the binary value of the item at the
current column and row into a real array. The array consists of elements
elements of elsize bytes each, starting at array. *binary_id is set to the
binary section identifier and *elements_read to the number of elements
actually read.
If any element in the integer binary data cant fit into the destination
element, the destination is set the nearest possible value.
If the value is not binary, the function returns CBF_ASCII.
If the requested number of elements cant be read, the function will read
as many as it can and then return CBF_ENDOFDATA.
Currently, the destination array must consist of chars, shorts or ints
(signed or unsigned). If elsize is not equal to sizeof (char), sizeof
(short) or sizeof (int), for cbf_get_integerarray, or sizeof(double) or
sizeof(float), for cbf_get_realarray the function returns CBF_ARGUMENT.
An additional restriction in the current version of CBFlib is that values
too large to fit in an int are not correctly decompressed. As an example,
if the machine with 32-bit ints is reading an array containing a value
outside the range 0 .. 2^32-1 (unsigned) or -2^31 .. 2^31-1 (signed), the
array will not be correctly decompressed. This restriction will be removed
in a future release. For cbf_get_realarray, only IEEE format is supported.
No conversion to other floating point formats is done at this time.
ARGUMENTS
handle CBF handle.
binary_id Pointer to the destination integer binary identifier.
array Pointer to the destination array.
elsize Size in bytes of each destination array element.
elsigned Set to non-0 if the destination array elements are
signed.
elements The number of elements to read.
elements_read Pointer to the destination number of elements actually
read.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.50 cbf_get_integervalue, cbf_require_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.56 cbf_set_integerarray,
cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs,
cbf_set_integerarray_wdims_sf,
cbf_set_realarray,
cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs,
cbf_set_realarray_wdims_sf
PROTOTYPE
#include "cbf.h"
int cbf_set_integerarray (cbf_handle handle, unsigned int compression, int
binary_id, void *array, size_t elsize, int elsigned, size_t elements);
int cbf_set_integerarray_wdims (cbf_handle handle, unsigned int
compression, int binary_id, void *array, size_t elsize, int elsigned,
size_t elements, const char *byteorder, size_t dimfast, size_t dimmid,
size_t dimslow, size_t padding);
int cbf_set_integerarray_wdims_fs (cbf_handle handle, unsigned int
compression, int binary_id, void *array, size_t elsize, int elsigned,
size_t elements, const char *byteorder, size_t dimfast, size_t dimmid,
size_t dimslow, size_t padding);
int cbf_set_integerarray_wdims_sf (cbf_handle handle, unsigned int
compression, int binary_id, void *array, size_t elsize, int elsigned,
size_t elements, const char *byteorder, size_t dimslow, size_t dimmid,
size_t dimfast, size_t padding);
int cbf_set_realarray (cbf_handle handle, unsigned int compression, int
binary_id, void *array, size_t elsize, size_t elements);
int cbf_set_realarray_wdims (cbf_handle handle, unsigned int compression,
int binary_id, void *array, size_t elsize, size_t elements, const char
*byteorder, size_t dimfast, size_t dimmid, size_t dimslow, size_t
padding);
int cbf_set_realarray_wdims_fs (cbf_handle handle, unsigned int
compression, int binary_id, void *array, size_t elsize, size_t elements,
const char *byteorder, size_t dimfast, size_t dimmid, size_t dimslow,
size_t padding);
int cbf_set_realarray_wdims_sf (cbf_handle handle, unsigned int
compression, int binary_id, void *array, size_t elsize, size_t elements,
const char *byteorder, size_t dimslow, size_t dimmid, size_t dimfast,
size_t padding);
DESCRIPTION
cbf_set_integerarray sets the binary value of the item at the current
column and row to an integer array. The array consists of elements
elements of elsize bytes each, starting at array. The elements are signed
if elsigned is non-0 and unsigned otherwise. binary_id is the binary
section identifier. cbf_set_realarray sets the binary value of the item at
the current column and row to an integer array. The array consists of
elements elements of elsize bytes each, starting at array. binary_id is
the binary section identifier.
The cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs,
cbf_set_integerarray_wdims_sf, cbf_set_realarray_wdims,
cbf_set_realarray_wdims_fs and cbf_set_realarray_wdims_sf variants allow
the data header values of byteorder, dimfast, dimmid, dimslow and padding
to be set to the data byte order, the fastest, second fastest and third
fastest array dimensions and the size in byte of the post data padding to
be used.
The array will be compressed using the compression scheme specifed by
compression. Currently, the available schemes are:
CBF_CANONICAL Canonical-code compression (section 3.3.1)
CBF_PACKED CCP4-style packing (section 3.3.2)
CBF_PACKED_V2 CCP4-style packing, version 2 (section 3.3.2)
CBF_BYTE_OFFSET Simple "byte_offset" compression.
CBF_NIBBLE_OFFSET Simple "nibble_offset" compression.
CBF_NONE No compression. NOTE: This scheme is by far the
slowest of the four and uses much more disk space. It
is intended for routine use with small arrays only.
With large arrays (like images) it should be used only
for debugging.
The values compressed are limited to 64 bits. If any element in the array
is larger than 64 bits, the value compressed is the nearest 64-bit value.
Currently, the source array must consist of chars, shorts or ints (signed
or unsigned), for cbf_set_integerarray, or IEEE doubles or floats for
cbf_set_realarray. If elsize is not equal to sizeof (char), sizeof (short)
or sizeof (int), the function returns CBF_ARGUMENT.
ARGUMENTS
handle CBF handle.
compression Compression method to use.
binary_id Integer binary identifier.
array Pointer to the source array.
elsize Size in bytes of each source array element.
elsigned Set to non-0 if the source array elements are signed.
elements: The number of elements in the array.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.51 cbf_set_integervalue
2.3.53 cbf_set_doublevalue
2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims
2.3.55 cbf_get_integerarray, cbf_get_realarray
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.57 cbf_failnez
DEFINITION
#include "cbf.h"
#define cbf_failnez(f) {int err; err = (f); if (err) return err; }
DESCRIPTION
cbf_failnez is a macro used for error propagation throughout CBFlib.
cbf_failnez executes the function f and saves the returned error value. If
the error value is non-0, cbf_failnez executes a return with the error
value as argument. If CBFDEBUG is defined, then a report of the error is
also printed to the standard error stream, stderr, in the form
CBFlib error f in "symbol"
where f is the decimal value of the error and symbol is the symbolic form.
ARGUMENTS
f Integer error value.
SEE ALSO
2.3.58 cbf_onfailnez
----------------------------------------------------------------------
2.3.58 cbf_onfailnez
DEFINITION
#include "cbf.h"
#define cbf_onfailnez(f,c) {int err; err = (f); if (err) {{c; }return err;
}}
DESCRIPTION
cbf_onfailnez is a macro used for error propagation throughout CBFlib.
cbf_onfailnez executes the function f and saves the returned error value.
If the error value is non-0, cbf_failnez executes first the statement c
and then a return with the error value as argument. If CBFDEBUG is
defined, then a report of the error is also printed to the standard error
stream, stderr, in the form
CBFlib error f in "symbol"
where f is the decimal value of the error and symbol is the symbolic form.
ARGUMENTS
f integer function to execute.
c statement to execute on failure.
SEE ALSO
* 2.3.57 cbf_failnez
----------------------------------------------------------------------
2.3.59 cbf_require_datablock
PROTOTYPE
#include "cbf.h"
int cbf_require_datablock (cbf_handle handle, const char
*datablockname);
DESCRIPTION
cbf_require_datablock makes the data block with name datablockname the
current data block, if it exists, or creates it if it does not.
The comparison is case-insensitive.
The current category becomes undefined.
ARGUMENTS
handle CBF handle.
datablockname The name of the data block to find or create.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.21 cbf_rewind_datablock
2.3.25 cbf_next_datablock
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.42 cbf_datablock_name
2.3.60 cbf_require_category
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.60 cbf_require_category
PROTOTYPE
#include "cbf.h"
int cbf_require_category (cbf_handle handle, const char *categoryname);
DESCRIPTION
cbf_rewuire_category makes the category in the current data block with
name categoryname the current category, if it exists, or creates the
catagory if it does not exist.
The comparison is case-insensitive.
The current column and row become undefined.
ARGUMENTS
handle CBF handle.
categoryname The name of the category to find.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.22 cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem
2.3.26 cbf_next_category, cbf_next_saveframe, cbf_next_blockitem
2.3.29 cbf_find_datablock
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.43 cbf_category_name
2.3.59 cbf_require_datablock
2.3.61 cbf_require_column
----------------------------------------------------------------------
2.3.61 cbf_require_column
PROTOTYPE
#include "cbf.h"
int cbf_require_column (cbf_handle handle, const char *columnname);
DESCRIPTION
cbf_require_column makes the columns in the current category with name
columnname the current column, if it exists, or creates it if it does
not.
The comparison is case-insensitive.
The current row is not affected.
ARGUMENTS
handle CBF handle.
columnname The name of column to find.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.19 cbf_rewind_column
2.3.27 cbf_next_column
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category, cbf_find_saveframe, cbf_find_blockitem
2.3.32 cbf_find_row
2.3.44 cbf_column_name, cbf_set_column_name
2.3.59 cbf_require_datablock
2.3.60 cbf_require_category
----------------------------------------------------------------------
2.3.62 cbf_require_column_value
PROTOTYPE
#include "cbf.h"
int cbf_require_column_value (cbf_handle handle, const char *columnname,
const char **value, const char *defaultvalue);
DESCRIPTION
cbf_require_column_doublevalue sets *value to the ASCII item at the
current row for the column given with the name given by *columnname, or
to the string given by defaultvalue if the item cannot be found.
ARGUMENTS
handle CBF handle.
columnname Name of the column containing the number.
value pointer to the location to receive the value.
defaultvalue Value to use if the requested column and value cannot
be found.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.51 cbf_set_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.63 cbf_require_column_integervalue
PROTOTYPE
#include "cbf.h"
int cbf_require_column_integervalue (cbf_handle handle, const char
*columnname, int *number, const int defaultvalue);
DESCRIPTION
cbf_require_column_doublevalue sets *number to the value of the ASCII
item at the current row for the column given with the name given by
*columnname, with the value interpreted as an integer number, or to the
number given by defaultvalue if the item cannot be found.
ARGUMENTS
handle CBF handle.
columnname Name of the column containing the number.
number pointer to the location to receive the integer value.
defaultvalue Value to use if the requested column and value cannot
be found.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.51 cbf_set_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.64 cbf_require_column_doublevalue
----------------------------------------------------------------------
2.3.64 cbf_require_column_doublevalue
PROTOTYPE
#include "cbf.h"
int cbf_require_column_doublevalue (cbf_handle handle, const char
*columnname, double *number, const double defaultvalue);
DESCRIPTION
cbf_require_column_doublevalue sets *number to the value of the ASCII
item at the current row for the column given with the name given by
*columnname, with the value interpreted as a decimal floating-point
number, or to the number given by defaultvalue if the item cannot be
found.
ARGUMENTS
handle CBF handle.
columnname Name of the column containing the number.
number pointer to the location to receive the floating-point
value.
defaultvalue Value to use if the requested column and value cannot
be found.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.46 cbf_get_value, cbf_require_value
2.3.47 cbf_set_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.51 cbf_set_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims,
cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
----------------------------------------------------------------------
2.3.65 cbf_get_local_integer_byte_order, cbf_get_local_real_byte_order,
cbf_get_local_real_format
PROTOTYPE
#include "cbf.h"
int cbf_get_local_integer_byte_order (char ** byte_order);
int cbf_get_local_real_byte_order (char ** byte_order);
int cbf_get_local_real_format (char ** real_format );
DESCRIPTION
cbf_get_local_integer_byte_order returns the byte order of integers on
the machine on which the API is being run in the form of a character
string returned as the value pointed to by byte_order.
cbf_get_local_real_byte_order returns the byte order of reals on the
machine on which the API is being run in the form of a character string
returned as the value pointed to by byte_order.
cbf_get_local_real_format returns the format of floats on the machine on
which the API is being run in the form of a character string returned as
the value pointed to by real_format. The strings returned must not be
modified in any way.
The values returned in byte_order may be the strings "little_endian" or
"big-endian". The values returned in real_format may be the strings
"ieee 754-1985" or "other". Additional values may be returned by future
versions of the API.
ARGUMENTS
byte_order pointer to the returned string
real_format pointer to the returned string
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.3.66 cbf_get_dictionary, cbf_set_dictionary, cbf_require_dictionary
PROTOTYPE
#include "cbf.h"
int cbf_get_dictionary (cbf_handle handle, cbf_handle * dictionary);
int cbf_set_dictionary (cbf_handle handle, cbf_handle dictionary_in);
int cbf_require_dictionary (cbf_handle handle, cbf_handle * dictionary)
DESCRIPTION
cbf_get_dictionary sets *dictionary to the handle of a CBF which has
been associated with the CBF handle by cbf_set_dictionary.
cbf_set_dictionary associates the CBF handle dictionary_in with handle
as its dictionary. cbf_require_dictionary sets *dictionary to the handle
of a CBF which has been associated with the CBF handle by
cbf_set_dictionary or creates a new empty CBF and associates it with
handle, returning the new handle in *dictionary.
ARGUMENTS
handle CBF handle.
dictionary Pointer to CBF handle of dictionary.
dictionary_in CBF handle of dcitionary.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.3.67 cbf_convert_dictionary
PROTOTYPE
#include "cbf.h"
int cbf_convert_dictionary (cbf_handle handle, cbf_handle dictionary )
DESCRIPTION
cbf_convert_dictionary converts dictionary as a DDL1 or DDL2 dictionary
to a CBF dictionary of category and item properties for handle, creating
a new dictionary if none exists or layering the definitions in
dictionary onto the existing dictionary of handle if one exists.
If a CBF is read into handle after calling cbf_convert_dictionary, then
the dictionary will be used for validation of the CBF as it is read.
ARGUMENTS
handle CBF handle.
dictionary CBF handle of dictionary.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.3.68 cbf_find_tag, cbf_find_local_tag
PROTOTYPE
#include "cbf.h"
int cbf_find_tag (cbf_handle handle, const char *tag)
int cbf_find_local_tag (cbf_handle handle, const char *tag)
DESCRIPTION
cbf_find_tag searches all of the CBF handle for the CIF tag given by the
string tag and makes it the current tag. The search does not include the
dictionary, but does include save frames as well as categories.
The string tag is the complete tag in either DDL1 or DDL2 format,
starting with the leading underscore, not just a category or column.
ARGUMENTS
handle CBF handle.
tag CIF tag.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.3.69 cbf_find_category_root, cbf_set_category_root,
cbf_require_category_root
PROTOTYPE
#include "cbf.h"
int cbf_find_category_root (cbf_handle handle, const char* categoryname,
const char** categoryroot);
int cbf_set_category_root (cbf_handle handle, const char*
categoryname_in, const char*categoryroot);
int cbf_require_category_root (cbf_handle handle, const char*
categoryname, const char** categoryroot);
DESCRIPTION
cbf_find_category_root sets *categoryroot to the root category of which
categoryname is an alias. cbf_set_category_root sets categoryname_in as
an alias of categoryroot in the dictionary associated with handle,
creating the dictionary if necessary. cbf_require_category_root sets
*categoryroot to the root category of which categoryname is an alias, if
there is one, or to the value of categoryname, if categoryname is not an
alias.
A returned categoryroot string must not be modified in any way.
ARGUMENTS
handle CBF handle.
categoryname category name which may be an alias.
categoryroot pointer to a returned category root name.
categoryroot_in input category root name.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.3.70 cbf_find_tag_root, cbf_set_tag_root, cbf_require_tag_root
PROTOTYPE
#include "cbf.h"
int cbf_find_tag_root (cbf_handle handle, const char* tagname, const
char** tagroot);
int cbf_set_tag_root (cbf_handle handle, const char* tagname, const
char*tagroot_in);
int cbf_require_tag_root (cbf_handle handle, const char* tagname, const
char** tagroot);
DESCRIPTION
cbf_find_tag_root sets *tagroot to the root tag of which tagname is an
alias. cbf_set_tag_root sets tagname as an alias of tagroot_in in the
dictionary associated with handle, creating the dictionary if necessary.
cbf_require_tag_root sets *tagroot to the root tag of which tagname is
an alias, if there is one, or to the value of tagname, if tagname is not
an alias.
A returned tagroot string must not be modified in any way.
ARGUMENTS
handle CBF handle.
tagname tag name which may be an alias.
tagroot pointer to a returned tag root name.
tagroot_in input tag root name.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.3.71 cbf_find_tag_category, cbf_set_tag_category
PROTOTYPE
#include "cbf.h"
int cbf_find_tag_category (cbf_handle handle, const char* tagname, const
char** categoryname);
int cbf_set_tag_category (cbf_handle handle, const char* tagname, const
char* categoryname_in);
DESCRIPTION
cbf_find_tag_category sets categoryname to the category associated with
tagname in the dictionary associated with handle. cbf_set_tag_category
upddates the dictionary associated with handle to indicated that tagname
is in category categoryname_in.
ARGUMENTS
handle CBF handle.
tagname tag name.
categoryname pointer to a returned category name.
categoryname_in input category name.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
----------------------------------------------------------------------
2.4 High-level function prototypes
2.4.1 cbf_read_template
PROTOTYPE
#include "cbf_simple.h"
int cbf_read_template (cbf_handle handle, FILE *file);
DESCRIPTION
cbf_read_template reads the CBF or CIF file file into the CBF object
specified by handle and selects the first datablock as the current
datablock.
ARGUMENTS
handle Pointer to a CBF handle.
file Pointer to a file descriptor.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.2 cbf_get_diffrn_id, cbf_require_diffrn_id
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_diffrn_id (cbf_handle handle, const char **diffrn_id);
int cbf_require_diffrn_id (cbf_handle handle, const char **diffrn_id,
const char *default_id)
DESCRIPTION
cbf_get_diffrn_id sets *diffrn_id to point to the ASCII value of the
"diffrn.id" entry. cbf_require_diffrn_id also sets *diffrn_id to point
to the ASCII value of the "diffrn.id" entry, but, if the "diffrn.id"
entry does not exist, it sets the value in the CBF and in*diffrn_id to
the character string given by default_id, creating the category and
column is necessary.
The diffrn_id will be valid as long as the item exists and has not been
set to a new value.
The diffrn_id must not be modified by the program in any way.
ARGUMENTS
handle CBF handle.
diffrn_id Pointer to the destination value pointer.
default_id Character string default value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.3 cbf_set_diffrn_id
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_diffrn_id (cbf_handle handle, const char *diffrn_id);
DESCRIPTION
cbf_set_diffrn_id sets the "diffrn.id" entry of the current datablock to
the ASCII value diffrn_id.
This function also changes corresponding "diffrn_id" entries in the
"diffrn_source", "diffrn_radiation", "diffrn_detector" and
"diffrn_measurement" categories.
ARGUMENTS
handle CBF handle.
diffrn_id ASCII value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.4 cbf_get_crystal_id
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_crystal_id (cbf_handle handle, const char **crystal_id);
DESCRIPTION
cbf_get_crystal_id sets *crystal_id to point to the ASCII value of the
"diffrn.crystal_id" entry.
If the value is not ASCII, the function returns CBF_BINARY.
The value will be valid as long as the item exists and has not been set
to a new value.
The value must not be modified by the program in any way.
ARGUMENTS
handle CBF handle.
crystal_id Pointer to the destination value pointer.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.5 cbf_set_crystal_id
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_crystal_id (cbf_handle handle, const char *crystal_id);
DESCRIPTION
cbf_set_crystal_id sets the "diffrn.crystal_id" entry to the ASCII value
crystal_id.
ARGUMENTS
handle CBF handle.
crystal_id ASCII value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.6 cbf_get_wavelength
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_wavelength (cbf_handle handle, double *wavelength);
DESCRIPTION
cbf_get_wavelength sets *wavelength to the current wavelength in AA.
ARGUMENTS
handle CBF handle.
wavelength Pointer to the destination.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.7 cbf_set_wavelength
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_wavelength (cbf_handle handle, double wavelength);
DESCRIPTION
cbf_set_wavelength sets the current wavelength in AA to wavelength.
ARGUMENTS
handle CBF handle.
wavelength Wavelength in AA.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.8 cbf_get_polarization
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_polarization (cbf_handle handle, double
*polarizn_source_ratio, double *polarizn_source_norm);
DESCRIPTION
cbf_get_polarization sets *polarizn_source_ratio and
*polarizn_source_norm to the corresponding source polarization
parameters.
Either destination pointer may be NULL.
ARGUMENTS
handle CBF handle.
polarizn_source_ratio Pointer to the destination
polarizn_source_ratio.
polarizn_source_norm Pointer to the destination
polarizn_source_norm.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.9 cbf_set_polarization
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_polarization (cbf_handle handle, double
polarizn_source_ratio, double polarizn_source_norm);
DESCRIPTION
cbf_set_polarization sets the source polarization to the values
specified by polarizn_source_ratio and polarizn_source_norm.
ARGUMENTS
handle CBF handle.
polarizn_source_ratio New value of polarizn_source_ratio.
polarizn_source_norm New value of polarizn_source_norm.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.10 cbf_get_divergence
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_divergence (cbf_handle handle, double *div_x_source, double
*div_y_source, double *div_x_y_source);
DESCRIPTION
cbf_get_divergence sets *div_x_source, *div_y_source and *div_x_y_source
to the corresponding source divergence parameters.
Any of the destination pointers may be NULL.
ARGUMENTS
handle CBF handle.
div_x_source Pointer to the destination div_x_source.
div_y_source Pointer to the destination div_y_source.
div_x_y_source Pointer to the destination div_x_y_source.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.11 cbf_ set_divergence
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_divergence (cbf_handle handle, double div_x_source, double
div_y_source, double div_x_y_source);
DESCRIPTION
cbf_set_divergence sets the source divergence parameters to the values
specified by div_x_source, div_y_source and div_x_y_source.
ARGUMENTS
handle CBF handle.
div_x_source New value of div_x_source.
div_y_source New value of div_y_source.
div_x_y_source New value of div_x_y_source.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.12 cbf_count_elements
PROTOTYPE
#include "cbf_simple.h"
int cbf_count_elements (cbf_handle handle, unsigned int *elements);
DESCRIPTION
cbf_count_elements sets *elements to the number of detector elements.
ARGUMENTS
handle CBF handle.
elements Pointer to the destination count.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.13 cbf_get_element_number, cbf_get_element_id
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_element_number(cbf_handle handle, const char *element_id,
const char *array_id, const char *array_section_id, unsigned int
*element_number);
int cbf_get_element_id (cbf_handle handle, unsigned int element_number,
const char **element_id);
DESCRIPTION
cbf_get_element_number sets element_number to a number that can be used
in other cbf_simple calls to identify the detector element element_id
and optionally the specific array_id> and array_section_id.
cbf_get_element_id sets *element_id to point to the ASCII value of the
element_number'th "diffrn_data_frame.detector_element_id" entry,
counting from 0. The element_number is the ordinal of the detector
element in the DIFFRN_DETECTOR_ELEMENT category. If an array_section_id
is specified (i.e. is not NULL), the element_number is the sum of the
ordinal of the detector element plus the number of detector elements
multiplied by the ordinal of array_section_id for the specified
array_id> in the ARRAY_STRUCTURE_LIST_SECTION category.
If the detector element does not exist, the function returns
CBF_NOTFOUND.
The element_id will be valid as long as the item exists and has not been
set to a new value.
The element_id must not be modified by the program in any way.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0
by order of appearance in the "diffrn_data_frame"
category.
element_id Pointer to the destination string for
cbf_get_element_id, but the string itself for
cbf_get_element_number.
array_id The optional array id or NULL.
array_section_id The optional array_section_id or NULL.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.14 cbf_get_gain
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_gain (cbf_handle handle, unsigned int element_number, double
*gain, double *gain_esd);
DESCRIPTION
cbf_get_gain sets *gain and *gain_esd to the corresponding gain
parameters for element number element_number.
Either of the destination pointers may be NULL.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
gain Pointer to the destination gain.
gain_esd Pointer to the destination gain_esd.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.15 cbf_ set_gain
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_gain (cbf_handle handle, unsigned int element_number, double
gain, double gain_esd);
DESCRIPTION
cbf_set_gain sets the gain of element number element_number to the
values specified by gain and gain_esd.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
gain New gain value.
gain_esd New gain_esd value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.16 cbf_get_overload
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_overload (cbf_handle handle, unsigned int element_number,
double *overload);
DESCRIPTION
cbf_get_overload sets *overload to the overload value for element number
element_number.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
overload Pointer to the destination overload.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.17 cbf_ set_overload
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_overload (cbf_handle handle, unsigned int element_number,
double overload);
DESCRIPTION
cbf_set_overload sets the overload value of element number
element_number to overload.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
overload New overload value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.18 cbf_get_integration_time
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_integration_time (cbf_handle handle, unsigned int reserved,
double *time);
DESCRIPTION
cbf_get_integration_time sets *time to the integration time in seconds.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
time Pointer to the destination time.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.19 cbf_set_integration_time
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_integration_time (cbf_handle handle, unsigned int reserved,
double time);
DESCRIPTION
cbf_set_integration_time sets the integration time in seconds to the
value specified by time. The parameter reserved is presently unused and
should be set to 0.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
time Integration time in seconds.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.20 cbf_get_timestamp
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_timestamp (cbf_handle handle, unsigned int reserved, double
*time, int *timezone);
DESCRIPTION
cbf_get_timestamp sets *time to the collection timestamp in seconds
since January 1 1970. *timezone is set to timezone difference from UTC
in minutes. The parameter reserved is presently unused and should be set
to 0.
Either of the destination pointers may be NULL.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
time Pointer to the destination collection timestamp.
timezone Pointer to the destination timezone difference.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.21 cbf_set_timestamp
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_timestamp (cbf_handle handle, unsigned int reserved, double
time, int timezone, double precision);
DESCRIPTION
cbf_set_timestamp sets the collection timestamp in seconds since January
1 1970 to the value specified by time. The timezone difference from UTC
in minutes is set to timezone. If no timezone is desired, timezone
should be CBF_NOTIM EZONE. The parameter reserved is presently unused
and should be set to 0.
The precision of the new timestamp is specified by the value precision
in seconds. If precision is 0, the saved timestamp is assumed accurate
to 1 second.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
time Timestamp in seconds since January 1 1970.
timezone Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
precision Timestamp precision in seconds.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.22 cbf_get_datestamp
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_datestamp (cbf_handle handle, unsigned int reserved, int
*year, int *month, int *day, int *hour, int *minute, double *second, int
*timezone);
DESCRIPTION
cbf_get_datestamp sets *year, *month, *day, *hour, *minute and *second
to the corresponding values of the collection timestamp. *timezone is
set to timezone difference from UTC in minutes. The parameter <
i>reserved is presently unused and should be set to 0.
Any of the destination pointers may be NULL.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
year Pointer to the destination timestamp year.
month Pointer to the destination timestamp month (1-12).
day Pointer to the destination timestamp day (1-31).
hour Pointer to the destination timestamp hour (0-23).
minute Pointer to the destination timestamp minute (0-59).
second Pointer to the destination timestamp second (0-60.0).
timezone Pointer to the destination timezone difference from UTC in
minutes.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.23 cbf_set_datestamp
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_datestamp (cbf_handle handle, unsigned int reserved, int
year, int month, int day, int hour, int minute, double second, int
timezone, double precision);
DESCRIPTION
cbf_set_datestamp sets the collection timestamp in seconds since January
1 1970 to the value specified by time. The timezone difference from UTC
in minutes is set to timezone. If no timezone is desired, timezone
should be CBF_NOTIM EZONE. The parameter reserved is presently unused
and should be set to 0.
The precision of the new timestamp is specified by the value precision
in seconds. If precision is 0, the saved timestamp is assumed accurate
to 1 second.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
time Timestamp in seconds since January 1 1970.
timezone Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
precision Timestamp precision in seconds.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.24 cbf_set_current_timestamp
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_current_timestamp (cbf_handle handle, unsigned int reserved,
int timezone);
DESCRIPTION
cbf_set_current_timestamp sets the collection timestamp to the current
time. The timezone difference from UTC in minutes is set to timezone. If
no timezone is desired, timezone should be CBF_NOTIMEZONE. If no
timezone is used, the timest amp will be UTC. The parameter reserved is
presently unused and should be set to 0.
The new timestamp will have a precision of 1 second.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
timezone Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.25 cbf_get_image_size, cbf_get_image_size_fs, cbf_get_image_size_sf,
cbf_get_3d_image_size, cbf_get_3d_image_size_fs,
cbf_get_3d_image_size_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_image_size (cbf_handle handle, unsigned int reserved,
unsigned int element_number, size_t *ndimslow, size_t *ndimfast);
int cbf_get_image_size_fs (cbf_handle handle, unsigned int reserved,
unsigned int element_number, size_t *ndimfast, size_t *ndimslow);
int cbf_get_image_size_sf (cbf_handle handle, unsigned int reserved,
unsigned int element_number, size_t *ndimslow, size_t *ndimfast);
int cbf_get_3d_image_size (cbf_handle handle, unsigned int reserved,
unsigned int element_number, size_t *ndimslow, size_t *ndimmid, size_t
*ndimfast);
int cbf_get_3d_image_size_fs (cbf_handle handle, unsigned int reserved,
unsigned int element_number, size_t *ndimfast, size_t *ndimmid, size_t
*ndimslow);
int cbf_get_3d_image_size_sf (cbf_handle handle, unsigned int reserved,
unsigned int element_number, size_t *ndimslow, size_t *ndimmid, size_t
*ndimfast);
DESCRIPTION
cbf_get_image_size, cbf_get_image_size_fs and cbf_get_image_size_sf set
*ndimslow and *ndimfast to the slow and fast dimensions of the image
array for element number element_number. If the array is 1-dimensional,
*ndimslow will be set to the array size and *ndimfast will be set to 1.
If the array is 3-dimensional an error code will be returned.
cbf_get_3d_image_size, cbf_get_3d_image_size_fs and
cbf_get_3d_image_size_sf set *ndimslow, *ndimmid and *ndimfast to the
slowest, next fastest and fastest dimensions, respectively, of the 3D
image array for element number element_number. If the array is
1-dimensional, *ndimslow will be set to the array size and *ndimmid and
*ndimfast will be set to 1. If the array is 2-dimensional *ndimslow and
*ndimmid will be set as for a call to cbf_get_image_size and *ndimfast
will be set to 1.
The _fs calls give the dimensions in a fast-to-slow order. The calls
with no suffix and the calls _sf calls give the dimensions in
slow-to-fast order
Note that the ordering of dimensions is specified by values of the tag
_array_structure_list.precedence with a precedence of 1 for the fastest
dimension, 2 for the next slower, etc., which is opposite to the
ordering of the dimension arguments for these functions, except for the
ones with the _fs suffix..
Any of the destination pointers may be NULL.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
ndimslow Pointer to the destination slowest dimension.
ndimmid Pointer to the destination next faster dimension.
ndimfast Pointer to the destination fastest dimension.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.26 cbf_get_image, cbf_get_image_fs, cbf_get_image_sf,
cbf_get_real_image, cbf_get_real_image_fs, cbf_get_real_image_sf,
cbf_get_3d_image, cbf_get_3d_image_fs, cbf_get_3d_image_sf,
cbf_get_real_3d_image, cbf_get_real_3d_image_fs,
cbf_get_real_3d_image_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_image (cbf_handle handle, unsigned int reserved, unsigned
int element_number, void *array, size_t elsize, int elsign, size_t
ndimslow, size_t ndimfast);
int cbf_get_image_fs (cbf_handle handle, unsigned int reserved, unsigned
int element_number, void *array, size_t elsize, int elsign, size_t
ndimfast, size_t ndimslow);
int cbf_get_image_sf (cbf_handle handle, unsigned int reserved, unsigned
int element_number, void *array, size_t elsize, int elsign, size_t
ndimslow, size_t ndimfast);
int cbf_get_real_image (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, size_t
ndimslow, size_t ndimfast);
int cbf_get_real_image_fs (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, size_t
ndimfast, size_t ndimslow);
int cbf_get_real_image_sf (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, size_t
ndimslow, size_t ndimfast);
int cbf_get_3d_image (cbf_handle handle, unsigned int reserved, unsigned
int element_number, void *array, size_t elsize, int elsign, size_t
ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_get_3d_image_fs (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, int elsign,
size_t ndimfast, size_t ndimmid, size_t ndimslow);
int cbf_get_3d_image_sf (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, int elsign,
size_t ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_get_real_3d_image (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, size_t
ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_get_real_3d_image_fs (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, size_t
ndimfast, size_t ndimmid, size_t ndimslow);
int cbf_get_real_3d_image_sf (cbf_handle handle, unsigned int reserved,
unsigned int element_number, void *array, size_t elsize, size_t
ndimslow, size_t ndimmid, size_t ndimfast);
DESCRIPTION
cbf_get_image, cbf_get_image_fs and cbf_get_image_sf read the image
array for element number element_number into an array. The array
consists of ndimslow *ndimfast elements of elsize bytes each, starting
at array. The elements are signed if elsign is non-0 and unsigned
otherwise. cbf_get_real_image, cbf_get_real_image_fs and
cbf_get_real_image_sf read the image array of IEEE doubles or floats for
element number element_number into an array. A real array is always
signed. cbf_get_3d_image, cbf_get_3d_image_fs and cbf_get_3d_image_sf
read the 3D image array for element number element_number into an array.
The array consists of ndimslow *ndimmid *ndimfast elements of elsize
bytes each, starting at array. The elements are signed if elsign is
non-0 and unsigned otherwise. cbf_get_real_3d_image,
cbf_get_real_3d_image_fs, cbf_get_real_3d_image_sf reads the 3D image
array of IEEE doubles or floats for element number element_number into
an array. A real array is always signed.
The _fs calls give the dimensions in a fast-to-slow order. The calls
with no suffix and the calls _sf calls give the dimensions in
slow-to-fast order
The structure of the array as a 1-, 2- or 3-dimensional array should
agree with the structure of the array given in the ARRAY_STRUCTURE_LIST
category. If the array is 1-dimensional, ndimslow should be the array
size and ndimfast and, for the 3D calls, ndimmid, should be set to 1
both in the call and in the imgCIF data being processed. If the array is
2-dimensional and a 3D call is used, ndimslow and ndimmid should be the
array dimensions and ndimfast should be set to 1 both in the call and in
the imgCIF data being processed.
If any element in the binary data canOt fit into the destination
element, the destination is set the nearest possible value.
If the value is not binary, the function returns CBF_ASCII.
If the requested number of elements canOt be read, the function will
read as many as it can and then return CBF_ENDOFDATA.
Currently, the destination array must consist of chars, shorts or ints
(signed or unsigned) for cbf_get_image, or IEEE doubles or floats for
cbf_get_real_image. If elsize is not equal to sizeof (char), sizeof
(short), sizeof (int), sizeof(double) or sizeof(float), the function
returns CBF_ARGUMENT.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
array Pointer to the destination array.
elsize Size in bytes of each destination array element.
elsigned Set to non-0 if the destination array elements are
signed.
ndimslow Slowest array dimension.
ndimmid Next faster array dimension.
ndimfast Fastest array dimension.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,
cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf,
cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,
cbf_set_real_3d_image, cbf_set_real_3d_image_fs,
cbf_set_real_3d_image_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_image (cbf_handle handle, unsigned int reserved, unsigned
int element_number, unsigned int compression, void *array, size_t
elsize, int elsign, size_t ndimslow, size_t ndimfast);
int cbf_set_image_fs(cbf_handle handle, unsigned int reserved, unsigned
int element_number, unsigned int compression, void *array, size_t
elsize, int elsign, size_t ndimfast, size_t ndimslow);
int cbf_set_image_sf(cbf_handle handle, unsigned int reserved, unsigned
int element_number, unsigned int compression, void *array, size_t
elsize, int elsign, size_t ndimslow, size_t ndimfast);
int cbf_set_real_image (cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void
*array,size_t elsize, size_t ndimslow, size_t ndimfast);
int cbf_set_real_image_fs(cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void
*array,size_t elsize, size_t ndimfast, size_t ndimslow);
int cbf_set_real_image_sf(cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void
*array,size_t elsize, size_t ndimslow, size_t ndimfast);
int cbf_set_3d_image (cbf_handle handle, unsigned int reserved, unsigned
int element_number, unsigned int compression, void *array, size_t
elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_set_3d_image_fs(cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void *array,
size_t elsize, int elsign, size_t ndimfast, size_t ndimmid, size_t
ndimslow);
int cbf_set_3d_image_sf(cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void *array,
size_t elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t
ndimfast);
int cbf_set_real_3d_image (cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void
*array,size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_set_real_3d_image_fs(cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void
*array,size_t elsize, size_t ndimfast, size_t ndimmid, size_t ndimslow);
int cbf_set_real_3d_image_sf(cbf_handle handle, unsigned int reserved,
unsigned int element_number, unsigned int compression, void
*array,size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);
DESCRIPTION
cbf_set_image, cbf_set_image_fs and cbf_set_image_sf write the image
array for element number element_number. The array consists of ndimfast
*ndimslow elements of elsize bytes each, starting at array. The elements
are signed if elsign is non-zero and unsigned otherwise.
cbf_set_real_image, cbf_set_real_image_fs and cbf_set_real_image_sf
write the image array for element number element_number. The array
consists of ndimfast *ndimslow IEEE double or float elements of elsize
bytes each, starting at array. cbf_set_3d_image, cbf_set_3d_image_fs and
cbf_set_3d_image_sf write the 3D image array for element number
element_number. The array consists of ndimfast *ndimmid *ndimslow
elements of elsize bytes each, starting at array. The elements are
signed if elsign is non-0 and unsigned otherwise. cbf_set_real_3d_image,
cbf_set_real_3d_image_fs and cbf_set_real_3d_image_sf writes the 3D
image array for element number element_number. The array consists of
ndimfast *ndimmid *ndimslow IEEE double or float elements of elsize
bytes each, starting at array.
The _fs calls give the dimensions in a fast-to-slow order. The calls
with no suffix and the calls _sf calls give the dimensions in
slow-to-fast order
If the array is 1-dimensional, ndimslow should be the array size and
ndimfast and, for the 3D calls, ndimmid, should be set to 1. If the
array is 2-dimensional and the 3D calls are used, ndimslow and ndimmid
should be used for the array dimensions and ndimfast should be set to 1.
The array will be compressed using the compression scheme specifed by
compression. Currently, the available schemes are:
CBF_CANONICAL Canonical-code compression (section 3.3.1)
CBF_PACKED CCP4-style packing (section 3.3.2)
CBF_PACKED_V2 CCP4-style packing, version 2 (section 3.3.2)
CBF_BYTE_OFFSET Simple "byte_offset" compression.
CBF_NIBBLE_OFFSET Simple "nibble_offset" compression.
CBF_NONE No compression.
The values compressed are limited to 64 bits. If any element in the
array is larger than 64 bits, the value compressed is the nearest 64-bit
value.
Currently, the source array must consist of chars, shorts or ints
(signed or unsigned)for cbf_set_image, or IEEE doubles or floats for
cbf_set_real_image. If elsize is not equal to sizeof (short), sizeof
(int), sizeof(double) or sizeof(float), the function returns
CBF_ARGUMENT.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
compression Compression type.
array Pointer to the image array.
elsize Size in bytes of each image array element.
elsigned Set to non-0 if the image array elements are signed.
ndimslow Slowest array dimension.
ndimmid Second slowest array dimension.
ndimfast Fastest array dimension.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.28 cbf_count_axis_ancestors, cbf_get_axis_ancestor,
cbf_get_axis_depends_on,
cbf_get_axis_equipment, cbf_get_axis_equipment_component,
cbf_get_axis_offset,
cbf_get_axis_rotation, cbf_get_axis_rotation_axis,
cbf_get_axis_setting,
cbf_get_axis_type,
cbf_get_axis_vector
PROTOTYPE
#include "cbf_simple.h"
int cbf_count_axis_ancestors (cbf_handle handle, const char *axis_id,
unsigned int *ancestors);
int cbf_get_axis_ancestor (cbf_handle handle, const char *axis_id, const
unsigned int ancestor_index, const char * *ancestor);
int cbf_get_axis_depends_on (cbf_handle handle, const char *axis_id,
const char * *depends_on);
int cbf_get_axis_equipment (cbf_handle handle, const char *axis_id,
const char * *equipment);
int cbf_get_axis_equipment_component (cbf_handle handle, const char
*axis_id, const char * *equipment_component);
int cbf_get_axis_offset (cbf_handle handle, const char *axis_id, double
*offset1, double *offset2, double *offset3);
int cbf_get_axis_rotation (cbf_handle handle, const char *axis_id,
double *rotation);
int cbf_get_axis_rotation_axis (cbf_handle handle, const char *axis_id,
const char * *rotation_axis);
int cbf_get_axis_setting (cbf_handle handle, unsigned int reserved,
const char *axis_id, double *start, double *increment);
int cbf_get_axis_type (cbf_handle handle, const char *axis_id,
cbf_axis_type *axis_type);
int cbf_get_axis_vector (cbf_handle handle, const char *axis_id, double
*vector1, double *vector2, double *vector3);
DESCRIPTION
cbf_count_axis_ancestors sets ancestors to the number of ancestors of
axis axis_id. cbf_get_axis_ancestor sets *ancestor to the ancestor axis
of index ancestor_index of axis axis_id, starting with axis_id for
ancestor_index 0.
cbf_get_axis_depends_on sets *depends_on to the immediate ancestor of
axis_id or to "." if there is no such ancestor. cbf_get_axis_equipment
sets *equipment to the equipment of axis_id or to "." if there is no
such equipment. cbf_get_axis_equipment_component sets
*equipment_component to the equipment_component of axis_id or to "." if
there is no such equipment_component.
cbf_get_axis_offset sets *offset1, *offset2 and *offset3 to the
components of the ofset of axis_id.
cbf_get_axis_rotation sets rotation to the rotation of axis_id or to 0
if there is no such rotation. cbf_get_axis_rotation_axis sets
*rotation_axis to the rotation_axis of axis_id or to "." if there is no
such rotation_axis.
cbf_get_axis_setting sets *start and *increment to the corresponding
values of the axis axis_id. Any of the destination pointers may be NULL.
cbf_get_axis_type sets axis_type to the type of axis_id.
cbf_get_axis_vector sets *vector1, *vector2 and *vector3 to the
components of the vector of axis_id.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
axis_id Axis id.
ancestor_index Integer index of the desired ancestor, starting
with 0 for the current axis_id.
ancestor Pointer to destination ancestor name pointer.
depends_on Pointer to destination depends_on name pointer.
equipment Pointer to destination equipment name pointer.
equipment_component Pointer to destination equipment_component name
pointer.
offset1 Pointer to destination first offset component
value.
offset2 Pointer to destination second offset component
value.
offset3 Pointer to destination third offset component
value.
rotation Pointer to destination rotation value.
rotation_axis Pointer to destination rotation_axisn name
pointer.
start Pointer to the destination start value.
increment Pointer to the destination increment value.
type Pointer to destination axis type of type .
vector1 Pointer to destination first vector component
value.
vector2 Pointer to destination second vector component
value.
vector3 Pointer to destination third vector component
value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.29 cbf_set_axis_setting
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_axis_setting (cbf_handle handle, unsigned int reserved,
const char *axis_id, double start, double increment);
DESCRIPTION
cbf_set_axis_setting sets the starting and increment values of the axis
axis_id to start and increment.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
handle CBF handle.
reserved Unused. Any value other than 0 is invalid.
axis_id Axis id.
start Start value.
increment Increment value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.30 cbf_construct_goniometer
PROTOTYPE
#include "cbf_simple.h"
int cbf_construct_goniometer (cbf_handle handle, cbf_goniometer
*goniometer);
DESCRIPTION
cbf_construct_goniometer constructs a goniometer object using the
description in the CBF object handle and initialises the goniometer
handle *goniometer.
ARGUMENTS
handle CBF handle.
goniometer Pointer to the destination goniometer handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.31 cbf_free_goniometer
PROTOTYPE
#include "cbf_simple.h"
int cbf_free_goniometer (cbf_goniometer goniometer);
DESCRIPTION
cbf_free_goniometer destroys the goniometer object specified by
goniometer and frees all associated memory.
ARGUMENTS
goniometer Goniometer handle to free.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.32 cbf_get_rotation_axis
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_rotation_axis (cbf_goniometer goniometer, unsigned int
reserved, double *vector1, double *vector2, double *vector3);
DESCRIPTION
cbf_get_rotation_axis sets *vector1, *vector2, and *vector3 to the 3
components of the goniometer rotation axis used for the exposure.
Any of the destination pointers may be NULL.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
goniometer Goniometer handle.
reserved Unused. Any value other than 0 is invalid.
vector1 Pointer to the destination x component of the rotation
axis.
vector2 Pointer to the destination y component of the rotation
axis.
vector3 Pointer to the destination z component of the rotation
axis.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.33 cbf_get_rotation_range
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_rotation_range (cbf_goniometer goniometer, unsigned int
reserved, double *start, double *increment);
DESCRIPTION
cbf_get_rotation_range sets *start and *increment to the corresponding
values of the goniometer rotation axis used for the exposure.
Either of the destination pointers may be NULL.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
goniometer Goniometer handle.
reserved Unused. Any value other than 0 is invalid.
start Pointer to the destination start value.
increment Pointer to the destination increment value.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.34 cbf_rotate_vector
PROTOTYPE
#include "cbf_simple.h"
int cbf_rotate_vector (cbf_goniometer goniometer, unsigned int reserved,
double ratio, double initial1, double initial2, double initial3, double
*final1, double *final2, double *final3);
DESCRIPTION
cbf_rotate_vector sets *final1, *final2, and *final3 to the 3 components
of the of the vector (initial1, initial2, initial3) after reorientation
by applying the goniometer rotations. The value ratio specif ies the
goniometer setting and varies from 0.0 at the beginning of the exposure
to 1.0 at the end, irrespective of the actual rotation range.
Any of the destination pointers may be NULL.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
goniometer Goniometer handle.
reserved Unused. Any value other than 0 is invalid.
ratio Goniometer setting. 0 = beginning of exposure, 1 = end.
initial1 x component of the initial vector.
initial2 y component of the initial vector.
initial3 z component of the initial vector.
vector1 Pointer to the destination x component of the final
vector.
vector2 Pointer to the destination y component of the final
vector.
vector3 Pointer to the destination z component of the final
vector.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.35 cbf_get_reciprocal
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_reciprocal (cbf_goniometer goniometer, unsigned int
reserved, double ratio, double wavelength, double real1, double real2,
double real3, double *reciprocal1, double *reciprocal2, double
*reciprocal3);
DESCRIPTION
cbf_get_reciprocal sets *reciprocal1, * reciprocal2, and * reciprocal3
to the 3 components of the of the reciprocal-space vector corresponding
to the real-space vector (real1, real2, real3). The reciprocal-space
vector is oriented to correspond to the goniometer setting with all axes
at 0. The value wavelength is the wavlength in AA and the value ratio
specifies the current goniometer setting and varies from 0.0 at the
beginning of the exposur e to 1.0 at the end, irrespective of the actual
rotation range.
Any of the destination pointers may be NULL.
The parameter reserved is presently unused and should be set to 0.
ARGUMENTS
goniometer Goniometer handle.
reserved Unused. Any value other than 0 is invalid.
ratio Goniometer setting. 0 = beginning of exposure, 1 = end.
wavelength Wavelength in AA.
real1 x component of the real-space vector.
real2 y component of the real-space vector.
real3 z component of the real-space vector.
reciprocal1 Pointer to the destination x component of the
reciprocal-space vector.
reciprocal2 Pointer to the destination y component of the
reciprocal-space vector.
reciprocal3 Pointer to the destination z component of the
reciprocal-space vector.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.36 cbf_construct_detector, cbf_construct_reference_detector,
cbf_require_reference_detector
PROTOTYPE
#include "cbf_simple.h"
int cbf_construct_detector (cbf_handle handle, cbf_detector *detector,
unsigned int element_number);
int cbf_construct_reference_detector (cbf_handle handle, cbf_detector
*detector, unsigned int element_number);
int cbf_require_reference_detector (cbf_handle handle, cbf_detector
*detector, unsigned int element_number);
DESCRIPTION
cbf_construct_detector constructs a detector object for detector element
number element_number using the description in the CBF object handle and
initialises the detector handle *detector.
cbf_construct_reference_detector constructs a detector object for
detector element number element_number using the description in the CBF
object handle and initialises the detector handle *detector using the
reference settings of the axes. cbf_require_reference_detector is
similar, but try to force the creations of missing intermediate
categories needed to construct a detector object.
ARGUMENTS
handle CBF handle.
detector Pointer to the destination detector handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.37 cbf_free_detector
PROTOTYPE
#include "cbf_simple.h"
int cbf_free_detector (cbf_detector detector);
DESCRIPTION
cbf_free_detector destroys the detector object specified by detector and
frees all associated memory.
ARGUMENTS
detector Detector handle to free.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.38 cbf_construct_positioner, cbf_construct_reference_positioner,
PROTOTYPE
#include "cbf_simple.h"
int cbf_construct_positioner (cbf_handle handle, cbf_positioner
*positioner, const char *axis_id);
int cbf_construct_reference_positioner (cbf_handle handle,
cbf_positioner *positioner, const char *axis_id);
DESCRIPTION
cbf_construct_positioner constructs a positioner object for the axis
given by axis_id using the description in the CBF object handle and
initialises the positioner handle *positioner.
cbf_construct_reference positioner constructs a positioner object for
the axis given by axis_id using the description in the CBF object handle
and initialises the detector handle *detector using the reference
settings of the axes.
ARGUMENTS
handle CBF handle.
detector Pointer to the destination detector handle.
axis_id The identifier of the axis in the "axis" category.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.39 cbf_free_positioner
PROTOTYPE
#include "cbf_simple.h"
int cbf_free_positioner (cbf_positioner positioner);
DESCRIPTION
cbf_free_positioner destroys the positioner object specified by
positioner and frees all associated memory.
ARGUMENTS
positioner Positioner handle to free.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.40 cbf_get_beam_center, cbf_get_beam_center_fs, cbf_get_beam_center_sf,
cbf_set_beam_center, cbf_set_beam_center_fs, cbf_set_beam_center_sf,
set_reference_beam_center, set_reference_beam_center_fs,
set_reference_beam_center_fs
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_beam_center (cbf_detector detector, double *indexslow,
double *indexfast, double *centerslow, double *centerfast);
int cbf_get_beam_center_fs (cbf_detector detector, double *indexfast,
double *indexslow, double *centerfast, double *centerslow);
int cbf_get_beam_center_sf (cbf_detector detector, double *indexslow,
double *indexfast, double *centerslow, double *centerfast);
int cbf_set_beam_center (cbf_detector detector, double *indexslow,
double *indexfast, double *centerslow, double *centerfast);
int cbf_set_beam_center_fs (cbf_detector detector, double *indexfast,
double *indexslow, double *centerfast, double *centerslow);
int cbf_set_beam_center_sf (cbf_detector detector, double *indexslow,
double *indexfast, double *centerslow, double *centerfast);
int cbf_set_reference_beam_center (cbf_detector detector, double
*indexslow, double *indexfast, double *centerslow, double *centerfast);
int cbf_set_reference_beam_center_fs (cbf_detector detector, double
*indexfast, double *indexslow, double *centerfast, double *centerslow);
int cbf_set_reference_beam_center_sf (cbf_detector detector, double
*indexslow, double *indexfast, double *centerslow, double *centerfast);
DESCRIPTION
cbf_get_beam_center sets *centerfast and *centerslow to the
displacements in mm along the detector axes from pixel (0, 0) to the
point at which the beam intersects the detector and *indexfast and
*indexslow to the corresponding indices. cbf_set_beam_center sets the
offsets in the axis category for the detector element axis with
precedence 1 to place the beam center at the position given in mm by
*centerfast and *centerslow as the displacements in mm along the
detector axes from pixel (0, 0) to the point at which the beam
intersects the detector at the indices given *indexfast and *indexslow.
cbf_set_reference_beam_center sets the displacments in the
array_structure_list_axis category to place the beam center at the
position given in mm by *centerfast and *centerslow as the displacements
in mm along the detector axes from pixel (0, 0) to the point at which
the beam intersects the detector at the indices given by *indexfast and
*indexslow. In order to achieve consistent results, a reference detector
should be used for detector to have all axes at their reference
settings.
Note that the precedence 1 axis is the fastest axis, so that *centerfast
and *indexfast are the fast axis components of the center and
*centerslow and *indexslow are the slow axis components of the center.
The _fs calls give the displacments in a fast-to-slow order. The calls
with no suffix and the calls _sf calls give the displacements in
slow-to-fast order
Any of the destination pointers may be NULL for getting the beam center.
For setting the beam axis, either the indices of the center must not be
NULL.
The indices are non-negative for beam centers within the detector
surface, but the center for an axis with a negative increment will be
negative for a beam center within the detector surface.
For cbf_set_beam_center if the diffrn_data_frame category exists with a
row for the corresponding element id, the values will be set for
_diffrn_data_frame.center_fast and _diffrn_data_frame.center_slow in
millimetres and the value of _diffrn_data_frame.center_units will be set
to 'mm'.
For cbf_set_reference_beam_center if the diffrn_detector_element
category exists with a row for the corresponding element id, the values
will be set for _diffrn_detector_element.reference_center_fast and
_diffrn_detector_element.reference_center_slow in millimetres and the
value of _diffrn_detector_element.reference_units will be set to 'mm'.
ARGUMENTS
detector Detector handle.
indexfast Pointer to the destination fast index.
indexslow Pointer to the destination slow index.
centerfast Pointer to the destination displacement along the fast
axis.
centerslow Pointer to the destination displacement along the slow
axis.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.41 cbf_get_detector_distance
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_detector_distance (cbf_detector detector, double *distance);
DESCRIPTION
cbf_get_detector_distance sets *distance to the nearest distance from
the sample position to the detector plane.
ARGUMENTS
detector Detector handle.
distance Pointer to the destination distance.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.42 cbf_get_detector_normal
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_detector_normal (cbf_detector detector, double *normal1,
double *normal2, double *normal3);
DESCRIPTION
cbf_get_detector_normal sets *normal1, *normal2, and *normal3 to the 3
components of the of the normal vector to the detector plane. The vector
is normalized.
Any of the destination pointers may be NULL.
ARGUMENTS
detector Detector handle.
normal1 Pointer to the destination x component of the normal
vector.
normal2 Pointer to the destination y component of the normal
vector.
normal3 Pointer to the destination z component of the normal
vector.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.43 cbf_get_detector_axis_slow, cbf_get_detector_axis_slow,
cbf_get_detector_axes, cbf_get_detector_axes_fs, cbf_get_detector_axes_sf,
cbf_get_detector_surface_axes
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_detector_axis_slow (cbf_detector detector, double
*slowaxis1, double *slowaxis2, double *slowaxis3);
int cbf_get_detector_axis_fast (cbf_detector detector, double
*fastaxis1, double *fastaxis2, double *fastaxis3);
int cbf_get_detector_axes (cbf_detector detector, double *slowaxis1,
double *slowaxis2, double *slowaxis3, double *fastaxis1, double
*fastaxis2, double *fastaxis3);
int cbf_get_detector_axes_fs (cbf_detector detector, double *fastaxis1,
double *fastaxis2, double *fastaxis3, double *slowaxis1, double
*slowaxis2, double *slowaxis3);
int cbf_get_detector_axes_sf (cbf_detector detector, double *slowaxis1,
double *slowaxis2, double *slowaxis3, double *fastaxis1, double
*fastaxis2, double *fastaxis3);
int cbf_get_detector_surface_axes(cbf_detector detector, const char * *
axis_id1, const char * * axis_id2);
DESCRIPTION
cbf_get_detector_axis_slow sets *slowaxis1, *slowaxis2, and *slowaxis3
to the 3 components of the slow axis of the specified detector at the
current settings of all axes. cbf_get_detector_axis_slow sets
*fastaxis1, *fastaxis2, and *fastaxis3 to the 3 components of the fast
axis of the specified detector at the current settings of all axes.
cbf_get_detector_axes, cbf_get_detector_axes_fs and int
cbf_get_detector_axes_sf set *slowaxis1, *slowaxis2, and *slowaxis3 to
the 3 components of the slow axis and *fastaxis1, *fastaxis2, and
*fastaxis3 to the 3 components of the fast axis of the specified
detector at the current settings of all axes.
cbf_get_detector_surface_axes sets *axis_id1 and *axis_id2 to the names
of the two surface axes of the detector or ".",
Any of the destination pointers may be NULL.
ARGUMENTS
detector Detector handle.
slowaxis1 Pointer to the destination x component of the slow axis
vector.
slowaxis2 Pointer to the destination y component of the slow axis
vector.
slowaxis3 Pointer to the destination z component of the slow axis
vector.
fastaxis1 Pointer to the destination x component of the fast axis
vector.
fastaxis2 Pointer to the destination y component of the fast axis
vector.
fastaxis3 Pointer to the destination z component of the fast axis
vector.
axis_id1 Pointer to the destination first surface axis name.
axis_id1 Pointer to the destination first surface axis name.
axis_id2 Pointer to the destination second surface axis name.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.44 cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs,
cbf_get_pixel_coordinates_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_pixel_coordinates (cbf_detector detector, double indexslow,
double indexfast, double *coordinate1, double *coordinate2, double
*coordinate3);
int cbf_get_pixel_coordinates_fs (cbf_detector detector, double
indexfast, double indexslow, double *coordinate1, double *coordinate2,
double *coordinate3);
int cbf_get_pixel_coordinates_sf (cbf_detector detector, double
indexslow, double indexfast, double *coordinate1, double *coordinate2,
double *coordinate3);
DESCRIPTION
cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs and
cbf_get_pixel_coordinates_sf ses *coordinate1, *coordinate2, and
*coordinate3 to the vector position of pixel (indexfast, indexslow) on
the detector surface. If indexslow and indexfast are integers then the
coordinates correspond to the center of a pixel.
Any of the destination pointers may be NULL.
ARGUMENTS
detector Detector handle.
indexslow Slow index.
indexfast Fast index.
coordinate1 Pointer to the destination x component.
coordinate2 Pointer to the destination y component.
coordinate3 Pointer to the destination z component.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs,
cbf_get_pixel_normal_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_pixel_normal (cbf_detector detector, double indexslow,
double indexfast, double *normal1, double *normal2, double *normal3);
int cbf_get_pixel_normal_fs (cbf_detector detector, double indexfast,
double indexslow, double *normal1, double *normal2, double *normal3);
int cbf_get_pixel_normal (cbf_detector detector, double indexslow,
double indexfast, double *normal1, double *normal2, double *normal3);
DESCRIPTION
cbf_get_detector_normal, cbf_get_pixel_normal_fs and
cbf_get_pixel_normal_sf set *normal1, *normal2, and *normal3 to the 3
components of the of the normal vector to the pixel at (indexfast,
indexslow). The vector is normalized.
Any of the destination pointers may be NULL.
ARGUMENTS
detector Detector handle.
indexslow Slow index.
indexfast Fast index.
normal1 Pointer to the destination x component of the normal
vector.
normal2 Pointer to the destination y component of the normal
vector.
normal3 Pointer to the destination z component of the normal
vector.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs, cbf_get_pixel_area_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_pixel_area (cbf_detector detector, double indexslow, double
indexfast, double *area, double *projected_area);
int cbf_get_pixel_area_fs(cbf_detector detector, double indexfast,
double indexslow, double *area, double *projected_area);
int cbf_get_pixel_area_sf(cbf_detector detector, double indexslow,
double indexfast, double *area, double *projected_area);
DESCRIPTION
cbf_get_pixel_area, cbf_get_pixel_area_fs and cbf_get_pixel_area_sf set
*area to the area of the pixel at (indexfast, indexslow) on the detector
surface and *projected_area to the apparent area of the pixel as viewed
from the sample position, with indexslow being the slow axis and
indexfast being the fast axis.
Either of the destination pointers may be NULL.
ARGUMENTS
detector Detector handle.
indexfast Fast index.
indexslow Slow index.
area Pointer to the destination area in mm2.
projected_area Pointer to the destination apparent area in mm2.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs, cbf_get_pixel_size_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_pixel_size (cbf_handle handle, unsigned int element_number,
int axis_number, double *psize);
int cbf_get_pixel_size_fs(cbf_handle handle, unsigned int
element_number, int axis_number, double *psize);
int cbf_get_pixel_size_sf(cbf_handle handle, unsigned int
element_number, int axis_number, double *psize);
DESCRIPTION
cbf_get_pixel_size and cbf_get_pixel_size_sf set *psize to point to the
double value in millimeters of the axis axis_number of the detector
element element_number. The axis_number is numbered from 1, starting
with the slowest axis. cbf_get_pixel_size_fs sets *psize to point to the
double value in millimeters of the axis axis_number of the detector
element element_number. The axis_number is numbered from 1, starting
with the fastest axis.
If a negative axis number is given, the order of axes is reversed, so
that -1 specifies the slowest axis for cbf_get_pixel_size_fs and the
fastest axis for cbf_get_pixel_size_sf.
If the pixel size is not given explcitly in the "array_element_size"
category, the function returns CBF_NOTFOUND.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
axis_number The number of the axis, starting from 1 for the
fastest for cbf_get_pixel_size and
cbf_get_pixel_size_fs and the slowest for
cbf_get_pixel_size_sf.
psize Pointer to the destination pixel size.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs, cbf_set_pixel_size_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_pixel_size (cbf_handle handle, unsigned int element_number,
int axis_number, double psize);
int cbf_set_pixel_size_fs(cbf_handle handle, unsigned int
element_number, int axis_number, double psize);
int cbf_set_pixel_size_sf(cbf_handle handle, unsigned int
element_number, int axis_number, double psize);
DESCRIPTION
cbf_set_pixel_size and cbf_set_pixel_size_sf set the item in the "size"
column of the "array_structure_list" category at the row which matches
axis axis_number of the detector element element_number converting the
double pixel size psize from meters to millimeters in storing it in the
"size" column for the axis axis_number of the detector element
element_number. The axis_number is numbered from 1, starting with the
slowest axis. cbf_set_pixel_size_fs sets the item in the "size" column
of the "array_structure_list" category at the row which matches axis
axis_number of the detector element element_number converting the double
pixel size psize from meters to millimeters in storing it in the "size"
column for the axis axis_number of the detector element element_number.
The axis_number is numbered from 1, starting with the fastest axis.
If a negative axis number is given, the order of axes is reversed, so
that -1 specifies the slowest axis for cbf_get_pixel_size_fs and the
fastest axis for cbf_get_pixel_size_sf.
If the "array_structure_list" category does not already exist, it is
created.
If the appropriate row in the "array_structure_list" catgeory does not
already exist, it is created.
If the pixel size is not given explcitly in the "array_element_size
category", the function returns CBF_NOTFOUND.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
axis_number The number of the axis, fastest first, starting from
1.
psize The pixel size in millimeters.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.49 cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_fs,
cbf_get_inferred_pixel_size_sf
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_inferred_pixel_size (cbf_detector detector, int axis_number,
double *psize);
int cbf_get_inferred_pixel_size_fs(cbf_detector detector, int
axis_number, double *psize);
int cbf_get_inferred_pixel_size_sf(cbf_detector detector, int
axis_number, double *psize);
DESCRIPTION
cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_sf set *psize
to point to the double value in millimeters of the pixel size for the
axis axis_number value. The slow index is treated as axis 1 and the next
faster index is treated as axis 2. cbf_get_inferred_pixel_size_fs sets
*psize to point to the double value in millimeters of the pixel size for
the axis axis_number value. The fast index is treated as axis 1 and the
next slower index is treated as axis 2.
If the axis number is negative, the axes are used in the reverse order
so that an axis_number of -1 indicates the fast axes in a call to
cbf_get_inferred_pixel_size or cbf_get_inferred_pixel_size_sf and
indicates the fast axis in a call to cbf_get_inferred_pixel_size_fs.
ARGUMENTS
detector Detector handle.
axis_number The number of the axis.
area Pointer to the destination pizel size in mm.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.50 cbf_get_unit_cell
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_unit_cell (cbf_handle handle, double cell[6], double
cell_esd[6] );
DESCRIPTION
cbf_get_unit_cell sets cell[0:2] to the double values of the cell edge
lengths a, b and c in AAngstroms, cell[3:5] to the double values of the
cell angles a, b and g in degrees, cell_esd[0:2] to the double values of
the estimated strandard deviations of the cell edge lengths a, b and c
in AAngstroms, cell_esd[3:5] to the double values of the estimated
standard deviations of the the cell angles a, b and g in degrees.
The values returned are retrieved from the first row of the "cell"
category. The value of "_cell.entry_id" is ignored.
cell or cell_esd may be NULL.
If cell is NULL, the cell parameters are not retrieved.
If cell_esd is NULL, the cell parameter esds are not retrieved.
If the "cell" category is present, but some of the values are missing,
zeros are returned for the missing values.
ARGUMENTS
handle CBF handle.
cell Pointer to the destination array of 6 doubles for the cell
parameters.
cell_esd Pointer to the destination array of 6 doubles for the cell
parameter esds.
RETURN VALUE
Returns an error code on failure or 0 for success. No errors is returned
for missing values if the "cell" category exists.
SEE ALSO
2.4.51 cbf_set_unit_cell
2.4.52 cbf_get_reciprocal_cell
2.4.53 cbf_set_reciprocal_cell
2.4.54 cbf_compute_cell_volume
2.4.55 cbf_compute_reciprocal_cell
----------------------------------------------------------------------
2.4.51 cbf_set_unit_cell
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_unit_cell (cbf_handle handle, double cell[6], double
cell_esd[6] );
DESCRIPTION
cbf_set_unit_cell sets the cell parameters to the double values given in
cell[0:2] for the cell edge lengths a, b and c in AAngstroms, the double
values given in cell[3:5] for the cell angles a, b and g in degrees, the
double values given in cell_esd[0:2] for the estimated strandard
deviations of the cell edge lengths a, b and c in AAngstroms, and the
double values given in cell_esd[3:5] for the estimated standard
deviations of the the cell angles a, b and g in degrees.
The values are placed in the first row of the "cell" category. If no
value has been given for "_cell.entry_id", it is set to the value of the
"diffrn.id" entry of the current data block.
cell or cell_esd may be NULL.
If cell is NULL, the cell parameters are not set.
If cell_esd is NULL, the cell parameter esds are not set.
If the "cell" category is not present, it is created. If any of the
necessary columns are not present, they are created.
ARGUMENTS
handle CBF handle.
cell Pointer to the array of 6 doubles for the cell parameters.
cell_esd Pointer to the array of 6 doubles for the cell parameter
esds.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.4.50 cbf_get_unit_cell
2.4.52 cbf_get_reciprocal_cell
2.4.53 cbf_set_reciprocal_cell
2.4.54 cbf_compute_cell_volume
2.4.55 cbf_compute_reciprocal_cell
----------------------------------------------------------------------
SEE ALSO
2.4.52 cbf_get_reciprocal_cell
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_reciprocal_cell (cbf_handle handle, double cell[6], double
cell_esd[6] );
DESCRIPTION
cbf_get_reciprocal_cell sets cell[0:2] to the double values of the
reciprocal cell edge lengths a*, b* and c* in AAngstroms-1, cell[3:5] to
the double values of the reciprocal cell angles a*, b* and g* in
degrees, cell_esd[0:2] to the double values of the estimated strandard
deviations of the reciprocal cell edge lengths a*, b* and c* in
AAngstroms-1, cell_esd[3:5] to the double values of the estimated
standard deviations of the the reciprocal cell angles a*, b* and g* in
degrees.
The values returned are retrieved from the first row of the "cell"
category. The value of "_cell.entry_id" is ignored.
cell or cell_esd may be NULL.
If cell is NULL, the reciprocal cell parameters are not retrieved.
If cell_esd is NULL, the reciprocal cell parameter esds are not
retrieved.
If the "cell" category is present, but some of the values are missing,
zeros are returned for the missing values.
ARGUMENTS
handle CBF handle.
cell Pointer to the destination array of 6 doubles for the
reciprocal cell parameters.
cell_esd Pointer to the destination array of 6 doubles for the
reciprocal cell parameter esds.
RETURN VALUE
Returns an error code on failure or 0 for success. No errors is returned
for missing values if the "cell" category exists.
SEE ALSO
2.4.50 cbf_get_unit_cell
2.4.51 cbf_set_unit_cell
2.4.53 cbf_set_reciprocal_cell
2.4.54 cbf_compute_cell_volume
2.4.55 cbf_compute_reciprocal_cell
----------------------------------------------------------------------
2.4.53 cbf_set_reciprocal_cell
PROTOTYPE
#include "cbf_simple.h"
int cbf_set_reciprocal_cell (cbf_handle handle, double cell[6], double
cell_esd[6] );
DESCRIPTION
cbf_set_reciprocal_cell sets the reciprocal cell parameters to the
double values given in cell[0:2] for the reciprocal cell edge lengths
a*, b* and c* in AAngstroms-1, the double values given in cell[3:5] for
the reciprocal cell angles a*, b* and g* in degrees, the double values
given in cell_esd[0:2] for the estimated strandard deviations of the
reciprocal cell edge lengths a*, b* and c* in AAngstroms, and the double
values given in cell_esd[3:5] for the estimated standard deviations of
the reciprocal cell angles a*, b* and g* in degrees.
The values are placed in the first row of the "cell" category. If no
value has been given for "_cell.entry_id", it is set to the value of the
"diffrn.id" entry of the current data block.
cell or cell_esd may be NULL.
If cell is NULL, the reciprocal cell parameters are not set.
If cell_esd is NULL, the reciprocal cell parameter esds are not set.
If the "cell" category is not present, it is created. If any of the
necessary columns are not present, they are created.
ARGUMENTS
handle CBF handle.
cell Pointer to the array of 6 doubles for the reciprocal cell
parameters.
cell_esd Pointer to the array of 6 doubles for the reciprocal cell
parameter esds.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.4.50 cbf_get_unit_cell
2.4.51 cbf_set_unit_cell
2.4.52 cbf_get_reciprocal_cell
2.4.54 cbf_compute_cell_volume
2.4.55 cbf_compute_reciprocal_cell
----------------------------------------------------------------------
2.4.54 cbf_compute_cell_volume
PROTOTYPE
#include "cbf_simple.h"
int cbf_compute_cell_volume ( double cell[6], double *volume );
DESCRIPTION
cbf_compute_cell_volume sets *volume to point to the volume of the unit
cell computed from the double values in cell[0:2] for the cell edge
lengths a, b and c in AAngstroms and the double values given in
cell[3:5] for the cell angles a, b and g in degrees.
ARGUMENTS
cell Pointer to the array of 6 doubles giving the cell parameters.
volume Pointer to the doubles for cell volume.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.4.50 cbf_get_unit_cell
2.4.51 cbf_set_unit_cell
2.4.52 cbf_get_reciprocal_cell
2.4.53 cbf_set_reciprocal_cell
2.4.55 cbf_compute_reciprocal_cell
----------------------------------------------------------------------
2.4.55 cbf_compute_reciprocal_cell
PROTOTYPE
#include "cbf_simple.h"
int cbf_compute_reciprocal_cell ( double cell[6], double rcell[6] );
DESCRIPTION
cbf_compute_reciprocal_cell sets rcell to point to the array of
reciprocal cell parameters computed from the double values cell[0:2]
giving the cell edge lengths a, b and c in AAngstroms, and the double
values cell[3:5] giving the cell angles a, b and g in degrees. The
double values rcell[0:2] will be set to the reciprocal cell lengths a*,
b* and c* in AAngstroms-1 and the double values rcell[3:5] will be set
to the reciprocal cell angles a*, b* and g* in degrees.
ARGUMENTS
cell Pointer to the array of 6 doubles giving the cell parameters.
rcell Pointer to the destination array of 6 doubles giving the
reciprocal cell parameters.
volume Pointer to the doubles for cell volume.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.4.50 cbf_get_unit_cell
2.4.51 cbf_set_unit_cell
2.4.52 cbf_get_reciprocal_cell
2.4.53 cbf_set_reciprocal_cell
2.4.54 cbf_compute_cell_volume
----------------------------------------------------------------------
2.4.56 cbf_get_orientation_matrix, cbf_set_orientation_matrix
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_orientation_matrix (cbf_handle handle, double ub_matrix[9]);
int cbf_set_orientation_matrix (cbf_handle handle, double ub_matrix[9]);
DESCRIPTION
cbf_get_orientation_matrix sets ub_matrix to point to the array of
orientation matrix entries in the "diffrn" category in the order of
columns:
"UB[1][1]" "UB[1][2]" "UB[1][3]"
"UB[2][1]" "UB[2][2]" "UB[2][3]"
"UB[3][1]" "UB[3][2]" "UB[3][3]"
cbf_set_orientation_matrix sets the values in the "diffrn" category to
the values pointed to by ub_matrix.
ARGUMENTS
handle CBF handle.
ubmatric Source or destination array of 9 doubles giving the
orientation matrix parameters.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_bin_sizes(cbf_handle handle, unsigned int element_number,
double * slowbinsize, double * fastbinsize);
int cbf_set_bin_sizes(cbf_handle handle, unsigned int element_number,
double slowbinsize_in,double fastbinsize_in);
DESCRIPTION
cbf_get_bin_sizes sets slowbinsize to point to the value of the number
of pixels composing one array element in the dimension that changes at
the second-fastest rate and fastbinsize to point to the value of the
number of pixels composing one array element in the dimension that
changes at the fastest rate for the dectector element with the ordinal
element_number. cbf_set_bin_sizes sets the the pixel bin sizes in the
"array_intensities" category to the values of slowbinsize_in for the
number of pixels composing one array element in the dimension that
changes at the second-fastest rate and fastbinsize_in for the number of
pixels composing one array element in the dimension that changes at the
fastest rate for the dectector element with the ordinal element_number.
In order to allow for software binning involving fractions of pixels,
the bin sizes are doubles rather than ints.
ARGUMENTS
handle CBF handle.
element_number The number of the detector element counting from 0 by
order of appearance in the "diffrn_data_frame"
category.
slowbinsize Pointer to the returned number of pixels composing
one array element in the dimension that changes at the
second-fastest rate.
fastbinsize Pointer to the returned number of pixels composing
one array element in the dimension that changes at the
fastest rate.
slowbinsize_in The number of pixels composing one array element in
the dimension that changes at the second-fastest rate.
fastbinsize_in The number of pixels composing one array element in
the dimension that changes at the fastest rate.
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise, cbf_get_reference_poise
PROTOTYPE
#include "cbf_simple.h"
int cbf_get_axis_poise(cbf_handle handle, double ratio, double *
vector1, double * vector2, double * vector3, double * offset1, double *
offset2, double * offset3, double * angle, const char * axis_id, const
char * frame_id);
int cbf_get_goniometer_poise(cbf_goniometer goniometer, double ratio,
double * vector1, double * vector2, double * vector3, double * offset1,
double * offset2, double * offset3, double * angle);
int cbf_get_axis_reference_poise(cbf_handle handle, double * vector1,
double * vector2, double * vector3, double * offset1, double * offset2,
double * offset3, const char * axis_id);
DESCRIPTION
cbf_get_axis_poise sets vector1, vector2, vector3 to point to the
components of the axis vector for axis axis_id, offset1, offset2,
offset3 to point to the components of the axis base offset vector for
axis axis_id, and angle to point to the angle of rotation of axis
axis_id after application of the axis settings for frame frame_id, using
ratio, a value between 0 and 1, indicating how far into the internal
motion in the frame to go. If frame_id is the string ".", the first
frame found is used. If there is more than one frame, which frame will
be found is indeterminate. If frame_id is NULL, the overall setting for
the scan are used, rather than those for any particular frame. The
vector and offset reported are the reference vector and offset of the
axis axis_id transformed by application of all motions of the axes on
which axis_id depends.
cbf_get_goniometer_poise vector1, vector2, vector3 to point to the
components of the axis vector for the goniometer axis, offset1, offset2,
offset3 to point to the components of the axis base offset vector for
the goniometer axis, and angle to point to the angle of rotation of the
goniometer axis after application of all axis settings in the goniometer
deriving the vector, offset and angle from the resulting matrix.
Calculation of the vector is indeterminate if the angle is zero.
cbf_get_axis_reference_poise sets vector1, vector2, vector3 to point to
the components of the axis vector for axis axis_id, offset1, offset2,
offset3 to point to the components of the axis base offset vector for
axis axis_id unmodified by axis rotations. Any of the pointers may be
specified as NULL.
ARGUMENTS
handle CBF handle.
ratio A number between 0 and 1 indication how far into the
frame to go
vector1 Pointer to the first component of the axis vector
vector2 Pointer to the second component of the axis vector
vector3 Pointer to the third component of the axis vector
offset1 Pointer to the first component of the axis offset
offset2 Pointer to the second component of the axis offset
offset3 Pointer to the third component of the axis offset
angle Pointer to the rotation angle
axis_id The specified axis
frame_id The specified frame
positioner CBF goniometer
RETURN VALUE
Returns an error code on failure or 0 for success.
----------------------------------------------------------------------
2.5 F90 function interfaces
At the suggestion of W. Kabsch, Fortran 90/95 routines have been added
to CBFlib. As of this writing code has been written to allow the reading
of CBF_BYTE_OFFSET, CBF_PACKED and CBF_PACKED_V2 binary images. This
code has been gather into FCBlib (Fortran Crystallographic Binary
library) as lib/libfcb.
In general, most of the FCBlib functions return 0 for normal completion
and a non-zero value in case of an error. In a few cases, such as
FCB_ATOL_WCNT and FCB_NBLEN_ARRAY in order to conform to the conventions
for commonly used C-equivalent functions, the function return is the
value being computed.
For each function, an interface is given to be included in the
declarations of your Fortran 90/95 code. Some functions in FCBlIB are
not intended for external use and are subject to change:
FCB_UPDATE_JPA_POINTERS_I2, FCB_UPDATE_JPA_POINTERS_I4,
FCB_UPDATE_JPA_POINTERS_3D_I2, FCB_UPDATE_JPA_POINTERS_3D_I4 and
CNT2PIX. These names should not be used for user routines.
The functions involving reading of a CBF have been done strictly in
Fortran without the use of C code. This has required some compromises
and the use of direct access I/O. Rather than putting the buffer and its
control variables into COMMON these are passed as local arguments to
make the routines inherently 'threadsafe' in a parallel programming
environment. Note also, that a reading error could occur for the last
record if it does not fill a full block. The code is written to recover
from end-of-record and end-of-file errors, if possible. On many modern
system, no special action is required, but on some systems it may be
necessary to make use of the padding between the end of binary data and
the terminal MIME boundary marker in binary sections. To ensure maximum
portability of CBF files, a padding of 4095 bytes is recommended.
Existing files without padding can be converted to files with padding by
use of the new -p4 option for cif2cbf.
2.5.1 FCB_ATOL_WCNT
INTERFACE
INTEGER(8) FUNCTION FCB_ATOL_WCNT(ARRAY, N, CNT)
INTEGER(1),INTENT(IN):: ARRAY(N)
INTEGER, INTENT(IN):: N
INTEGER, INTENT(OUT):: CNT
END FUNCTION
END INTERFACE
FCB_ATOL_WCNT converts INTEGER(1) bytes in ARRAY of N bytes to an
INTEGER(8) value returned as the function value. The number of bytes of
ARRAY actually used before encountering a character not used to form the
number is returned in CNT.
The scan stops at the first byte in ARRAY that cannot be properly parsed
as part of the integer result.
ARGUMENTS
ARRAY The array of INTEGER(1) bytes to be scanned
N The INTEGER size of ARRAY
CNT The INTEGER size of the portion of ARRAY scanned.
RETURN VALUE
Returns the INTEGER(8) value derived from the characters ARRAY(1:CNT)
scanned.
----------------------------------------------------------------------
2.5.2 FCB_CI_STRNCMPARR
INTERFACE
INTEGER FUNCTION FCB_CI_STRNCMPARR(STRING>, ARRAY, N, LIMIT)
CHARACTER(LEN=*),INTENT(IN):: STRING>
INTEGER, INTENT(IN):: N, LIMIT
INTEGER(1), INTENT(IN):: ARRAY(N)
END FUNCTION
END INTERFACE
The function FCB_CI_STRNCMPARR compares up to LIMIT characters of
character string STRING and INTEGER(1) byte array ARRAY of dimension N
in a case-insensitive manner, returning 0 for a match.
ARGUMENTS
STRING A character string
ARRAY The array of INTEGER(1) bytes to be scanned
N The INTEGER size of ARRAY
N The INTEGER limit on the number of characters to consider in
the comparison
RETURN VALUE
Returns 0 if the string and array match, a non-zero value otherwise.
----------------------------------------------------------------------
2.5.3 FCB_EXIT_BINARY
INTERFACE
INTEGER FUNCTION FCB_EXIT_BINARY(TAPIN,LAST_CHAR,FCB_BYTES_IN_REC,&
BYTE_IN_FILE,REC_IN_FILE,BUFFER, &
PADDING )
INTEGER, INTENT(IN) :: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE
INTEGER(1),INTENT(INOUT):: LAST_CHAR,BUFFER(FCB_BYTES_IN_REC)
INTEGER(8),INTENT(IN) :: PADDING
END FUNCTION
END INTERFACE
The function FCB_EXIT_BINARY is used to skip from the end of a binary
section past any padding to the end of the text section that encloses
the binary section. The values of the arguments must be consistent with
those in the last call to FCB_NEXT_BINARY
ARGUMENTS
TAPIN The INTEGER Fortran device unit number assigned to
image file.
LAST_CHAR The last character (as an INTEGER(1) byte) read.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN
PADDING The INTEGER(8) number of bytes of padding after the
binary data and before the closing MIME boundary.
RETURN VALUE
Returns 0 if the function is successful. Returns whatever non-zero error
value is reported by FCB_READ_LINE if a necessary next line cannot be
read.
SEE ALSO
2.5.5 FCB_NEXT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.9 FCB_READ_BYTE
2.5.11 FCB_READ_LINE
----------------------------------------------------------------------
2.5.4 FCB_NBLEN_ARRAY
INTERFACE
INTEGER FUNCTION FCB_NBLEN_ARRAY(ARRAY, ARRAYLEN)
INTEGER, INTENT(IN):: ARRAYLEN
INTEGER(1), INTENT(IN):: ARRAY(ARRAYLEN)
END FUNCTION
END INTERFACE
The function FCB_NBLEN_ARRAY returns the trimmed length of the
INTEGER(1) byte array ARRAY of dimension ARRAYLEN after removal of
trailing ASCII blanks, horizontal tabs (Z'09'), newlines (Z'0A') and
carriage returns (Z'0D'). The resulting length may be zero.
The INTEGER trimmed length is returned as the function value.
ARGUMENTS
ARRAY The array of bytes for which the trimmed length is
required.
ARRAYLEN The dimension of the array of bytes to be scanned.
RETURN VALUE
Returns the trimmed length of the array ARRAY.
----------------------------------------------------------------------
2.5.5 FCB_NEXT_BINARY
INTERFACE
INTEGER FUNCTION FCB_NEXT_BINARY(TAPIN,LAST_CHAR,FCB_BYTES_IN_REC,&
BYTE_IN_FILE,REC_IN_FILE,BUFFER, &
ENCODING,SIZE,ID,DIGEST, &
COMPRESSION,BITS,VORZEICHEN,REELL,&
BYTEORDER,DIMOVER,DIM1,DIM2,DIM3, &
PADDING )
INTEGER, INTENT(IN) :: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE
INTEGER(1),INTENT(INOUT):: LAST_CHAR,BUFFER(FCB_BYTES_IN_REC)
INTEGER, INTENT(OUT) :: ENCODING
INTEGER, INTENT(OUT) :: SIZE !Binary size
INTEGER, INTENT(OUT) :: ID !Binary ID
CHARACTER(len=*),INTENT(OUT):: DIGEST !Message digest
INTEGER, INTENT(OUT):: COMPRESSION
INTEGER, INTENT(OUT):: BITS,VORZEICHEN,REELL
CHARACTER(len=*),INTENT(OUT):: BYTEORDER
INTEGER(8), INTENT(OUT):: DIMOVER
INTEGER(8), INTENT(OUT):: DIM1
INTEGER(8), INTENT(OUT):: DIM2
INTEGER(8), INTENT(OUT):: DIM3
INTEGER(8), INTENT(OUT):: PADDING
END FUNCTION
END INTERFACE
The function FCB_NEXT_BINARY skips to the start of the next binary
section in the image file on unit TAPIN leaving the file positioned for
a subsequent read of the image data. The skip may prior to the text
field that contains the binary section. When the text filed is reached,
it will be scanned for a MIME boundary marker, and, if it is found the
subsequence MIME headers will be used to populate the arguments
ENCODING, SIZE, ID, DIGEST, COMPRESSION, BITS, VORZEICHEN,REELL,
BYTEORDER, DIMOVER, DIM1, DIM2,DIM3, PADDING.
The value returned in ENCODING is taken from the MIME header
Content-Transfer-Encoding as an INTEGER. It is returned as 0 if not
specified. The reported value is one of the integer values ENC_NONE
(Z'0001') for BINARY encoding, ENC_BASE64 (Z'0002') for BASE64 encoding,
ENC_BASE32K (Z'0004') for X-BASE32K encoding, ENC_QP (Z'0008') for
QUOTED-PRINTABLE encoding, ENC_BASE10 (Z'0010') for BASE10 encoding,
ENC_BASE16 (Z'0020') for BASE16 encoding or ENC_BASE8 (Z'0040') for
BASE8 encoding. At this time FCBlib only supports ENC_NONE BINARY
encoding.
The value returned in SIZE is taken from the MIME header X-Binary-Size
as an INTEGER. It is returned as 0 if not specified.
The value returned in ID is taken from the MIME header X-Binary-ID as an
INTEGER. It is returned as 0 if not specified.
The value returned in DIGEST is taken from the MIME header Content-MD5.
It is returned as a character string. If no digest is given, an empty
string is returned.
The value returned in COMPRESSION is taken from the MIME header
Content-Type in the conversions parameter. The reported value is one of
the INTEGER values CBF_CANONICAL (Z'0050'), CBF_PACKED (Z'0060'),
CBF_PACKED_V2 (Z'0090'), CBF_BYTE_OFFSET (Z'0070'), CBF_PREDICTOR
(Z'0080'), CBF_NONE (Z'0040'). Two flags may be combined with CBF_PACKED
or CBF_PACKED_V2: CBF_UNCORRELATED_SECTIONS (Z'0100') or CBF_FLAT_IMAGE
(Z'0200'). At this time FCBlib does not support CBF_PREDICTOR or
CBF_NONE compression.
The values returned in BITS, VORZEICHEN and REELL are the parameters of
the data types of the elements. These values are taken from the MIME
header X-Binary-Element-Type, which has values of the form "signed
BITS-bit integer", "unsigned BITS-bit integer", "signed BITS-bit real
IEEE" or "signed BITS-bit complex IEEE". If no value is given, REELL is
reported as -1. If the value in one of the integer types, REELL is
reported as 0. If the value is one of the real or complex types, REELL
is reported as 1. In the current release of FCBlib only the integer
types for BITS equal to 16 or 32 are supported.
The value returned in BYTEORDER is the byte order of the data in the
image file as reported in the MIME header. The value, if specified, will
be either the character string "LITTLE_ENDIAN" or the character string
"BIG_ENDIAN". If no byte order is specified, "LITTLE_ENDIAN" is
reported. This value is taken from the MIME header
X-Binary-Element-Byte-Order. As of this writing, CBFlib will not
generate "BIG_ENDIAN" byte-order files. However, both CBFlib and FCBlib
read "LITTLE_ENDIAN" byte-order files, even on big-endian machines.
The value returned in DIMOVER is the overall number of elements in the
image array, if specified, or zero, if not specified. This value is
taken from the MIME header X-Binary-Number-of-Elements. The values
returned in DIM1, DIM2 and DIM3 are the sizes of the fastest changing,
second fastest changing and third fastest changing dimensions of the
array, if specified, or zero, if not specified. These values are taken
from the MIME header X-Binary-Size-Fastest-Dimension,
X-Binary-Size-Second-Dimension and X-Binary-Size-Third-Dimension
respectively.
The value returned in PADDING is the size of the post-data padding, if
any, if specified or zero, if not specified. The value is given as a
count of octets. This value is taken from the MIME header
X-Binary-Size-Padding.
ARGUMENTS
TAPIN The INTEGER Fortran device unit number assigned to
image file.
LAST_CHAR The last character (as an INTEGER(1) byte) read.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN
ENCODING INTEGER type of encoding for the binary section as
reported in the MIME header.
ID INTEGER binary identifier as reported in the MIME
header.
SIZE INTEGER size of compressed binary section as
reported in the MIME header.
DIGEST The MD5 message digest as reported in the MIME
header.
COMPRESSION INTEGER compression method as reported in the MIME
header.
BITS INTEGER number of bits in each element as reported
in the MIME header.
VORZEICHEN INTEGER flag for signed or unsigned elements as
reported in the MIME header. Set to 1 if the elements
can be read as signed values, 0 otherwise.
REELL INTEGER flag for real elements as reported in the
MIME header. Set to 1 if the elements can be read as
REAL
BYTEORDER The byte order as reported in the MIME header.
DIM1 Pointer to the destination fastest dimension.
DIM2 Pointer to the destination second fastest
dimension.
DIM3 Pointer to the destination third fastest dimension.
PADDING Pointer to the destination padding size.
RETURN VALUE
Returns 0 if the function is successful. SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.9 FCB_READ_BYTE
2.5.11 FCB_READ_LINE
----------------------------------------------------------------------
2.5.6 FCB_OPEN_CIFIN
INTERFACE
INTEGER FUNCTION FCB_OPEN_CIFIN(FILNAM,TAPIN,LAST_CHAR, &
FCB_BYTES_IN_REC,BYTE_IN_FILE,REC_IN_FILE,BUFFER)
CHARACTER(len=*),INTENT(IN) :: FILNAM
INTEGER, INTENT(IN) :: TAPIN,FCB_BYTES_IN_REC
INTEGER(1), INTENT(OUT):: LAST_CHAR
INTEGER, INTENT(OUT):: BYTE_IN_FILE,REC_IN_FILE
INTEGER(1), INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
INTEGER FCB_RECORD_SIZE
END FUNCTION
END INTERFACE
The function FCB_OPEN_CIFIN opens the CBF image file given by the file
name in the character string FILNAM on the logical unit TAPIN. The
calling routine must provide an INTEGER(1) byte buffer BUFFER of some
appropriate INTEGER size FCB_BYTES_IN_REC. The size must be chosen to
suit the machine, but in most cases, 4096 will work. The values returned
in LAST_CHAR, BYTE_IN_FILE, and REC_IN_FILE are for use in subsequent
FCBlib I/O routines.
The image file will be checked for the initial characters "###CBF: ". If
there is no match the error value CBF_FILEREAD is returned.
ARGUMENTS
FILNAM The character string name of the image file to be
opened.
TAPIN The INTEGER Fortran device unit number assigned to
image file.
LAST_CHAR The last character (as an INTEGER(1) byte) read.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN
RETURN VALUE
Returns 0 if the function is successful. SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.5 FCB_NEXT_BINARY
2.5.9 FCB_READ_BYTE
2.5.11 FCB_READ_LINE
----------------------------------------------------------------------
2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4,
FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4
INTERFACE
INTEGER FUNCTION FCB_DECOMPRESS_PACKED_I2 (ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, &
TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(2), INTENT(OUT):: ARRAY(DIM1,DIM2)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN, COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
INTERFACE
INTEGER FUNCTION FCB_DECOMPRESS_PACKED_I4 (ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, &
TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(4), INTENT(OUT):: ARRAY(DIM1,DIM2)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN, COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
INTERFACE
INTEGER FUNCTION FCB_DECOMPRESS_PACKED_3D_I2 (ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, DIM3, &
TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(2), INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN, COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2,DIM3
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
INTERFACE
INTEGER FUNCTION FCB_DECOMPRESS_PACKED_3D_I4 (ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, DIM3, &
TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(4), INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN, COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2,DIM3
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
The functions FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4,
FCB_DECOMPRESS_PACKED_3D_I2 and FCB_DECOMPRESS_PACKED_3D_I4, decompress
images compress according the the CBF_PACKED or CBF_PACKED_V2
compression described in section 3.3.2 on J. P. Abrahams CCP4 packed
compression.
The relevant function should be called immediately after a call to
FCB_NEXT_BINARY, using the values returned by FCB_NEXT_BINARY to select
the appropriate version of the function.
ARGUMENTS
ARRAY The array to receive the image
NELEM The INTEGER(8) number of elements to be read
NELEM_READ The INTEGER(8) returned value of the number of
elements actually read
ELSIGN The INTEGER value of the flag for signed (1) OR
unsigned (0) data
COMPRESSION The compression of the image
DIM1 The INTEGER(8) value of the fastest dimension of
ARRAY
DIM2 The INTEGER(8) value of the second fastest
dimension
DIM3 The INTEGER(8) value of the third fastest dimension
TAPIN The INTEGER Fortran device unit number assigned to
image file.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN
RETURN VALUE
Returns 0 if the function is successful.
SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.5 FCB_NEXT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.9 FCB_READ_BYTE
2.5.11 FCB_READ_LINE
----------------------------------------------------------------------
2.5.8 FCB_READ_BITS
INTERFACE
INTEGER FUNCTION FCB_READ_BITS(TAPIN,FCB_BYTES_IN_REC,BUFFER, &
REC_IN_FILE,BYTE_IN_FILE,BCOUNT,BBYTE, &
BITCOUNT,IINT,LINT)
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
INTEGER, INTENT(INOUT):: BCOUNT
INTEGER(1),INTENT(INOUT):: BBYTE
INTEGER, INTENT(IN):: BITCOUNT
INTEGER, INTENT(IN):: LINT
INTEGER(4), INTENT(OUT):: IINT(LINT)
END FUNCTION
END INTERFACE
The function FCB_READ_BITS gets the integer value starting at
BYTE_IN_FILE from file TAPIN continuing through BITCOUNT bits, with sign
extension. BYTE_IN_FILE is left at the entry value and not incremented.
The resulting, sign-extended integer value is stored in the INTEGER(4)
array IINT of dimension LINT with the least significant portion in
IINT(1).
ARGUMENTS
TAPIN The INTEGER Fortran device unit number assigned to
image file.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
BCOUNT The INTEGER count of bits remaining unused from the
last call to FCB_READ_BITS.
BBYTE The INTEGER(1) byte containing the unused bits from
the last call to FCB_READ_BITS.
BITCOUNT The INTEGER count of the number of bits to be
extracted from the image file.
IINT The INTEGER(4) array into which to store the value
extracted from the image file.
LINT The INTEGER length of the array IINT.
RETURN VALUE
Returns 0 if the function is successful. Because of the use of direct
access I/O in blocks of size FCB_BYTES_IN_REC the precise location of
the end of file may not be detected.
SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.5 FCB_NEXT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.9 FCB_READ_BYTE
2.5.11 FCB_READ_LINE
----------------------------------------------------------------------
2.5.9 FCB_READ_BYTE
INTERFACE
INTEGER FUNCTION FCB_READ_BYTE(TAPIN,FCB_BYTES_IN_REC,BUFFER, &
REC_IN_FILE,BYTE_IN_FILE,IBYTE)
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
INTEGER(1), INTENT(OUT):: IBYTE
END FUNCTION
END INTERFACE
The function FCB_READ_BYTE reads the byte at the position BYTE_IN_FILE
in the image file TAPIN. The first byte in the file is at BYTE_IN_FILE =
1. BYTE_IN_FILE should be set to the desired value before the call to
the function and is not incremented within the function.
The function attempts to suppress the error caused by a read of a short
last record, and in most systems cannot determine the exact location of
the end of the image file, returning zero bytes until the equivalent of
a full final record has been read.
ARGUMENTS
TAPIN The INTEGER Fortran device unit number assigned to
image file.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
IBYTE The INTEGER(1) byte found in the image file at the
byte position BYTE_IN_FILE.
RETURN VALUE
Returns 0 if the function is successful. Because of the use of direct
access I/O in blocks of size FCB_BYTES_IN_REC the precise location of
the end of file may not be detected.
SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.5 FCB_NEXT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.9 FCB_READ_BITS
2.5.11 FCB_READ_LINE
----------------------------------------------------------------------
2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4, FCB_READ_IMAGE_3D_I2,
FCB_READ_IMAGE_3D_I4
INTERFACE
INTEGER FUNCTION FCB_READ_IMAGE_I2(ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, &
PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(2), INTENT(OUT):: ARRAY(DIM1,DIM2)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN
INTEGER, INTENT(OUT):: COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2
INTEGER(8), INTENT(OUT):: PADDING
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
INTERFACE
INTEGER FUNCTION FCB_READ_IMAGE_I4(ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, &
PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(4), INTENT(OUT):: ARRAY(DIM1,DIM2)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN
INTEGER, INTENT(OUT):: COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2
INTEGER(8), INTENT(OUT):: PADDING
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
INTERFACE
INTEGER FUNCTION FCB_READ_IMAGE_3D_I2(ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, DIM3, &
PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(2), INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN
INTEGER, INTENT(OUT):: COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2,DIM3
INTEGER(8), INTENT(OUT):: PADDING
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
INTERFACE
INTEGER FUNCTION FCB_READ_IMAGE_3D_I4(ARRAY,NELEM,NELEM_READ, &
ELSIGN, COMPRESSION, DIM1, DIM2, DIM3, &
PADDING,TAPIN,FCB_BYTES_IN_REC,BYTE_IN_FILE, &
REC_IN_FILE,BUFFER)
INTEGER(4), INTENT(OUT):: ARRAY(DIM1,DIM2,DIM3)
INTEGER(8), INTENT(OUT):: NELEM_READ
INTEGER(8), INTENT(IN):: NELEM
INTEGER, INTENT(IN):: ELSIGN
INTEGER, INTENT(OUT):: COMPRESSION
INTEGER(8), INTENT(IN):: DIM1,DIM2,DIM3
INTEGER(8), INTENT(OUT):: PADDING
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC
INTEGER, INTENT(INOUT):: REC_IN_FILE,BYTE_IN_FILE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC)
END FUNCTION
END INTERFACE
The function FCB_READ_IMAGE_I2 reads a 16-bit twos complement INTEGER(2)
2D image. The function FCB_READ_IMAGE_I4 read a 32-bit twos complement
INTEGER(4) 2D image. The function FCB_READ_IMAGE_3D_I2 reads a 16-bit
twos complement INTEGER(2) 3D image. The function FCB_READ_IMAGE_3D_I4
reads a 32-bit twos complement INTEGER(4) 3D image. In each case the
image is compressed either by a BYTE_OFFSET algorithm by W. Kabsch based
on a proposal by A. Hammersley or by a PACKED algorithm by J. P.
Abrahams as used in CCP4, with modifications by P. Ellis and H. J.
Bernstein.
The relevant function automatically first calls FCB_NEXT_BINARY to skip
to the next binary section and then starts to read. An error return will
result if the parameters of this call are inconsistent with the values
in MIME header.
ARGUMENTS
ARRAY The array to receive the image
NELEM The INTEGER(8) number of elements to be read
NELEM_READ The INTEGER(8) returned value of the number of
elements actually read
ELSIGN The INTEGER value of the flag for signed (1) OR
unsigned (0) data
COMPRESSION The actual compression of the image
DIM1 The INTEGER(8) value of the fastest dimension of
ARRAY
DIM2 The INTEGER(8) value of the second fastest
dimension
DIM3 The INTEGER(8) value of the third fastest dimension
TAPIN The INTEGER Fortran device unit number assigned to
image file.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN
RETURN VALUE
Returns 0 if the function is successful.
SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.5 FCB_NEXT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.7 FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2,
FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
FCB_DECOMPRESS_PACKED_3D_I4
2.5.9 FCB_READ_BYTE
2.5.11 FCB_READ_LINE
----------------------------------------------------------------------
2.5.11 FCB_READ_LINE
INTERFACE
INTEGER FUNCTION FCB_READ_LINE(TAPIN,LAST_CHAR,FCB_BYTES_IN_REC, &
BYTE_IN_FILE,REC_IN_FILE,BUFFER,LINE,N,LINELEN)
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC,N
INTEGER, INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE
INTEGER, INTENT(OUT):: LINELEN
INTEGER(1),INTENT(INOUT):: LAST_CHAR,BUFFER,(FCB_BYTES_IN_REC)
INTEGER(1), INTENT(OUT):: LINE(N)
END FUNCTION
END INTERFACE
The function FCB_READ_LINE reads successive bytes into the INTEGER(1)
byte array LINE of dimension N), stopping at N bytes or the first error
or the first CR (Z'0D') or LF (Z'0A'), whichever comes first. It
discards an LF after a CR. The variable LAST_CHAR is checked for the
last character from the previous line to make this determination.
The actual number of bytes read into the line, not including any
terminal CR or LF is stored in LINELEN.
ARGUMENTS
TAPIN The INTEGER Fortran device unit number assigned to
image file.
LAST_CHAR The INTEGER(1) byte holding the ASCII value of the
last character read for each line read.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN.
LINE The INTEGER(1) array of length N to hold the line
to be read from TAPIN.
N The INTEGER dimension of LINE.
LINELEN The INTEGER number of characters read into LINE.
RETURN VALUE
Returns 0 if the function is successful.
SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.5 FCB_NEXT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.7 FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2,
FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
FCB_DECOMPRESS_PACKED_3D_I4
2.5.9 FCB_READ_BYTE
2.5.12 FCB_READ_XDS_I2
INTERFACE
INTEGER FUNCTION FCB_READ_XDS_I2(FILNAM,TAPIN,NX,NY,IFRAME,JFRAME)
CHARACTER(len=*),INTENT(IN) :: FILNAM
INTEGER, INTENT(IN) :: TAPIN,NX,NY
INTEGER(2), INTENT(OUT):: IFRAME(NX*NY)
INTEGER(4), INTENT(OUT):: JFRAME(NX,NY)
END FUNCTION
END INTERFACE
The function FCB_READ_XDS_I2 read a 32-bit integer twos complement image
into a 16-bit INTEGER(2) XDS image using the CBF_BYTE_OFFSET, CBF_PACKED
or CBF_PACKED_V2 compressions for the 32-bit data. The BYTE_OFFSET
algorithm is a variant of the September 2006 version by W. Kabsch which
was based on a suggestion by A. Hammersley and which was further
modified by H. Bernstein.
The file named FILNAM is opened on the logical unit TAPIN and
FCB_NEXT_BINARY is used to skip to the next binary image. The binary
image is then decompressed to produce an XDS 16-bit integer image array
IFRAME which is NX by NY. The dimensions must agree with the dimensions
specified in MIME header.
The conversion from a 32-bit integer I32 to 16-bit XDS pixel I16 is done
as per W. Kabsch as follows: The value I32 is limited to the range -1023
=< I32 =< 1048576. If I32 is outside that range it is truncated to the
closer boundary. The generate I16, the 16-bit result, if I32 > 32767, it
is divided by 32 (producing a number between 1024 and 32768), and then
negated (producing a number between -1024 and -32768).
For CBF_BYTE_OFFSET this conversion can be done on the fly directly into
the target array IFRAME, but for the CBF_PACKED or CBF_PACKED_V2, the
full 32 bit precision is needed during the decompression, forcing the
use of an intermediate INTEGER(4) array JFRAME to hold the 32-bit image
in that case.
The image file is closed after reading one image.
ARGUMENTS
FILNAM The character string name of the image file to be opened.
TAPIN The INTEGER Fortran device unit number assigned to image
file.
NX The INTEGER fast dimension of the image array.
NY The INTEGER slow dimension of the image array.
IFRAME The INTEGER(2) XDS image array.
JFRAME The INTEGER(4) 32-bit image scratch array needed for
CBF_PACKED or CBF_PACKED_V2 images.
RETURN VALUE
Returns 0 if the function is successful, CBF_FORMAT (=1) if it cannot
handle this CBF format (not implemented), -1 if it cannot determine
endian architecture of this machine, -2: if it cannot open the image
file, -3: if it finds the wrong image format and -4 if it cannot read
the image.
----------------------------------------------------------------------
2.5.13 FCB_SKIP_WHITESPACE
INTERFACE
INTEGER FUNCTION FCB_SKIP_WHITESPACE(TAPIN,LAST_CHAR, &
FCB_BYTES_IN_REC,BYTE_IN_FILE,REC_IN_FILE,BUFFER,&
LINE,N,LINELEN,ICUR,FRESH_LINE)
INTEGER, INTENT(IN):: TAPIN,FCB_BYTES_IN_REC,N
INTEGER, INTENT(INOUT):: BYTE_IN_FILE,REC_IN_FILE,LINELEN,ICUR, &
FRESH_LINE
INTEGER(1),INTENT(INOUT):: BUFFER(FCB_BYTES_IN_REC),LINE(N), &
LAST_CHAR
END INTERFACE
The function FCB_SKIP_WHITESPACE skips forward on the current INTEGER(1)
byte array LINE of size N with valid data in LINE(1:LINELEN) from the
current position ICUR moving over MIME header whitespace and comments,
reading new lines into LINE if needed. The flag FRESH_LINE indicates
that a fresh line should be read on entry.
ARGUMENTS
TAPIN The INTEGER Fortran device unit number assigned to
image file.
LAST_CHAR The INTEGER(1) byte holding the ASCII value of the
last character read for each line read.
FCB_BYTES_IN_REC The INTEGER number of bytes in a record.
BYTE_IN_FILE The INTEGER byte (counting from 1) of the byte to
read.
REC_IN_FILE The INTEGER record number (counting from 1) of next
record to read.
BUFFER The INTEGER(1) array of length FCB_BYTES_IN_REC to
hold the appropriate record from TAPIN.
LINE The INTEGER(1) array of length N to hold the line
to be read from TAPIN.
N The INTEGER dimension of LINE.
LINELEN The INTEGER number of characters read into LINE.
ICUR The INTEGER position within the line.
FRESH_LINE The INTEGER flag that a fresh line is needed.
RETURN VALUE
Returns 0 if the function is successful.
SEE ALSO
2.5.3 FCB_EXIT_BINARY
2.5.5 FCB_NEXT_BINARY
2.5.6 FCB_OPEN_CIFIN
2.5.7 FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2,
FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
FCB_DECOMPRESS_PACKED_3D_I4
2.5.9 FCB_READ_BYTE
----------------------------------------------------------------------
2.6 HDF5 abstraction layer and convenience functions
The HDF5 abstraction layer mostly follows the HDF5 naming convention of
H5Xfunction_name, where X is usually a single letter identifying the
section of the API that the function resides in. A cbf_ prefix is used
on all functions to avoid naming conflicts and make it clear that all
these functions use the CBFlib error handling method whenever an error
may occur.
The main purpose of this API is to not to reimplement the HDF5 API, but
to make common HDF5-related tasks easier when working with HDF5 files
within CBFlib. The API therefore doesn't attempt to cover every possible
use of HDF5, but to simplify common tasks. Use of the HDF5 API is not
unexpected in library or user code, but functions in this section should
be preferred in order to reduce development time and the amount of
debugging required. A relatively comprehensive test program is provided,
this should be used to verify that the functions in this section of the
API are performing as expected and can be used as a source of example
code.
This section describes functions available for working with:
* Attributes:
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
* Datasets:
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
* Files:
* 2.6.21 cbf_H5Fopen
* 2.6.22 cbf_H5Fclose
* Groups:
* 2.6.23 cbf_H5Gcreate
* 2.6.24 cbf_H5Gfind
* 2.6.25 cbf_H5Grequire
* 2.6.26 cbf_H5Gfree
* Identifiers:
* 2.6.27 cbf_H5Ivalid
* Objects:
* 2.6.28 cbf_H5Ocmp
* 2.6.29 cbf_H5Ofree
* Dataspaces:
* 2.6.30 cbf_H5Screate
* 2.6.31 cbf_H5Sfree
* Datatypes:
* 2.6.32 cbf_H5Tcreate_string
* 2.6.33 cbf_H5Tfree
Rank of a dataset
Where a rank is required it must be equal to the length of the dim, max
& chunk parameters, if they are given, and should be:
* 0, for scalar data
* 1, for vector data
* 2, for matrix data
* 3, for volume data
* etc...
The maximum rank is defined by the HDF5 library, a negative rank makes
no sense and will often be treated as an error.
HDF5-specific datatypes
Any type parameters defining types for data stored in a file should
usually be a value returned by cbf_H5Tcreate_string or one of the
standard or IEEE types:
H5T_STD_I8LE H5T_STD_I16LE H5T_STD_I32LE H5T_STD_I64LE
H5T_STD_U8LE H5T_STD_U16LE H5T_STD_U32LE H5T_STD_U64LE
H5T_STD_I8BE H5T_STD_I16BE H5T_STD_I32BE H5T_STD_I64BE
H5T_STD_U8BE H5T_STD_U16BE H5T_STD_U32BE H5T_STD_U64BE
H5T_IEEE_F32LE H5T_IEEE_F64LE H5T_IEEE_F32BE H5T_IEEE_F64BE
Any type parameters defining types for data stored in memory should
usually be a value returned by cbf_H5Tcreate_string or one of the native
types:
H5T_NATIVE_SCHAR H5T_NATIVE_SHORT H5T_NATIVE_INT H5T_NATIVE_LONG H5T_NATIVE_LLONG
H5T_NATIVE_UCHAR H5T_NATIVE_USHORT H5T_NATIVE_UINT H5T_NATIVE_ULONG H5T_NATIVE_ULLONG
H5T_NATIVE_FLOAT H5T_NATIVE_DOUBLE H5T_NATIVE_LDOUBLE
Functions are rarely (if ever) limited to the above values, and can take
any valid HDF5 datatype. The above is not a complete list of all
available types, check the HDF5 documentation for such a list if you
need one.
Comparing data
Some of the functions in this section will require a comparison function
and some comparison parameters to be provided. The function should
return zero if the data in the two arrays are considered equal and
non-zero otherwise, note that this is the same as C's strcmp(). The
signature of the comparison functions used here is:
int compare (const void * expected, const void * existing, size_t
length, const void * params)
This will be called with:
Type Name Description
const void * expected A pointer to the array of requested values that
was passed to the function.
const void * existing An array of existing values read from the object.
size_t length The length of the expected and existing arrays.
const void * params A pointer to the comparison parameters which were
passed to the calling function.
The comparison parameters allow more complex comparisons to be
performed, such as a check that the numbers are 'close enough' as
determined by some variable measure of closeness. It is the caller's
responsibility to ensure that the comparison function is appropriate for
the type of data expected and that params is of the appropriate type for
the comparison function. The parameters expected and existing should
normally be cast to the appropriate type before being used.
An example function for comparing ints, taken from the implementation of
CBFlib:
/*
Compare two arrays of ints.
Most parameters are defined as being 'const' even though
the expected signature allows them to be mutable.
*/
int cmp_int
(const void * const expected,
const void * const existing,
size_t length,
const void * const params)
{
/*
Cast the array pointers to the appropriate type, preserving the const-ness of the data.
I won't be using any parameters for this comparison, so just ignore that argument.
*/
const int * A = expected;
const int * B = existing;
/*
Iterate through the arrays comparing each element and decrementing a counter.
If any are not equal the loop will exit early with length being non-zero.
*/
while (length && *A++ == *B++) --length;
/*
Return a value indicating whether the arrays are equal.
*/
return length;
}
Some older functions use a simpler 3-argument comparison function, which
doesn't have a parameter that can be used to pass some extra information
to or retrieve information from the function.
----------------------------------------------------------------------
2.6.1 cbf_H5Acreate
Create a new attribute.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Acreate (const hid_t location, hid_t *const attr, const char
*const name, const hid_t type, const hid_t space)
DESCRIPTION
Creates a new attribute of the object location with name given by name,
optionally returning it in the attr variable. An error will occur if a
similarly named attribute already exists.
ARGUMENTS
location The hdf5 group/file in which to put the attribute.
A pointer to a HDF5 object identifier that is set to the
attr location of a valid object if the function succeeds, otherwise
is left untouched.
name The name of the existing/new dataset.
type The type of data to be stored in the attribute.
space The dataspace of the attribute.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.2 cbf_H5Afind
Try to locate an existing attribute.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Afind (const hid_t location, hid_t *const attr, const char
*const name, const hid_t type, const hid_t space)
DESCRIPTION
Checks for the existance of an attribute with the given name at location
with a datatype of type and dataspace of space. Will return CBF_NOTFOUND
if it cannot be found, or open it if it already exists.
If type is not a datatype then no check of the attribute datatype will
be done. If space is not a dataspace then no checks of the attribute
dataspace wil be done.
ARGUMENTS
location The hdf5 group/file in which to put the attribute.
A pointer to a HDF5 object identifier that is set to the
attr location of a valid object if the function succeeds, otherwise
is left untouched.
name The name of the existing/new attribute.
type The type of data stored in the attribute, or an invalid
identifier if it should not be checked.
space The dataspace of the attribute, or an invalid identifier if it
should not be checked.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.3 cbf_H5Aread
Read an entire attribute from a file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Aread (const hid_t attr, const hid_t type, void *const buf)
DESCRIPTION
Reads all of the data from attr into buf, which should have been
allocated as the native type indicated by mem_type.
ARGUMENTS
attr A valid hdf5 handle for an attribute.
type The type of data in memory.
buf The location where the data is to be stored.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.4 cbf_H5Aread_string
Read an entire string attribute from a file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Aread_string (const hid_t attr, const char **const val)
DESCRIPTION
Read a string attribute into memory, returning a pointer that must be
free'd by the caller in val.
ARGUMENTS
attr The attribute to read from.
val A pointer to a place the string may be stored.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.5 cbf_H5Awrite
Write an entire attribute to a file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Awrite (const hid_t attr, const hid_t type, void *const buf)
DESCRIPTION
Writes all of the data from buf, which should contain data if the type
indicated by mem_type, into attr.
ARGUMENTS
attr A valid hdf5 handle for an attribute.
type The type of data in memory.
buf The address of the data to be written.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.6 cbf_H5Arequire_cmp2
Check for an attribute with the given space/type/value, or set one if it
doesn't exist.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Arequire_cmp2 (const hid_t ID, const char * const name, const
int rank, const hsize_t * const dim, const hid_t fileType, const hid_t
memType, const void *const value, void *const buf, int(*cmp)(const void
*, const void *, size_t))
DESCRIPTION
Checks the existance of an attribute of the given name, size, type and
value. Equal value is determined by a custom comparison function which
may use some extra data for more sophisticated tests. A new attribute
with the given properties will be created if none currently exist, the
function will fail if an incompatible attribute exists.
ARGUMENTS
ID The HDF5 object that the attribute will be applied to.
name The name of the attribute.
rank The number of dimensions of the attribute data, 0 for scalar
data.
dim The length of each dimension, not used for scalar data.
fileType The HDF5 type of the attribute data in the file.
memType The HDF5 type of the attribute data in memory.
value The data to be written to the attribute.
buf A buffer to be used when reading an existing attribute of the
same size.
cmp A comparison function to test if a previously set value is
equal to the value I asked for.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.7 cbf_H5Arequire_cmp2_ULP
Check for an attribute with the given space/type/value, or set one if it
doesn't exist.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Arequire_cmp2_ULP (const hid_t ID, const char *const name,
const int rank, const hsize_t * const dim, const hid_t fileType, const
hid_t memType, const void *const value, void *const buf, int(*cmp)(const
void *, const void *, size_t, const void *), const void *const
cmp_params)
DESCRIPTION
Checks the existance of an attribute of the given name, size, type and
value. Equal value is determined by a custom comparison function which
may use some extra data for more sophisticated tests. A new attribute
with the given properties will be created if none currently exist, the
function will fail if an incompatible attribute exists.
ARGUMENTS
ID The HDF5 object that the attribute will be applied to.
name The name of the attribute.
rank The number of dimensions of the attribute data, 0 for scalar
data.
dim The length of each dimension, not used for scalar data.
fileType The HDF5 type of the attribute data in the file.
memType The HDF5 type of the attribute data in memory.
value The data to be written to the attribute.
buf A buffer to be used when reading an existing attribute of the
same size.
cmp A comparison function to test if a previously set value is
equal to the value I asked for.
cmp_params A pointer to a data structure which may be used by the
comparison function.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.8 cbf_H5Arequire_string
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.8 cbf_H5Arequire_string
Check for a scalar string attribute with a given value, or set one if it
doesn't exist.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Arequire_string (const hid_t location, const char *const name,
const char *const value)
DESCRIPTION
Forwarding function that calls cbf_H5Arequire_cmp2_ULP with the
appropriate arguments to compare two strings. The strcmp function is
used for string comparison, with a small wrapper to verify array length:
/** a possible implementation of a function to compare two strings for equality */
static int cmp_string
(const void * const a,
const void * const b,
const size_t N,
const void * const params)
{
/* first ensure the arrays have one element each */
if (1 != N) return 1;
/* then forward to 'strcmp' for the actual comparison */
else return strcmp(a,b);
}
ARGUMENTS
location HDF5 object to which the string attribute should/will belong.
name The name of the attribute.
value The value which the attribute should/will have.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.9 cbf_H5Afree
----------------------------------------------------------------------
2.6.9 cbf_H5Afree
Close a HDF5 attribute.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Afree (const hid_t ID)
DESCRIPTION
Attempt to close an attribute, but don't modify the identifier that
described it.
ARGUMENTS
ID The HDF5 attribute to be closed.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.1 cbf_H5Acreate
* 2.6.2 cbf_H5Afind
* 2.6.3 cbf_H5Aread
* 2.6.4 cbf_H5Aread_string
* 2.6.5 cbf_H5Awrite
* 2.6.6 cbf_H5Arequire_cmp2
* 2.6.7 cbf_H5Arequire_cmp2_ULP
* 2.6.8 cbf_H5Arequire_string
----------------------------------------------------------------------
2.6.10 cbf_H5Dcreate
Creates a new dataset in the given location.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Dcreate (const hid_t location, hid_t * const dataset, const
char * const name, const int rank, const hsize_t * const dim, const
hsize_t * const max, const hsize_t * const chunk, const hid_t type)
DESCRIPTION
The dataset parameter gives a location to store the dataset for use by
the caller, for example to add an attribute to it. If non-zero the
returned handle MUST be free'd by the caller with cbf_H5Dfree.
The dimensions of the dataset to create are given in dim. The maximum
extents of the dataset are given in max, which uses the values in dim as
defaults if set to a null pointer. Each element of max must be at least
as large as the corresponding element of dim. The dataset created will
be a fixed-size dataset unless one of the elements of max is set to
H5S_UNLIMITED.
A chunk size must be given in the chunk argument if any element of max
is set to H5S_UNLIMITED or is greater than the corresponding element of
dim. If the dataset should not be chunked then a null pointer should be
given.
The dim, max and chunk arrays - if given - must each contain rank
elements.
This function will fail if a link with the same name already exists in
location.
ARGUMENTS
location The hdf5 group/file in which to put the dataset.
dataset An optional pointer to a location where the dataset handle
should be stored.
name The name of the new dataset.
rank The rank of the data.
dim The dimensions of the dataset to create. Unused if rank == 0.
max The maximum size of each dimension. Unused if rank == 0.
chunk The chunk size for the dataset.
type The type of each data element in the file.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.11 cbf_H5Dfind2
Look for a dataset with the given properties.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Dfind2 (const hid_t location, hid_t *const dataset, const char
*const name, const int rank, const hsize_t *const max, hsize_t *const
buf, const hid_t type)
DESCRIPTION
Returns CBF_NOTFOUND without modifying dataset if no dataset exists and
fails without modifying dataset if one with different properties exists.
A dataset will be 'found' if it has the same name and a maximum size
which is at least as big as the size requested in max.
A buffer of rank elements pointed to by buf may be used to store the
array of maximum extents for a potentially matching dataset, in order to
avoid the use of malloc & free for very small amounts of memory.
Use as:
/* Get the return code from the function call, */
const int found = cbf_H5Dfind(location, &dataset, ...);
/* and check what it was: */
if (CBF_SUCCESS==found) {
/* A dataset already existed and I have a handle for it: */
use_existing_dataset(dataset);
} else if (CBF_NOTFOUND==found) {
/* No matching dataset existed, so I can create one: */
cbf_H5Dcreate(location, &dataset, ...);
use_new_datset(dataset);
} else {
/*
The function call failed, do something with the error.
In this case, store it for later use and print a message.
*/
error |= found;
cbf_debug_print(cbf_strerror(error));
}
/* clean up: */
cbf_H5Dfree(dataset);
ARGUMENTS
location The hdf5 group/file in which to put the dataset.
A pointer to a HDF5 object identifier that is set to the
dataset location of a valid object if the function succeeds, otherwise
is left in an undefined state.
name The name of the existing/new dataset.
rank The rank of the data, must be equal to the length of the max
and buf arrays, if they are given.
The (optional) maximum size of each dimension, pointer or an
max array of length rank where 0 <= max[i] <= H5S_UNLIMITED for i =
[0, rank), unused if rank == 0.
An optional buffer with rank elements which may be used to
buf store the current maximum dimensions of a potential match to
avoid a malloc/free call.
type The type of each data element in the file. If an invalid type
is given a dataset of any type may be returned.
RETURN VALUE
CBF_SUCCESS if a matching dataset was found, CBF_NOTFOUND if nothing
with the same name was found, some other error code otherwise.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.12 cbf_H5Drequire
Ensure that a dataset exists, returning a handle to an existing dataset
or creating a new dataset if needed.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Drequire (const hid_t location, hid_t * const dataset, const
char * const name, const int rank, const hsize_t * const max, const
hsize_t * const chunk, hsize_t * const buf, const hid_t type)
DESCRIPTION
Ensure a dataset of the given rank exists and can hold at least as many
elements as specified in max. If no dataset exists then one will be
created with dimensions of [0, 0, ... 0]. cbf_H5Dfind and cbf_H5Dcreate
are used in the implementation of this function.
An existing dataset may be found using cbf_H5Dfind2(location, dataset,
name, rank, max, buf, type). If no dataset can be found then a dataset
will be created by setting each element of a buffer of length rank to
zero and using cbf_H5Dcreate(location, dataset, name, rank, buffer, max,
chunk, type). A buffer of rank elements may be provided to avoid using
malloc to allocate memory for a small array whose size may already be
known.
The value pointed to by dataset should be a valid object identifier if
the function exits successfully, and will be left in an undefined state
otherwise.
This is roughly equivalent to:
const int error = cbf_H5Dfind2(location, dataset, name, rank, max, buf, type);
if (CBF_NOTFOUND==error) {
int i;
for (i = 0; i != rank; ++i) buf[i] = 0;
return cbf_H5Dcreate(location, dataset, name, rank, buf, max, chunk, type);
} else {
/* 'error' may be 'CBF_SUCCESS' or could indicate an error: */
return error;
}
but contains more sophisticated error handling code and allows for some
parameters to be omitted.
ARGUMENTS
location The hdf5 group/file in which to put the dataset.
dataset A pointer to a location to store the dataset.
name The name of the existing/new dataset.
rank The rank of the data.
max The (optional) maximum size of each dimension.
chunk The chunk size used if creating a new dataset.
buf An optional buffer with rank elements.
type The type of each data element in the file.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.13 cbf_H5Dinsert
Add some data to a datset, expanding the dataset to the appropriate size
if needed.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Dinsert (const hid_t dataset, const hsize_t * const offset,
const hsize_t *const stride, const hsize_t *const count, hsize_t *const
buf, const void *const value, const hid_t type)
DESCRIPTION
Insert a slice of data into dataset with the appropriate offset &
stride, ensuring that no existing data is lost due to resizing the
dataset but not checking that previous data isn't being overwritten.
The offset, stride, count and buf arrays must each have rank elements.
If stride is set to the null pointer then a default of [1, 1, 1, ..., 1]
will be used. An optional buffer may be provided in buf to avoid using
malloc to allocate a small amount of memory whose size may actually be
known at compile time.
The value array should contain count[0] * count[1] * ... * count[rank-1]
=== product(count) elements of data.
ARGUMENTS
dataset The dataset to write the data to.
offset Where to start writing the data.
stride The number of elements in the dataset to step for each element
to be written.
count The number of elements in each dimension to be written.
buf An optional buffer to avoid using the heap for small amounts of
memory.
value The address of the data to be written.
type The type of data in memory.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.14 cbf_H5Dset_extent
Change the extent of a chunked dataset to the values in dim.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Dset_extent (const hid_t dataset, const hsize_t * const dim)
DESCRIPTION
Forwards to a HDF5 function to change the extent of dataset. The dim
array must have the same number of elements as the rank of the dataset,
but this can't be checked within this function.
ARGUMENTS
dataset A handle for the dataset whose extent is to be changed.
dim The new extent of the dataset, if the function succeeds.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.15 cbf_H5Dwrite2
Add some data to the specified position in the dataset, without checking
what (if anything) was there before.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Dwrite2 (const hid_t dataset, const hsize_t * const offset,
const hsize_t *const stride, const hsize_t *const count, const void
*const value, const hid_t type)
DESCRIPTION
Assumes the dataset has the appropriate size to contain all the data and
overwrites any existing data that may be there. The rank of the dataset
is assumed to be known, and the size of the array parameters is not
tested. When rank is zero - in the case of scalar datasets - the offset,
stride and count parameters are meaningless and should be omitted by
setting them to zero.
ARGUMENTS
dataset The dataset to write the data to.
offset Where to start writing the data, as an array of rank numbers.
The number of elements in the dataset to step for each element
stride to be written, where null is equivalent to a stride of [1, 1, 1,
..., 1], as an array of rank numbers.
count The number of elements in each dimension to be written, as an
array of rank numbers.
value The address of the data to be written.
type The type of data in memory.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.16 cbf_H5Dread2
Extract some existing data from a dataset at a known position with
memtype.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Dread2 (const hid_t dataset, const hsize_t * const offset,
const hsize_t * const stride, const hsize_t * const count, void * const
value, const hid_t type)
DESCRIPTION
Read some data from a given location in the dataset to an existing
location in memory. Does not check the length of the array parameters,
which should all have rank elements or (in some cases) be null. When
rank is zero - in the case of scalar datasets - the offset, stride and
count parameters are meaningless and should be omitted by setting them
to zero.
ARGUMENTS
dataset The dataset to read the data from.
offset Where to start writing the data, as an array of rank numbers.
The number of elements in the dataset to step for each element
stride to be written, where null is equivalent to a stride of [1, 1, 1,
..., 1], as an array of rank numbers.
count The number of elements in each dimension to be written, as an
array of rank numbers.
value The location where the data is to be stored.
type The type of data in memory.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.17 cbf_H5Drequire_scalar_F64LE2
Write a scalar 64-bit floating point number as a dataset with
comparison.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Drequire_scalar_F64LE2 (const hid_t location, hid_t * const
dataset, const char * const name, const double value, int (*cmp)(const
void *, const void *, size_t))
DESCRIPTION
Convenience function using the HDF5 abstraction layer to avoid the need
to consider array-related parameters for a scalar dataset.It ensures
that a scalar 64-bit IEEE floating point dataset exists with the
appropriate name and (for an existing dataset) the correct value as
determined by the comparison function cmp.
ARGUMENTS
location The group containing the new dataset.
dataset An optional pointer to a place to store the new dataset.
name The name of the new dataset.
value The value of the new dataset.
cmp A comparison function to test if a previously set value is
equal to the value I asked for.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
Write a scalar 64-bit floating point number as a dataset with a
user-defined comparison.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Drequire_scalar_F64LE2_ULP (const hid_t location, hid_t *const
dataset, const char *const name, const double value, int(*cmp)(const
void *, const void *, size_t, const void *), const void *const
cmp_params)
DESCRIPTION
Convenience function using the HDF5 abstraction layer to avoid the need
to consider array-related parameters for a scalar dataset. It ensures
that a scalar 64-bit IEEE floating point dataset exists with the
appropriate name and (for an existing dataset) the correct value as
determined by the user-supplied comparison function cmp.
It is implemented using some of the other dataset functions:
* cbf_H5Dfind2
* cbf_H5Dcreate
* cbf_H5Dread2
* cbf_H5Dwrite2
ARGUMENTS
location The group containing the new dataset.
dataset An optional pointer to a place to store the new dataset.
name The name of the new dataset.
value The value of the new dataset.
cmp A comparison function to test if a previously set value is
equal to the value I asked for.
cmp_params Some extra data which may be required by the comparison
function.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.19 cbf_H5Drequire_flstring
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.19 cbf_H5Drequire_flstring
Write a single fixed-length string as a dataset.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Drequire_flstring (const hid_t location, hid_t *const dataset,
const char *const name, const char *const value)
DESCRIPTION
Convenience function using the HDF5 abstraction layer to avoid the need
to consider array-related parameters for a scalar dataset and to
automatically set the string type to the correct size.
ARGUMENTS
location The group containing the new dataset.
dataset An optional pointer to a place to store the new dataset.
name The name of the new dataset.
value The value of the new dataset.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.20 cbf_H5Dfree
----------------------------------------------------------------------
2.6.20 cbf_H5Dfree
Close a HDF5 dataset.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Dfree (const hid_t ID)
DESCRIPTION
Attempt to close a dataset, but don't modify the identifier that
described it.
ARGUMENTS
ID The HDF5 dataset to be closed.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.10 cbf_H5Dcreate
* 2.6.11 cbf_H5Dfind2
* 2.6.12 cbf_H5Drequire
* 2.6.13 cbf_H5Dinsert
* 2.6.14 cbf_H5Dset_extent
* 2.6.15 cbf_H5Dwrite2
* 2.6.16 cbf_H5Dread2
* 2.6.17 cbf_H5Drequire_scalar_F64LE2
* 2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
* 2.6.19 cbf_H5Drequire_flstring
----------------------------------------------------------------------
2.6.21 cbf_H5Fopen
Attempt to open an HDF5 file by file name.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Fopen (hid_t * const file, const char * const name)
DESCRIPTION
Will try to open a file of the given name with suitable values for some
of it's properties to make memory leaks less likely.
Warning: this function will destroy any existing data in the file, do
not pass the name of any file containing data you want to keep.
ARGUMENTS
file A pointer to an HDF5 ID where the newly opened file should be
stored.
name The name of the file to attempt to open.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.22 cbf_H5Fclose
----------------------------------------------------------------------
2.6.22 cbf_H5Fclose
Close a HDF5 file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Fclose (const hid_t ID)
DESCRIPTION
Attempt to close a file, but don't modify the identifier that described
it.
ARGUMENTS
ID The HDF5 file to be closed.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.21 cbf_H5Fopen
----------------------------------------------------------------------
2.6.23 cbf_H5Gcreate
Attempt to create a group.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Gcreate (const hid_t location, hid_t * const group, const char
* const name)
DESCRIPTION
Helper function to attempt to create a HDF5 group identified by name and
return an error code, to make error handling more consistant. This will
fail if a link with the same name already exists in parent.
ARGUMENTS
location The group that will contain the newly created group.
group A pointer to a HDF5 ID type where the group will be stored.
name The name that the group will be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.24 cbf_H5Gfind
* 2.6.25 cbf_H5Grequire
* 2.6.26 cbf_H5Gfree
----------------------------------------------------------------------
2.6.24 cbf_H5Gfind
Check if a group exists.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Gfind (const hid_t location, hid_t *const group, const char
*const name)
DESCRIPTION
Checks for the existance of a group with the given name and parent. Will
return CBF_NOTFOUND if it cannot be found, or open it if it already
exists. An error code will be returned if something other than a group
exists at the specified location.
ARGUMENTS
location The group to be searched.
group A pointer to a HDF5 ID type where the group will be stored.
name The path (ie, name) of the group to be found.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.23 cbf_H5Gcreate
* 2.6.25 cbf_H5Grequire
* 2.6.26 cbf_H5Gfree
----------------------------------------------------------------------
2.6.25 cbf_H5Grequire
Ensure a group exists.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Grequire (const hid_t location, hid_t *const group, const char
*const name)
DESCRIPTION
Checks for the existance of a group with the given name and parent. Will
create the group if it cannot be found, or open it if it already exists.
It is an error if a matching group cannot be found or created. This uses
cbf_H5Gcreate to create any new groups.
ARGUMENTS
location The group that will contain the newly created group.
group A pointer to a HDF5 ID type where the group will be stored.
name The name that the group will be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.23 cbf_H5Gcreate
* 2.6.24 cbf_H5Gfind
* 2.6.26 cbf_H5Gfree
----------------------------------------------------------------------
2.6.26 cbf_H5Gfree
Close a HDF5 group.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Gfree (const hid_t ID)
DESCRIPTION
Attempt to close a group, but don't modify the identifier that described
it.
ARGUMENTS
ID The HDF5 group to be closed.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.23 cbf_H5Gcreate
* 2.6.24 cbf_H5Gfind
* 2.6.25 cbf_H5Grequire
----------------------------------------------------------------------
2.6.27 cbf_H5Ivalid
Check the validity of an object identifier.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Ivalid (const hid_t ID)
DESCRIPTION
Function to check validity of a HDF5 identifier. HDF5's predefined types
are never counted as valid by this function, so it can't be used to test
the validity of a type constant. Types obtained by using H5Tcopy are
safe to test.
ARGUMENTS
ID An HDF5 object identifier.
RETURN VALUE
Non-zero if the type is valid, zero otherwise.
SEE ALSO
* 2.6.28 cbf_H5Ocmp
----------------------------------------------------------------------
2.6.28 cbf_H5Ocmp
A missing HDF5 function.
PROTOTYPE
#include "cbf_hdf5.h"
htri_t cbf_H5Ocmp (const hid_t id0, const hid_t id1)
DESCRIPTION
Compare two HDF5 object ID's for equality. This follows the standard
practice of returning zero if objects should be considered equal, and
the HDF5 practice of returning a negative number if there is an error.
ARGUMENTS
id0 An HDF5 identifier.
id1 An HDF5 identifier.
RETURN VALUE
0 if equal, a positive value if not equal, or a negative value if there
is an error.
SEE ALSO
* 2.6.27 cbf_H5Ivalid
----------------------------------------------------------------------
2.6.29 cbf_H5Ofree
Close a HDF5 object identifier.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Ofree (const hid_t ID)
DESCRIPTION
Attempt to close an object identifier of unknown type, but don't modify
the identifier that described it.
ARGUMENTS
ID The HDF5 object to be closed.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.28 cbf_H5Ocmp
* 2.6.27 cbf_H5Ivalid
----------------------------------------------------------------------
2.6.30 cbf_H5Screate
Create a dataspace with some given values.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Screate (hid_t *const ID, const int rank, const hsize_t *const
dim, const hsize_t *const max)
DESCRIPTION
Helper function which creates a HDF5 dataspace.
Maximum dimensions can be set to infinity by passing H5S_UNLIMITED in
the appropriate slot of the max parameter. If rank is zero then neither
dim nor max are used and a scalar dataspace is created. If rank is
non-zero and dim is a null pointer then ID will not be modified and the
function will fail. If rank is non-zero and max is a null pointer the
maximum length is set to the current length as given by dim.
ARGUMENTS
ID A pointer to a HDF5 identifier that will contain the new dataspace.
rank The number of dimensions of the new dataspace.
dim The current size of each dimension of the dataspace, should be an
array of length rank.
max The maximum size of each dimension, should be an array of length
rank.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.31 cbf_H5Sfree
----------------------------------------------------------------------
2.6.31 cbf_H5Sfree
Close a HDF5 dataspace identifier.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Sfree (const hid_t ID)
DESCRIPTION
Attempt to close a dataspace identifier, but don't modify the identifier
that described it.
ARGUMENTS
ID The HDF5 dataspace to be closed.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.30 cbf_H5Screate
----------------------------------------------------------------------
2.6.32 cbf_H5Tcreate_string
Get a HDF5 string datatype to describe a sting of the specified length.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Tcreate_string (hid_t *const type, const size_t len)
DESCRIPTION
Convenience function to create a string datatype suitable for use when
storing a string of length len, returning it in the identifier pointed
to by type.
ARGUMENTS
type A pointer to a the HDF5 handle of the new datatype, which should be
free'd with cbf_H5Tfree
len The length of the string datatype - should be strlen() or
H5T_VARIABLE
RETURN VALUE
An error code.
SEE ALSO
* 2.6.33 cbf_H5Tfree
----------------------------------------------------------------------
2.6.33 cbf_H5Tfree
Close a HDF5 datatype identifier.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_H5Tfree (const hid_t ID)
DESCRIPTION
Attempt to close a datatype identifier, but don't modify the identifier
that described it.
ARGUMENTS
ID The HDF5 datatype to be closed.
RETURN VALUE
An error code.
SEE ALSO
* 2.6.32 cbf_H5Tcreate_string
----------------------------------------------------------------------
2.7 High-level NeXus-related functions
These functions primarily allow interaction with a cbf_h5handle without
being exposed to its structure or the complexities of using it
correctly. Wherever possible these functions should be used instead of
directly accessing a cbf_h5handle or cbf_config_t in order make code
easier to read, to maintain the integrity of the data structures and to
ensure all resources allocated to these object are correctly cleaned up.
This section describes functions available for working with:
* CBF's HDF5 handles:
* 2.7.1 cbf_h5handle_get_file
* 2.7.2 cbf_h5handle_set_file
* 2.7.3 cbf_h5handle_get_entry
* 2.7.4 cbf_h5handle_set_entry
* 2.7.5 cbf_h5handle_require_entry
* 2.7.6 cbf_h5handle_require_entry_definition
* 2.7.7 cbf_h5handle_get_sample
* 2.7.8 cbf_h5handle_set_sample
* 2.7.9 cbf_h5handle_require_sample
* 2.7.10 cbf_h5handle_get_beam
* 2.7.11 cbf_h5handle_set_beam
* 2.7.12 cbf_h5handle_require_beam
* 2.7.13 cbf_h5handle_get_instrument
* 2.7.14 cbf_h5handle_set_instrument
* 2.7.15 cbf_h5handle_find_instrument
* 2.7.16 cbf_h5handle_require_instrument
* 2.7.17 cbf_h5handle_get_detector
* 2.7.18 cbf_h5handle_set_detector
* 2.7.19 cbf_h5handle_find_detector
* 2.7.20 cbf_h5handle_require_detector
* 2.7.21 cbf_h5handle_get_goniometer
* 2.7.22 cbf_h5handle_set_goniometer
* 2.7.23 cbf_h5handle_require_goniometer
* 2.7.24 cbf_h5handle_get_monochromator
* 2.7.25 cbf_h5handle_set_monochromator
* 2.7.26 cbf_h5handle_require_monochromator
* 2.7.27 cbf_h5handle_get_source
* 2.7.28 cbf_h5handle_set_source
* 2.7.29 cbf_h5handle_require_source
* 2.7.30 cbf_free_h5handle
* 2.7.31 cbf_create_h5handle3
* 2.7.32 cbf_write_cbf_h5file
* 2.7.33 cbf_write_cbf2nx
* 2.7.34 cbf_write_minicbf_h5file
* 2.7.35 cbf_write_nx2cbf
* miniCBF configuration settings:
* 2.7.36 cbf_config_create
* 2.7.37 cbf_config_parse
* 2.7.38 cbf_config_free
* 2.7.39 cbf_config_strerror
Reading miniCBF configuration settings
This example demonstrates how a miniCBF configuration file should be
parsed, what should be checked before the extracted settings are used
and what should be cleaned up by the caller afterwards:
/* Declare some important variables */
int configError = cbf_configError_success;
FILE * configFile = fopen("config.txt","r");
cbf_config_t * const configSettings = cbf_config_create();
/*
Read and check the configuration settings,
writing any error messages to stderr.
*/
configError = cbf_config_parse(configFile,stderr,configSettings);
/* I no longer need to keep the file open */
fclose(configFile);
/* Check if I could read the file successfully */
if (cbf_configError_success != configError) {
fprintf(stderr,"Error parsing configuration file 'config.txt': %s\n",
cbf_config_strerror(configError));
} else {
/* Use the configuration settings here... */
}
/* Clean up the settings to avoid memory leaks */
cbf_config_free(configSettings);
----------------------------------------------------------------------
2.7.1 cbf_h5handle_get_file
Get the current id of the file within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_file (const cbf_h5handle nx, hid_t *const file)
DESCRIPTION
Check the handle for the presence of a file, optionally returning it.
ARGUMENTS
nx A handle to query for the presence of the requested information.
file A place to store the file (if found), or null if the file isn't
wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.2 cbf_h5handle_set_file
----------------------------------------------------------------------
2.7.2 cbf_h5handle_set_file
Set the id of the file within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_file (const cbf_h5handle nx, const hid_t file)
DESCRIPTION
Sets the file id within the handle to the given value. Doesn't check or
modify any attributes in any way.
ARGUMENTS
nx The handle to add information to.
file The file to be set as the current file id.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.1 cbf_h5handle_get_file
----------------------------------------------------------------------
2.7.3 cbf_h5handle_get_entry
Get the current id and name of the entry group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_entry (const cbf_h5handle nx, hid_t *const group,
const char **const name)
DESCRIPTION
Check the handle for the presence of an entry group and its name,
optionally returning any combination of them. The error code
'CBF_NOTFOUND' will be returned if any of the requested items of data
cannot be found.
The handle retains ownership of the returned object and/or string,
neither of them should be free'd by the caller.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.4 cbf_h5handle_set_entry
* 2.7.5 cbf_h5handle_require_entry
----------------------------------------------------------------------
2.7.4 cbf_h5handle_set_entry
Set the id and name of the entry group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_entry (const cbf_h5handle nx, const hid_t group,
const char *const name)
DESCRIPTION
Sets the entry group and name within the handle to the given values.
Doesn't check or modify the NX_class attribute in any way. The handle
will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current entry group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.3 cbf_h5handle_get_entry
* 2.7.5 cbf_h5handle_require_entry
----------------------------------------------------------------------
2.7.5 cbf_h5handle_require_entry
Ensure I have an entry in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_entry (const cbf_h5handle nx, hid_t *const
group, const char *name)
DESCRIPTION
This will check if the entry group within the handle matches any
existing group of the same name within the current file. If they don't
match a new group is opened or created and added to the handle. The
NX_class attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of "entry".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.3 cbf_h5handle_get_entry
* 2.7.4 cbf_h5handle_set_entry
----------------------------------------------------------------------
2.7.6 cbf_h5handle_require_entry_definition
Ensure I have an entry in the hdf5 handle with definition.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_entry_definition (const cbf_h5handle nx, hid_t
*const group, const char *name, const char *definition, const char
*version, const char *URL)
DESCRIPTION
This will check if the entry group and definition within the handle
matches any existing group of the same name within the current file and
has a definition designation that agrees. If the group name doesn't
match a new group is opened or created and added to the handle. If the
definition does not match, it is replaced with the new one. If the
version attribute does not match it is replaced with the new one. If the
URL> attribute does not match it is replace with the new one. The
NX_class attributes are not checked, but if a new entry is created it
will be created with NX_class NXentry.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group ID should be
stored.
name The group name, or null to use the default name of "entry".
definition The definition name, or null to not specify a definition
name.
version The version string, or null to not specify a version string.
URL The URL at which the definition is stored, or null to not
specify a URL
RETURN VALUE
An error code.
SEE ALSO
* 2.7.3 cbf_h5handle_get_entry
* 2.7.4 cbf_h5handle_set_entry
* 2.7.5 cbf_h5handle_require_entry
----------------------------------------------------------------------
2.7.7 cbf_h5handle_get_sample
Get the current id and name of the sample group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_sample (const cbf_h5handle nx, hid_t *const group,
const char **const name)
DESCRIPTION
Check the handle for the presence of an sample group and its name,
optionally returning any combination of them.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.8 cbf_h5handle_set_sample
* 2.7.9 cbf_h5handle_require_sample
----------------------------------------------------------------------
2.7.8 cbf_h5handle_set_sample
Set the id and name of the sample group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_sample (const cbf_h5handle nx, const hid_t group,
const char *const name)
DESCRIPTION
Sets the sample group and name within the handle to the given values.
Doesn't check or modify the NX_class attribute in any way. The handle
will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current sample group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.7 cbf_h5handle_get_sample
* 2.7.9 cbf_h5handle_require_sample
----------------------------------------------------------------------
2.7.9 cbf_h5handle_require_sample
Ensure I have a sample in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_sample (const cbf_h5handle nx, hid_t *const
group, const char *name)
DESCRIPTION
This will check if the sample group within the handle matches any
existing group of the same name within the current file. If they don't
match a new group is opened or created and added to the handle. The
NX_class attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of "sample".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.7 cbf_h5handle_get_sample
* 2.7.8 cbf_h5handle_set_sample
----------------------------------------------------------------------
2.7.10 cbf_h5handle_get_beam
Get the current id and name of the beam group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_beam (const cbf_h5handle nx, hid_t *const group,
const char **const name)
DESCRIPTION
Check the handle for the presence of a beam group and its name,
optionally returning any combination of them. The error code
'CBF_NOTFOUND' will be returned if any of the requested items of data
cannot be found.
The handle retains ownership of the returned object and/or string,
neither of them should be free'd by the caller.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.11 cbf_h5handle_set_beam
* 2.7.12 cbf_h5handle_require_beam
----------------------------------------------------------------------
2.7.11 cbf_h5handle_set_beam
Set the id and name of the beam group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_beam (const cbf_h5handle nx, const hid_t group,
const char *const name)
DESCRIPTION
Sets the beam group and name within the handle to the given values.
Doesn't check or modify the NX_class attribute in any way. The handle
will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current beam group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.10 cbf_h5handle_get_beam
* 2.7.12 cbf_h5handle_require_beam
----------------------------------------------------------------------
2.7.12 cbf_h5handle_require_beam
Ensure I have a beam in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_beam (const cbf_h5handle nx, hid_t *const
group, const char *name)
DESCRIPTION
This will check if the beam group within the handle matches any existing
group of the same name within the current file. If they don't match a
new group is opened or created and added to the handle. The NX_class
attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of "beam".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.10 cbf_h5handle_get_beam
* 2.7.11 cbf_h5handle_set_beam
----------------------------------------------------------------------
2.7.13 cbf_h5handle_get_instrument
Get the current id and name of the instrument group within the given
handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_instrument (const cbf_h5handle nx, hid_t *const
group, const char **const name)
DESCRIPTION
Check the handle for the presence of an instrument group and its name,
optionally returning any combination of them. The error code
'CBF_NOTFOUND' will be returned if any of the requested items of data
cannot be found.
The handle retains ownership of the returned object and/or string,
neither of them should be free'd by the caller.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.14 cbf_h5handle_set_instrument
* 2.7.15 cbf_h5handle_find_instrument
* 2.7.16 cbf_h5handle_require_instrument
----------------------------------------------------------------------
2.7.14 cbf_h5handle_set_instrument
Set the id and name of the instrument group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_instrument (const cbf_h5handle nx, const hid_t
group, const char *const name)
DESCRIPTION
Sets the instrument group and name within the handle to the given
values. Doesn't check or modify the NX_class attribute in any way. The
handle will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current instrument group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.13 cbf_h5handle_get_instrument
* 2.7.15 cbf_h5handle_find_instrument
* 2.7.16 cbf_h5handle_require_instrument
----------------------------------------------------------------------
2.7.15 cbf_h5handle_find_instrument
Find an existing instrument group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_find_instrument (const cbf_h5handle nx, hid_t *const
group, const char **const name)
ARGUMENTS
nx
group
name
----------------------------------------------------------------------
2.7.16 cbf_h5handle_require_instrument
Ensure I have an instrument in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_instrument (const cbf_h5handle nx, hid_t *const
group, const char * name)
DESCRIPTION
This will check if the instrument group within the handle matches any
existing group of the same name within the current file. If they don't
match a new group is opened or created and added to the handle. The
NX_class attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of "instrument".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.13 cbf_h5handle_get_instrument
* 2.7.14 cbf_h5handle_set_instrument
* 2.7.15 cbf_h5handle_find_instrument
----------------------------------------------------------------------
2.7.17 cbf_h5handle_get_detector
Get the current id and name of the detector group within the given
handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_detector (const cbf_h5handle nx, hid_t *const
group, const char **const name)
DESCRIPTION
Check the handle for the presence of an detector group and its name,
optionally returning any combination of them. The error code
'CBF_NOTFOUND' will be returned if any of the requested items of data
cannot be found.
The handle retains ownership of the returned object and/or string,
neither of them should be free'd by the caller.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.18 cbf_h5handle_set_detector
* 2.7.19 cbf_h5handle_find_detector
* 2.7.20 cbf_h5handle_require_detector
----------------------------------------------------------------------
2.7.18 cbf_h5handle_set_detector
Set the id and name of the detector group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_detector (const cbf_h5handle nx, const hid_t group,
const char *const name)
DESCRIPTION
Sets the detector group and name within the handle to the given values.
Doesn't check or modify the NX_class attribute in any way. The handle
will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current detector group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.17 cbf_h5handle_get_detector
* 2.7.19 cbf_h5handle_find_detector
* 2.7.20 cbf_h5handle_require_detector
----------------------------------------------------------------------
2.7.19 cbf_h5handle_find_detector
Find an existing detector group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_find_detector (const cbf_h5handle nx, hid_t *const
group, const char **const name)
ARGUMENTS
nx
group
name
----------------------------------------------------------------------
2.7.20 cbf_h5handle_require_detector
Ensure I have a detector in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_detector (const cbf_h5handle nx, hid_t *const
group, const char *name)
DESCRIPTION
This will check if the detector group within the handle matches any
existing group of the same name within the current file. If they don't
match a new group is opened or created and added to the handle. The
NX_class attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of "detector".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.17 cbf_h5handle_get_detector
* 2.7.18 cbf_h5handle_set_detector
* 2.7.19 cbf_h5handle_find_detector
----------------------------------------------------------------------
2.7.21 cbf_h5handle_get_goniometer
Get the current id and name of the goniometer group within the given
handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_goniometer (const cbf_h5handle nx, hid_t *const
group, const char **const name)
DESCRIPTION
Check the handle for the presence of an goniometer group and its name,
optionally returning any combination of them. The error code
'CBF_NOTFOUND' will be returned if any of the requested items of data
cannot be found.
The handle retains ownership of the returned object and/or string,
neither of them should be free'd by the caller.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.22 cbf_h5handle_set_goniometer
* 2.7.23 cbf_h5handle_require_goniometer
----------------------------------------------------------------------
2.7.22 cbf_h5handle_set_goniometer
Set the id and name of the goniometer group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_goniometer (const cbf_h5handle nx, const hid_t
group, const char *const name)
DESCRIPTION
Sets the goniometer group and name within the handle to the given
values. Doesn't check or modify the NX_class attribute in any way. The
handle will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current goniometer group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.21 cbf_h5handle_get_goniometer
* 2.7.23 cbf_h5handle_require_goniometer
----------------------------------------------------------------------
2.7.23 cbf_h5handle_require_goniometer
Ensure I have a goniometer in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_goniometer (const cbf_h5handle nx, hid_t *const
group, const char *name)
DESCRIPTION
This will check if the goniometer group within the handle matches any
existing group of the same name within the current file. If they don't
match a new group is opened or created and added to the handle. The
NX_class attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of "goniometer".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.21 cbf_h5handle_get_goniometer
* 2.7.22 cbf_h5handle_set_goniometer
----------------------------------------------------------------------
2.7.24 cbf_h5handle_get_monochromator
Get the current id and name of the monochromator group within the given
handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_monochromator (const cbf_h5handle nx, hid_t *const
group, const char **const name)
DESCRIPTION
Check the handle for the presence of an monochromator group and its
name, optionally returning any combination of them. The error code
'CBF_NOTFOUND' will be returned if any of the requested items of data
cannot be found.
The handle retains ownership of the returned object and/or string,
neither of them should be free'd by the caller.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.25 cbf_h5handle_set_monochromator
* 2.7.26 cbf_h5handle_require_monochromator
----------------------------------------------------------------------
2.7.25 cbf_h5handle_set_monochromator
Set the id and name of the monochromator group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_monochromator (const cbf_h5handle nx, const hid_t
group, const char * const name)
DESCRIPTION
Sets the monochromator group and name within the handle to the given
values. Doesn't check or modify the NX_class attribute in any way. The
handle will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current monochromator group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.24 cbf_h5handle_get_monochromator
* 2.7.26 cbf_h5handle_require_monochromator
----------------------------------------------------------------------
2.7.26 cbf_h5handle_require_monochromator
Ensure I have a monochromator in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_monochromator (const cbf_h5handle nx, hid_t
*const group, const char *name)
DESCRIPTION
This will check if the monochromator group within the handle matches any
existing group of the same name within the current file. If they don't
match a new group is opened or created and added to the handle. The
NX_class attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of
"monochromator".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.24 cbf_h5handle_get_monochromator
* 2.7.25 cbf_h5handle_set_monochromator
----------------------------------------------------------------------
2.7.27 cbf_h5handle_get_source
Get the current id and name of the source group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_get_source (const cbf_h5handle nx, hid_t *const group,
const char **const name)
DESCRIPTION
Check the handle for the presence of an source group and its name,
optionally returning any combination of them. The error code
'CBF_NOTFOUND' will be returned if any of the requested items of data
cannot be found.
The handle retains ownership of the returned object and/or string,
neither of them should be free'd by the caller.
ARGUMENTS
nx A handle to query for the presence of the requested information.
group A place to store the group (if found), or null if the group isn't
wanted.
name A place to store the name of the group (if found), or null if the
name isn't wanted.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.28 cbf_h5handle_set_source
* 2.7.29 cbf_h5handle_require_source
----------------------------------------------------------------------
2.7.28 cbf_h5handle_set_source
Set the id and name of the source group within the given handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_set_source (const cbf_h5handle nx, const hid_t group,
const char *const name)
DESCRIPTION
Sets the source group and name within the handle to the given values.
Doesn't check or modify the NX_class attribute in any way. The handle
will take ownership of the group id iff this function succeeds.
ARGUMENTS
nx The handle to add information to.
group The group to be set as the current source group
name The name which the group should be given.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.27 cbf_h5handle_get_source
* 2.7.29 cbf_h5handle_require_source
----------------------------------------------------------------------
2.7.29 cbf_h5handle_require_source
Ensure I have a source in the hdf5 handle.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_h5handle_require_source (const cbf_h5handle nx, hid_t *const
group, const char *name)
DESCRIPTION
This will check if the source group within the handle matches any
existing group of the same name within the current file. If they don't
match a new group is opened or created and added to the handle. The
NX_class attributes are not checked.
ARGUMENTS
nx The HDF5 handle to use.
group An optional pointer to a place where the group should be stored.
name The group name, or null to use the default name of "source".
RETURN VALUE
An error code.
SEE ALSO
* 2.7.27 cbf_h5handle_get_source
* 2.7.28 cbf_h5handle_set_source
----------------------------------------------------------------------
2.7.30 cbf_free_h5handle
Free a handle for an HDF5 file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_free_h5handle (cbf_h5handle h5handle)
DESCRIPTION
Checks if the handle appears to be valid, the free's the handle and any
data that the handle owns.
ARGUMENTS
h5handle The handle to be free'd.
RETURN VALUE
An error code
SEE ALSO
* 2.7.31 cbf_create_h5handle3
----------------------------------------------------------------------
2.7.31 cbf_create_h5handle3
Allocates space for a HDF5 file handle and associates it with the given
file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_create_h5handle3 (cbf_h5handle *handle, hid_t file)
DESCRIPTION
This function expects the user to create or open a hdf5 file with the
appropriate parameters for what they are trying to do, replacing older
functions which would create a file with the H5F_ACC_TRUNC flag and
H5F_CLOSE_STRONG property.
ARGUMENTS
handle A pointer to a handle which is to be allocated.
file A HDF5 file to store within the newly created handle.
RETURN VALUE
An error code
SEE ALSO
* 2.7.30 cbf_free_h5handle
----------------------------------------------------------------------
2.7.32 cbf_write_cbf_h5file
Extract the data from a CBF file & put it into a NeXus file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_write_cbf_h5file (cbf_handle handle, cbf_h5handle h5handle)
DESCRIPTION
Equivalent to cbf_write_cbf2nx(handle,h5handle,0,0,0).
ARGUMENTS
handle The CBF file to extract data from.
h5handle The NeXuS file to write data to.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.34 cbf_write_minicbf_h5file
* 2.7.33 cbf_write_cbf2nx
* 2.7.35 cbf_write_nx2cbf
----------------------------------------------------------------------
2.7.33 cbf_write_cbf2nx
Extract the data from a CBF file & put it into a NeXus file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_write_cbf2nx (cbf_handle handle, cbf_h5handle h5handle, const
char *const datablock, const char *const scan, const int list)
DESCRIPTION
Extracts data from handle and generates a NeXus file in h5handle. This
will attempt to extract metadata and image data from each scan (or the
named scan) within each datablock (or the the named datablock) and
insert it into a given index into the NXentry group specified in
h5handle.
Each scan in the CBF file corresponds to one NXentry in NeXus, so a CBF
datablock with multiple scans must be converted by calling this function
with the appropriate value of scan once for each scan in the datablock.
The flags (within h5handle) determine:
* Compression algorithm: zlib/CBF/none
* Plugin registration method: automatic/manual
The strings given by h5handle->scan_id and h5handle->sample_id define:
* The presence and value of an identifier for the scan, stored in
/*:NXentry/entry_identifier.
* The presence and value of an identifier for the sample, stored in
/*:NXentry/*:NXsample/sample_identifier.
ARGUMENTS
handle The CBF file to extract data from.
h5handle The NeXuS file to write data to.
datablock The name of the datablock to convert, or NULL to convert all
datablocks.
scan The name of the scan to convert, or NULL if there is only one
scan in the datablock.
list Boolean flag to determine if a list of processed items is
printed.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.32 cbf_write_cbf_h5file
* 2.7.34 cbf_write_minicbf_h5file
* 2.7.35 cbf_write_nx2cbf
----------------------------------------------------------------------
2.7.34 cbf_write_minicbf_h5file
Extract the data from a miniCBF file & put it into a NeXus file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_write_minicbf_h5file (cbf_handle handle, cbf_h5handle h5handle,
const cbf_config_t *const axisConfig)
DESCRIPTION
Extracts the miniCBF data directly - by parsing the header - and uses
that plus the configuration options from axisConfig to generate a NeXus
file in h5handle. This can extract metadata and image data from miniCBF
files containing multiple datablocks which each contain a single image
and insert it into a given index into the NXentry group specified in
h5handle.
Currently, only Pilatus 1.2 format headers are supported.
The flags determine:
* Compression algorithm: zlib/CBF/none
* Plugin registration method: automatic/manual
ARGUMENTS
handle The miniCBF file to extract data from.
h5handle The NeXus file to write data to.
axisConfig The configuration settings desribing the axes and their
relation to the sample and to each other.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.32 cbf_write_cbf_h5file
* 2.7.35 cbf_write_nx2cbf
----------------------------------------------------------------------
2.7.35 cbf_write_nx2cbf
Extract data from a nexus file and store it in a CBF file.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_write_nx2cbf (cbf_h5handle nx, cbf_handle cbf)
DESCRIPTION
Reads NeXus-format data from the entry group defined in the nx handle,
extracting data related to the frame with index nx->slice and in
CBF-format within the the cbf handle.
ARGUMENTS
nx The handle defining the NeXus data to be converted.
cbf The handle in which to store the resulting CBF data.
RETURN VALUE
An error code.
SEE ALSO
* 2.7.32 cbf_write_cbf_h5file
* 2.7.34 cbf_write_minicbf_h5file
----------------------------------------------------------------------
2.7.36 cbf_config_create
Obtain a new handle for some configuration settings.
PROTOTYPE
#include "cbf_hdf5.h"
cbf_config_t* cbf_config_create ()
DESCRIPTION
Allocates a new collection of configuration settings on the heap, and
initialises it. The returned pointer should be destroyed by the caller.
ARGUMENTS
This function takes no arguments.
RETURN VALUE
A newly allocated object for miniCBF configuration settings, or NULL.
----------------------------------------------------------------------
2.7.37 cbf_config_parse
Read a minicbf configuration file into the given handle, writing errors
to logfile.
PROTOTYPE
#include "cbf_hdf5.h"
int cbf_config_parse (FILE * const configFile, FILE * const logFile,
cbf_config_t * const vec)
DESCRIPTION
Parses a configuration file to extract a collection of configuration
settings for a miniCBF file, storing them in the given configuration
settings object. The pointer should have been obtained by a call to
cbf_config_create. The configuration file format is described in the
minicbf2nexus documentation.
ARGUMENTS
configFile The file from which the config settings should be read.
logFile A stream to be used for logging error messages.
vec An object describing the configuration settings.
RETURN VALUE
A parser error code.
----------------------------------------------------------------------
2.7.38 cbf_config_free
Free any heap memory associated with the given
cbf_hdf5_configItemVectorhandle object.
PROTOTYPE
#include "cbf_hdf5.h"
void cbf_config_free (const cbf_config_t *const vector)
DESCRIPTION
Destroys an existing collection of configuration settings. The settings
should have been obtained by a call to cbf_config_create.
ARGUMENTS
vector The configuration data to be free'd.
RETURN VALUE
Nothing.
----------------------------------------------------------------------
2.7.39 cbf_config_strerror
Convert a parse error to a descriptive string.
PROTOTYPE
#include "cbf_hdf5.h"
const char * cbf_config_strerror (const int error)
DESCRIPTION
The returned string is "none" for success, "unknown error" if the given
error code is not recognised and a non-empty string briefly describing
the error otherwise.
The returned string must not be free'd.
ARGUMENTS
error An error returned by a cbf_config_* function.
RETURN VALUE
A string describing the error.
----------------------------------------------------------------------
3. File format
3.1 General description
With the exception of the binary sections, a CBF file is an mmCIF-format
ASCII file, so a CBF file with no binary sections is a CIF file. An
imgCIF file has any binary sections encoded as CIF-format ASCII strings
and is a CIF file whether or not it contains binary sections. In most
cases, CBFlib can also be used to access normal CIF files as well as CBF
and imgCIF files.
3.2 Format of the binary sections
Before getting to the binary data itself, there are some preliminaries
to allow a smooth transition from the conventions of CIF to those of raw
or encoded streams of "octets" (8-bit bytes). The binary data is given
as the essential part of a specially formatted semicolon-delimited CIF
multi-line text string. This text string is the value associated with
the tag "_array_data.data".
The specific format of the binary sections differs between an imgCIF and
a CBF file.
3.2.1 Format of imgCIF binary sections
Each binary section is encoded as a semicolon-delimited string. Within
the text string, the conventions developed for transmitting email
messages including binary attachments are followed. There is secondary
ASCII header information, formatted as Multipurpose Internet Mail
Extensions (MIME) headers (see RFCs 2045-49 by Freed, et al.). The
boundary marker for the beginning of all this is the special string
--CIF-BINARY-FORMAT-SECTION--
at the beginning of a line. The initial "--" says that this is a MIME
boundary. We cannot put "###" in front of it and conform to MIME
conventions. Immediately after the boundary marker are MIME headers,
describing some useful information we will need to process the binary
section. MIME headers can appear in different orders, and can be very
confusing (look at the raw contents of a email message with
attachments), but there is only one header which is has to be understood
to process an imgCIF: "Content-Transfer-Encoding". If the value given on
this header is "BINARY", this is a CBF and the data will be presented as
raw binary, containing a count (in the header described in 3.2.2 Format
of CBF binary sections) so that we'll know when to start looking for
more information.
If the value given for "Content-Transfer-Encoding" is one of the real
encodings: "BASE64", "QUOTED-PRINTABLE", "X-BASE8", "X-BASE10" or
"X-BASE16", the file is an imgCIF, and we'll need some other headers to
process the encoded binary data properly. It is a good practice to give
headers in all cases. The meanings of various encodings is given in the
CBF extensions dictionary, cif_img_1.5.4.dic, as one html file, or as
separate pages for each defintion.
For certain compressions (e.g. CBF_PACKED) MIME headers are essential to
determine the parameters of the compression. The full list of MIME
headers recognized by and generated by CBFlib is:
* Content-Type:
* Content-Transfer-Encoding:
* Content-MD5:
* X-Binary-Size:
* X-Binary-ID:
* X-Binary-Element-Type:
* X-Binary-Element-Byte-Order:
* X-Binary-Number-of-Elements:
* X-Binary-Size-Fastest-Dimension:
* X-Binary-Size-Second-Dimension:
* X-Binary-Size-Third-Dimension:
* X-Binary-Size-Padding:
* Content-Type:
The "Content-Type" header tells us what sort of data we
have (currently always "application/octet-stream" for a
miscellaneous stream of binary data) and, optionally, the
conversions that were applied to the original data. The default is
to compress the data with the "CBF-PACKED" algorithm. The
Content-Type may be any of the discrete types permitted in RFC 2045;
'application/octet-stream' is recommended. If an octet stream was
compressed, the compression should be specified by the parameter
'conversions="X-CBF_PACKED"' or the parameter
'conversions="X-CBF_PACKED_V2"' or the parameter
'conversions="X-CBF_CANONICAL"' or the parameter
'conversions="X-CBF_BYTE_OFFSET"' or the parameter
'conversions="X-CBF_NIBBLE_OFFSET"'
If the parameter 'conversions="X-CBF_PACKED"' or
'conversions="X-CBF_PACKED_V2"' is given it may be further modified
with the parameters '"uncorrelated_sections"' or '"flat"'
If the '"uncorrelated_sections"' parameter is given, each section
will be compressed without using the prior section for averaging. If
the '"flat"' parameter is given, each the image will be treated as
one long row.
* Content-Transfer-Encoding:
The "Content-Transfer-Encoding" may be 'BASE64', 'Quoted-Printable',
'X-BASE8', 'X-BASE10', 'X-BASE16' or 'X-BASE32K', for an imgCIF or
'BINARY' for a CBF. The octal, decimal and hexadecimal transfer
encodings are provided for convenience in debugging and are not
recommended for archiving and data interchange.
In a CIF, one of the parameters 'charset=us-ascii', 'charset=utf-8'
or 'charset=utf-16' may be used on the Content-Transfer-Encoding to
specify the character set used for the external presentation of the
encoded data. If no charset parameter is given, the character set of
the enclosing CIF is assumed. In any case, if a BOM flag is detected
(FE FF for big-endian UTF-16, FF FE for little-endian UTF-16 or EF
BB BF for UTF-8) is detected, the indicated charset will be assumed
until the end of the encoded data or the detection of a different
BOM. The charset of the Content-Transfer-Encoding is not the
character set of the encoded data, only the character set of the
presentation of the encoded data and should be respecified for each
distinct STAR string.
In an imgCIF file, the encoded binary data begins after the empty
line terminating the header. In an imgCIF file, the encoded binary
data ends with the terminating boundary delimiter
'\n--CIF-BINARY-FORMAT-SECTION----' in the currently effective
charset or with the '\n; ' that terminates the STAR string.
In a CBF, the raw binary data begins after an empty line terminating
the header and after the sequence:
Octet Hex Decimal Purpose
0 0C 12 (ctrl-L) Page break
1 1A 26 (ctrl-Z) Stop listings in MS-DOS
2 04 04 (Ctrl-D) Stop listings in UNIX
3 D5 213 Binary section begins
None of these octets are included in the calculation of the message
size or in the calculation of the message digest.
* Content-MD5:
An MD5 message digest may, optionally, be used. The 'RSA Data
Security, Inc. MD5 Message-Digest Algorithm' should be used. No
portion of the header is included in the calculation of the message
digest. The optional "Content-MD5" header provides a much more
sophisticated check on the integrity of the binary data than size
checks alone can provide.
* X-Binary-Size:
The "X-Binary-Size" header specifies the size of the equivalent
binary data in octets. This is the size after any compressions, but
before any ascii encodings. This is useful in making a simple check
for a missing portion of this file. The 8 bytes for the Compression
type (see below) are not counted in this field, so the value of
"X-Binary-Size" is 8 less than the quantity in bytes 12-19 of the
raw binary data ( 3.2.2 Format of CBF binary sections).
* X-Binary-ID:
The "X-Binary-ID" header should contain the same value as was given
for "_array_data.binary_id".
* X-Binary-Element-Type:
The "X-Binary-Element-Type" header specifies the type of binary data
in the octets, using the same descriptive phrases as in
_array_structure.encoding_type. The default value is 'unsigned
32-bit integer'.
* X-Binary-Element-Byte-Order:
The "X-Binary-Element-Byte-Order" can specify either '"BIG_ENDIAN"'
or '"LITTLE_ENDIAN"' byte order of the image data. CBFlib only
writes '"LITTLE_ENDIAN"', and in general can only process
LITTLE_ENDIAN even on machines that are BIG_ENDIAN.
* X-Binary-Number-of-Elements:
The "X-Binary-Number-of-Elements" specifies the number of elements
(not the number of octets) in the decompressed, decoded image.
* X-Binary-Size-Fastest-Dimension:
The optional "X-Binary-Size-Fastest-Dimension" specifies the number
of elements (not the number of octets) in one row of the fastest
changing dimension of the binary data array. This information must
be in the MIME header for proper operation of some of the
decompression algorithms.
* X-Binary-Size-Second-Dimension:
The optional "X-Binary-Size-Second-Dimension" specifies the number
of elements (not the number of octets) in one column of the
second-fastest changing dimension of the binary data array. This
information must be in the MIME header for proper operation of some
of the decompression algorithms.
* X-Binary-Size-Third-Dimension:
The optional "X-Binary-Size-Third-Dimension" specifies the number of
sections for the third-fastest changing dimension of the binary data
array.
* X-Binary-Size-Padding:
The optional "X-Binary-Size-Padding" specifies the size in octets of
an optional padding after the binary array data and before the
closing flags for a binary section. CBFlib always writes this
padding as zeros, but this information should be in the MIME header
for a binary section that uses padding, especially if non-zero
padding is used.
A blank line separator immediately precedes the start of the encoded
binary data. Blank spaces may be added prior to the preceding "line
separator" if desired (e.g. to force word or block alignment).
Because CBFLIB may jump forward in the file from the MIME header, the
length of encoded data cannot be greater than the value defined by
"X-Binary-Size" (except when "X-Binary-Size" is zero, which means that
the size is unknown), unless "X-Binary-Size-Padding" is specified to
allow for the padding. At exactly the byte following the full binary
section as defined by the length and padding values is the end of binary
section identifier. This consists of the line-termination sequence
followed by:
--CIF-BINARY-FORMAT-SECTION----
;
with each of these lines followed by a line-termination sequence. This
brings us back into a normal CIF environment. This identifier is, in a
sense, redundant because the binary data length value tells the a
program how many bytes to jump over to the end of the binary data. This
redundancy has been deliberately added for error checking, and for
possible file recovery in the case of a corrupted file and this
identifier must be present at the end of every block of binary data.
3.2.2 Format of CBF binary sections
In a CBF file, each binary section is encoded as a ;-delimited string,
starting with an arbitrary number of pure-ASCII characters.
Note: For historical reasons, CIFlib has the option of writing simple
header and footer sections: "START OF BINARY SECTION" at the start of a
binary section and "END OF BINARY SECTION" at the end of a binary
section, or writing MIME-type header and footer sections (3.2.1 Format
of imgCIF binary sections). If the simple header is used, the actual
ASCII text is ignored when the binary section is read. Use of the simple
binary header is deprecated.
The MIME header is recommended.
Between the ASCII header and the actual CBF binary data is a series of
bytes ("octets") to try to stop the listing of the header, bytes which
define the binary identifier which should match the "binary_id" defined
in the header, and bytes which define the length of the binary section.
Octet Hex Decimal Purpose
1 0C 12 (ctrl-L) End of Page
2 1A 26 (ctrl-Z) Stop listings in MS-DOS
3 04 04 (Ctrl-D) Stop listings in UNIX
4 D5 213 Binary section begins
5..5+n-1 Binary data (n octets)
NOTE: When a MIME header is used, only bytes 5 through 5+n-1 are
considered in computing the size and the message digest, and only these
bytes are encoded for the equivalent imgCIF file using the indicated
Content-Transfer-Encoding.
If no MIME header has been requested (a deprecated use), then bytes 5
through 28 are used for three 8-byte words to hold the binary_id, the
size and the compression type:
5..12 Binary Section Identifier
(See _array_data.binary_id)
64-bit, little endian
13..20 The size (n) of the
binary section in octets
(i.e. the offset from octet
29 to the first byte following
the data)
21..28 Compression type:
CBF_NONE 0x0040 (64)
CBF_CANONICAL 0x0050 (80)
CBF_PACKED 0x0060 (96)
CBF_PACKED_V2 0x0090 (144)
CBF_BYTE_OFFSET 0x0070 (112)
CBF_NIBBLE_OFFSET 0x00A0 (160)
CBF_PREDICTOR 0x0080 (128)
...
The binary data then follows in bytes 29 through 29+n-1.
The binary characters serve specific purposes:
o The Control-L (from-feed) will terminate printing of the current
page on most operating systems.
o The Control-Z will stop the listing of the file on MS-DOS type
operating systems.
o The Control-D will stop the listing of the file on Unix type
operating systems.
o The unsigned byte value 213 (decimal) is binary 11010101. (Octal
325, and hexadecimal D5). This has the eighth bit set so can be used
for error checking on 7-bit transmission. It is also asymmetric, but
with the first bit also set in the case that the bit order could be
reversed (which is not a known concern).
o (The carriage return, line-feed pair before the START_OF_BIN and
other lines can also be used to check that the file has not been
corrupted e.g. by being sent by ftp in ASCII mode.)
At present four compression schemes are implemented are defined:
CBF_NONE (for no compression), CBF_CANONICAL (for and entropy-coding
scheme based on the canonical-code algorithm described by Moffat, et
al. (International Journal of High Speed Electronics and Systems,
Vol 8, No 1 (1997) 179-231)), CBF_PACKED or CBF_PACKED_V2 for J. P.
Abrahams CCP4-style packing schemes and CBF_BYTE_OFFSET for a simple
byte_offset compression scheme.. Other compression schemes will be
added to this list in the future.
For historical reasons, CBFlib can read or write a binary string without
a MIME header. The structure of a binary string with simple headers is:
Byte ASCII Decimal Description
symbol value
1 ; 59 Initial ; delimiter
2 carriage-return 13
3 line-feed 10 The CBF new-line code is
carriage-return, line-feed
4 S 83
5 T 84
6 A 65
7 R 83
8 T 84
9 32
10 O 79
11 F 70
12 32
13 B 66
14 I 73
15 N 78
16 A 65
17 R 83
18 Y 89
19 32
20 S 83
21 E 69
22 C 67
23 T 84
24 I 73
25 O 79
26 N 78
27 carriage-return 13
28 line-feed 10
29 form-feed 12
30 substitute 26 Stop the listing of the file
in MS-DOS
31 end-of-transmission 4 Stop the listing of the file
in unix
32 213 First non-ASCII value
33 .. 40 Binary section identifier
(64-bit little-endien)
41 .. 48 Offset from byte 57 to the
first ASCII character
following the binary data
49 .. 56 Compression type
57 .. 57 + n-1 Binary data (nbytes)
57 + n carriage-return 13
58 + n line-feed 10
59 + n E 69
60 + n N 78
61 + n D 68
62 + n 32
63 + n O 79
64 + n F 70
65 + n 32
66 + n B 66
67 + n I 73
68 + n N 78
69 + n A 65
70 + n R 83
71 + n Y 89
72 + n 32
73 + n S 83
74 + n E 69
75 + n C 67
76 + n T 84
77 + n I 73
78 + n O 79
79 + n N 78
80 + n carriage-return 13
81 + n line-feed 10
82 + n ; 59 Final ; delimiter
3.3 Compression schemes
Two schemes for lossless compression of integer arrays (such as images)
have been implemented in this version of CBFlib:
1. An entropy-encoding scheme using canonical coding
2. A CCP4-style packing scheme. 3. A simple and efficient byte-offset
compression. 4. A slightly more complex nibble-offset compression.
All encode the difference (or error) between the current element in the
array and the prior element or neighboring elements.
3.3.1 Canonical-code compression
The canonical-code compression scheme encodes errors in two ways:
directly or indirectly. Errors are coded directly using a symbol
corresponding to the error value. Errors are coded indirectly using a
symbol for the number of bits in the (signed) error, followed by the
error iteslf.
At the start of the compression, CBFlib constructs a table containing a
set of symbols, one for each of the 2^n direct codes from -2^(n-1) ..
2^(n-1)-1, one for a stop code, and one for each of the maxbits -n
indirect codes, where n is chosen at compress time and maxbits is the
maximum number of bits in an error. CBFlib then assigns to each symbol a
bit-code, using a shorter bit code for the more common symbols and a
longer bit code for the less common symbols. The bit-code lengths are
calculated using a Huffman-type algorithm, and the actual bit-codes are
constructed using the canonical-code algorithm described by Moffat, et
al. (International Journal of High Speed Electronics and Systems, Vol 8,
No 1 (1997) 179-231).
The structure of the compressed data is:
Byte Value
1 .. 8 Number of elements (64-bit
little-endian number)
9 .. 16 Minimum element
17 .. 24 Maximum element
25 .. 32 (reserved for future use)
33 Number of bits directly coded, n
34 Maximum number of bits encoded, maxbits
35 .. 35+2^n-1 Number of bits in each direct code
35+2^n Number of bits in the stop code
35+2^n+1 .. 35+2^n+maxbits-n Number of bits in each indirect code
35+2^n+maxbits-n+1 .. Coded data
3.3.2 CCP4-style compression
Starting with CBFlib 0.7.7, CBFlib supports three variations on
CCP4-style compression: the "flat" version supported in versions of
CBFlib prior to release 0.7.7, as well as both version 1 and version 2
of J. P. Abrahams "pack_c" compression.
The CBF_PACKED and CBF_PACKED_V2 compression and decompression code
incorporated in CBFlib is derived in large part from the J. P. Abrahams
pack_c.c compression code in CCP4. This code is incorporated in CBFlib
under the GPL and the LGPL with both the permission Jan Pieter Abrahams,
the original author of pack_c.c (email from Jan Pieter Abrahams of 15
January 2007) and of the CCP4 project (email from Martyn Winn on 12
January 2007). The cooperation of J. P. Abrahams and of the CCP4 project
is gratefully acknowledged.
The basis for all three versions is a scheme to pack offsets
(differences from a base value) into a small-endian bit stream. The
stream is organized into blocks. Each block begins with a header of 6
bits in the flat packed version and version 1 of J. P. Abrahams
compression, and 7 bits in version 2 of J. P. Abrahams compression. The
header gives the number of offsets that follow and the number of bits in
each offset. Each offset is a signed, 2's complement integer.
The first 3 bits in the header gives the logarithm base 2 of the numer
of offsets that follow the header. For example, if a header has a zero
in bits, only one offset follows the header. If those same bits contain
the number n, the number of offsets in the block is 2n.
The following 3 bits (flat and version 1) or 4 bits (version 2) contains
a number giving an index into a table of bit-lengths for the offsets.
All offsets in a given block are of the same length.
Bits 3 .. 5 (flat and version 1) or bits 3 .. 6 (version 2) encode the
number of bits in each offset as follows:
Value in Number of bits Number of bits
bits 3 .. 5 in each V1 offset in each V2 offset
0 0 0
1 4 3
2 5 4
3 6 5
4 7 6
5 8 7
6 16 8
7 max 9
8 10
9 11
10 12
11 13
12 14
13 15
14 16
15 max
The value "max" is determined by the compression version and the element
size. If the compression used is "flat", then "max" is 65. If the
compression is version 1 or version 2 of the JPA compression, then "max"
is the number of bits in each element, i.e. 8, 16, 32 or 64 bits.
The major difference between the three variants of packed compression is
the choice of the base value from which the offset is measured. In all
cases the first offset is measured from zero, i.e. the first offset is
the value of the first pixel of the image. If "flat" is chosen or if the
dimensions of the data array are not given, then the remaining offset
are measure against the prior value, making it similar in approach to
the "byte offset" compression described in section 3.3.3 Byte offset
compression, but with a more efficient representation of the offsets.
In version 1 and version 2 of the J. P. Abrahams compression, the
offsets are measured against an average of earlier pixels. If there is
only one row only the prior pxiel is used, starting with the same
offsets for that row as for "flat". After the first row, three pixels
from the prior row are used in addition to using the immediately prior
pixel. If there are multiple sections, and the sections are marked as
correlated, after the first section, 4 pixels from the prior section are
included in the average. The CBFlib code differs from the pack_c code in
the handling of the beginnings and ends of rows and sections. The pack_c
code will use pixels from the other side of the image in doing the
averaging. The CBFlib code drops pixels from the other side of the image
from the pool. The details follow.
After dealing with the special case of the first pixel, The algorithm
uses an array of pointers, trail_char_data. The assignment of pixels to
the pool to be averaged begins with trail_char_data[0] points to the
pixel immediately prior to the next pixel to be processed, either in the
same row (fastest index) or, at the end of the prior row if the next
data element to be processed is at the end of a row. The location of the
pixel pointed to by trail_char_data[0] is used to compute the locations
of the other pixels in the pool. It will be dropped from the pool before
averaging if it is on the opposite side of the image. The pool will
consist of 1, 2, 4 or 8 pixels.
Assume ndim1, ndim2, ndim3 are the indices of the same pixel as
trail_char_data[0] points to. These indices are incremented to be the
indices of the next pixel to be processed before populating
trail_char_data.
On exit, trail_char_data[0 .. 7] will have been populated with pointers
to the pixels to be used in forming the average. Pixels that will not be
used will be set to NULL. Note that trail_char_data[0] may be set to
NULL.
If we mark the next element to be processed with a "*" and the entries
in trail_char_data with their array indices 0 .. 7, the possible
patterns of settings in the general case are:
current section:
- - - - 0 * - - - -
- - - - 3 2 1 - - -
- - - - - - - - - -
prior section:
- - - - - 4 - - - -
- - - - 7 6 5 - - -
- - - - - - - - - -
If there is no prior section (i.e. ndim3 is 0, or the
CBF_UNCORRELATED_SECTIONS flag is set to indicate discontinuous
sections), the values for trail_char_data[4 .. 7] will all be NULL. When
there is a prior section, trail_char_data[5..7] are pointers to the
pixels immediately below the elements pointed to by
trail_char_data[1..3], except trail_char_data[4] is one element further
along its row to be directly below the next element to be processed.
The first element of the first row of the first section is a special
case, with no averaging.
In the first row of the first section (ndim2 == 0, and ndim3 == 0),
after the first element (ndim1 > 0), only trail_char_data[0] is used
current section:
- - - - 0 * - - - -
For subsequent rows of the first section (ndim2 > 0, and ndim3 == 0),
for the first element (ndim1 == 0), two elements from the prior row are
used:
current section:
* - - - - - - - - -
2 1 - - - - - - - -
- - - - - - - - - -
while for element after the first element, but before the last element
of the row, a full set of 4 elements is used:
current section:
- - - - 0 * - - - -
- - - - 3 2 1 - - -
- - - - - - - - - -
For the last element of a row (ndim1 == dim1-1), two elements are used
current section:
- - - - - - - - 0 *
- - - - - - - - - 2
- - - - - - - - - -
For sections after the first section, provided the
CBF_UNCORRELATED_SECTIONS flag is not set in the compression, for each
non-NULL entry in trail_char_data [0..3] an entry is made in
trail_char_data [4..7], except for the first element of the first row of
a section. In that case an entry is made in trail_char_data[4].
The structure of the compressed data is:
Byte Value
1 .. 8 Number of elements (64-bit little-endian number)
9 .. 16 Minumum element (currently unused)
17 .. 24 Maximum element (currently unused)
25 .. 32 (reserved for future use)
33 .. Coded data
3.3.3 Byte_offset compression
Starting with CBFlib 0.7.7, CBFlib supports a simple and efficient
"byte_offset" algorithm originally proposed by Andy Hammerley and
modified by Wolgang Kabsch and Herbert Bernstein. The original proposal
was called "byte_offsets". We distinguish this variant by calling it
"byte_offset". The major differences are that the "byte_offsets"
algorithm started with explicit storage of the first element of the
array as a 4-byte signed two's integer, and checked for image edges to
changes the selection of prior pixel. The CBFlib "byte_offset"
alogorithm starts with an assumed zero before the first pixel and
represents the value of the first pixel as an offset of whatever number
of size is needed to hold the value, and for speed, treats the entire
image as a simple linear array, allowing use of the last pixel of one
row as the base against which to compute the offset for the first
element of the next row.
The algorithm is simple and easily implemented. This algorithm can never
achieve better than a factor of two compression relative to 16-bit raw
data or 4 relative to 32-bit raw data, but for most diffraction data the
compression will indeed be very close to these ideal values. It also has
the advantage that integer values up to 32 bits (or 31 bits and sign)
may be stored efficiently without the need for special over-load tables.
It is a fixed algorithm which does not need to calculate any image
statistics, so is fast.
The algorithm works because of the following property of almost all
diffraction data and much other image data: The value of one element
tends to be close to the value of the adjacent elements, and the vast
majority of the differences use little of the full dynamic range.
However, noise in experimental data means that run-length encoding is
not useful (unless the image is separated into different bit-planes). If
a variable length code is used to store the differences, with the number
of bits used being inversely proportional to the probability of
occurrence, then compression ratios of 2.5 to 3.0 may be achieved.
However, the optimum encoding becomes dependent of the exact properties
of the image, and in particular on the noise. Here a lower compression
ratio is achieved, but the resulting algorithm is much simpler and more
robust.
The "byte_offset" compression algorithm is the following:
1. Start with a base pixel value of 0.
2. Compute the difference delta between the next pixel value and the
base pixel value.
3. If -127 =< delta =< 127, output delta as one byte, make the current
pixel value the base pixel value and return to step 2.
4. Otherwise output -128 (80 hex).
5. We still have to output delta. If -32767 =< delta =< 32767, output
delta as a little_endian 16-bit quantity, make the current pixel
value the base pixel value and return to step 2.
6. Otherwise output -32768 (8000 hex, little_endian, i.e. 00 then 80)
7. We still have to output delta. If -2147483647 =< delta =<
2147483647, output delta as a little_endian 32 bit quantity, make
the current pixel value the base pixel value and return to step 2.
8. Otherwise output -2147483648 (80000000 hex, little_endian, i.e. 00,
then 00, then 00, then 80) and then output the pixel value as a
little-endian 64 bit quantity, make the current pixel value the base
pixel value and return to step 2.
The "byte_offset" decompression algorithm is the following:
1. Start with a base pixel value of 0.
2. Read the next byte as delta
3. If -127 =< delta =< 127, add delta to the base pixel value, make
that the new base pixel value, place it on the output array and
return to step 2.
4. If delta is 80 hex, read the next two bytes as a little_endian
16-bit number and make that delta.
5. If -32767 =< delta =< 32767, add delta to the base pixel value, make
that the new base pixel value, place it on the output array and
return to step 2.
6. If delta is 8000 hex, read the next 4 bytes as a little_endian
32-bit number and make that delta
7. If -2147483647 =< delta =< 2147483647, add delta to the base pixel
value, make that the new base pixel value, place it on the output
array and return to step 2.
8. If delta is 80000000 hex, read the next 8 bytes as a little_endian
64-bit number and make that delta, add delta to the base pixel
value, make that the new base pixel value, place it on the output
array and return to step 2.
Let us look at an example, of two 1000 x 1000 flat field images
presented as a mimimal imgCIF file. The first image uses 32-bit unsigned
integers and the second image uses 16-bit unsigned integers.
The imgCIF file begins with some identifying comments (magic numbers) to
track the version of the dictionary and library:
###CBF: VERSION 1.5
# CBF file written by CBFlib v0.7.7
This is followed by the necessary syntax to start a CIF data block and
by whatever tags and values are appropriate to describe the experiment.
The minimum is something like
data_testflat
eventually we come to the actual binary data, which begins the loop
header for the array_data category
loop_
_array_data.data
with any additional tags needed, and then the data itself, which starts
with the mini-header:
;
--CIF-BINARY-FORMAT-SECTION--
Content-Type: application/octet-stream;
conversions="x-CBF_BYTE_OFFSET"
Content-Transfer-Encoding: BINARY
X-Binary-Size: 1000002
X-Binary-ID: 1
X-Binary-Element-Type: "unsigned 32-bit integer"
X-Binary-Element-Byte-Order: LITTLE_ENDIAN
Content-MD5: +FqUJGxXhvCijXMFHC0kaA==
X-Binary-Number-of-Elements: 1000000
X-Binary-Size-Fastest-Dimension: 1000
X-Binary-Size-Second-Dimension: 1000
X-Binary-Size-Padding: 4095
followed by an empty line and then the sequence of characters:
^L^Z^D<D5>
followed immediately by the compressed data.
The binary data begins with the hex byte 80 to flag the need for a value
that will not fit in one byte. That is followed by the small_endian hex
value 3E8 saying that the first delta is 1000. Then 999,999 bytes of
zero follow, since this is a flat field, with all values equal to zero.
That gives us our entire 1000x1000 compressed flat field. However,
because we asked for 4095 bytes of padding, there is an additional 4095
bytes of zero that are not part of the compressed field. They are just
pad and can be ignored. Finally, after the pad, the CIF text field that
began with
;
--CIF-BINARY-FORMAT-SECTION--
is completed with
--CIF-BINARY-FORMAT-SECTION----
;
notice the extra --
The second flat field then follows, with a very similar mini-header:
;
--CIF-BINARY-FORMAT-SECTION--
Content-Type: application/octet-stream;
conversions="x-CBF_BYTE_OFFSET"
Content-Transfer-Encoding: BINARY
X-Binary-Size: 1000002
X-Binary-ID: 2
X-Binary-Element-Type: "unsigned 16-bit integer"
X-Binary-Element-Byte-Order: LITTLE_ENDIAN
Content-MD5: +FqUJGxXhvCijXMFHC0kaA==
X-Binary-Number-of-Elements: 1000000
X-Binary-Size-Fastest-Dimension: 1000
X-Binary-Size-Second-Dimension: 1000
X-Binary-Size-Padding: 4095
^L^Z^D<D5>
The only difference is that we have declared this array to be 16-bit and
have chosen a different binary id (2 instead of 1). Even the checksum is
the same.
3.3.4 Nibble_offset compression
The nibble offset algorithm is a variant on A. P. Hammersley's byte
offset algorithm. The major differences are that the compression modes
are "sticky", the compression can be reset at any point to allow for
block parallelism, and the basic unit of compression is the nibble, but
for very clean data, the dibit is also supported.
The data stream starts with and in general uses a mode-setting octet
presented in one if three forms, a single dibit a0, two dibits a0, a1,
or two dibits and a nibble a0, a1, b:
+-----------------------------------------------+
| a0 a1 b | octet | meaning |
|------------+-------+--------------------------|
| 00 00 0000 | 0x00 | reset to zero |
|------------+-------+--------------------------|
| 01 | 0x01 | up 1 mode |
|------------+-------+--------------------------|
| 10 | 0x02 | dibit mode |
|------------+-------+--------------------------|
| 11 | 0x03 | up n modes |
|------------+-------+--------------------------|
| 00 01 | 0x04 | nibble mode |
|------------+-------+--------------------------|
| 00 11 | 0x0C | 6-bit mode |
|------------+-------+--------------------------|
| 00 10 | 0x08 | byte mode |
|------------+-------+--------------------------|
| 00 00 0011 | 0x30 | 12-bit word mode |
|------------+-------+--------------------------|
| 00 00 0001 | 0x10 | 16-bit word mode |
|------------+-------+--------------------------|
| 00 00 0010 | 0x20 | 32-bit word mode |
|------------+-------+--------------------------|
| 00 00 0100 | 0x40 | 64-bit word mode |
|------------+-------+--------------------------|
| 00 00 1100 | 0xC0 | specify starting address |
+-----------------------------------------------+
The reset to zero is followed by a new mode octet A reset to zero resets
the prior value for delta to zero
The up n modes code is followed immediately by a dibit specifying 2 less
than the number of modes by which to change, and then by a delta in the
mode.
Note that up n modes has no effect until an actual mode has been set and
can be used immediately after a reset to pad to nibble, octet or
double-word boundaries.
Once a mode is established, it is followed by a stream of deltas of that
size (for modes 2 or 4-64) or by one delta of that size and then a
stream of deltas of the size that was in effect before an up or down
giving little-endian offsets from the currently accumulated value. If
the offset is one of the following in the indicated mode
+------------------------------------------+
| dibit mode | 0x2 |
|------------------+-----------------------|
| nibble mode | 0x8 |
|------------------+-----------------------|
| 6-bit mode | 0x20 |
|------------------+-----------------------|
| byte mode | 0x80 |
|------------------+-----------------------|
| 12-bit word mode | 0x800 |
|------------------+-----------------------|
| 16-bit word mode | 0x8000 |
|------------------+-----------------------|
| 32-bit word mode | 0x8000 0000 |
|------------------+-----------------------|
| 64-bit word mode | 0x8000 0000 0000 0000 |
+------------------------------------------+
it is followed by the new mode as 1 or 2 dibits or 2 dibits and a nibble
a1 a1 b. If a1 is 1 or 2 or 3, that is the new mode. If a1 is zero and
a2 is 1 or 2 the new mode is a2*4. If a2 is 3 the new mode is a2*2. If
both a1 and a2 are zero, the new mode is b*16 unless b is 3. If b is 3
the new mode is b*4
The 0xC0 flag is followed by a second mode giving the number of bytes of
image starting offset address followed by the image offset address
followed by the mode of that data. 0xC0 also acts as a reset. Use of the
0xC0 flag is not required. Addresses default to sequential starting from
0, but is provided to faciliate parallel compression.
3.4 Access to CBFlib compressions from HDF5
Starting with CBFlib release 0.9.2.11, a plugin module in provided to
allow access to CBFlib compressions from HDF5 1.8.11 and later. For
general documentation on HDF5 dynamically loaded filters, see
http://www.hdfgroup.org/HDF5/doc/Advanced/DynamicallyLoadedFilters/HDF5DynamicallyLoadedFilters.pdf
The discussion here will be confined to use of the CBFlib compressions
plugin.
The filter has been registered with the HDF5 group as 32006, and cbf.h
includes the symbolic name for the filter CBF_H5Z_FILTER_CBF.
The source and header of the CBFlib filter plugin are cbf_hdf5_filter.c
and cbf_hdf5_filter.h. To use the filter in C applications, you will
need to include cbf_hdf5_filter.h in the application and have the
cbflib.so library in the search path used by HDF5 1.8.11. The HDF group
says
The default directory for an HDF5 filter plugin library is defined on
UNIX- like systems as quot;/usr/local/hdf5/lib/plugin"
and on Windows systems as "%ALLUSERSPROFILE%/hdf5/lib/plugin". The
default path can be overwritten by a user with the HDF5_PLUGIN_PATH
environment variable. Several directories can be specified for the
search path using ":" as a path separator for UNIX-like systems and
";" for Windows.
In the Makefile, tests are done by defining HDF5_PLUGIN_PATH to point to
the build kit shared library directory:
HDF5_PLUGIN_PATH=$(SOLIB); export HDF5_PLUGIN_PATH;
In most cases that should be sufficient to allow code to read HDF5 files
with datasets compressed with this filter.
In order to write files that use this filter, several relevant values
must first be stored into an unsigned int array, cd_values. The header,
cbf_hdf5_filter.h, defines the follwing symbolic values for the indices
of this array:
+------------------------------------------------------------------------------+
| symbol | value | meaning |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_NELMTS | 11 | size of cd_values |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_COMPRESSION | 0 | one of the compressions (see 3.2.2) |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_RESERVED | 1 | reserved for future use, should be |
| | | set to zero |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_BINARY_ID | 2 | binary ID of the array (default 1) |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_ELSIZE | 3 | element size in octets |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_ELSIGN | 4 | 1 if signed, 0 if unsigned |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_REAL | 5 | 1 if a real array, 0 if an integer |
| | | array |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_DIMOVER | 6 | the total number of elements in the |
| | | array |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_DIMFAST | 7 | the fast dimension |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_DIMMID | 8 | the middle dimension |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_DIMSLOW | 9 | the slow domension |
|--------------------------------+-------+-------------------------------------|
| CBF_H5Z_FILTER_CBF_PADDING | 10 | the padding |
+------------------------------------------------------------------------------+
Only chunked data may be written using this filter. The recommended
chunk size is a single image. The filter writes the chunks using the
imgCIF binary section format described in section 3.2.1 including the
MIME header. If each chunk is the size of an image, programs such as XDS
can use the patterns of the MIME header to skip directly to a frame even
in a complex HDF5 file. Typical code to write such chunks would first
define the cd_values array and an array of chunk dimensions and create
the properties to be used in creating a dataset, as in
unsigned int cd_values[CBF_H5Z_FILTER_CBF_NELMTS];
hsize_t chunk[3];
hid_t valspace;
chunk[0] = 1;
chunk[1] = dimmid;
chunk[2] = dimfast;
cd_values[CBF_H5Z_FILTER_CBF_COMPRESSION] = compression;
cd_values[CBF_H5Z_FILTER_CBF_RESERVED] = 0;
cd_values[CBF_H5Z_FILTER_CBF_BINARY_ID] = id;
cd_values[CBF_H5Z_FILTER_CBF_PADDING] = padding;
cd_values[CBF_H5Z_FILTER_CBF_ELSIZE] = (bits+7)/8;
cd_values[CBF_H5Z_FILTER_CBF_ELSIGN] = sign;
cd_values[CBF_H5Z_FILTER_CBF_REAL] = realarray;
cd_values[CBF_H5Z_FILTER_CBF_DIMFAST] = dimfast;
cd_values[CBF_H5Z_FILTER_CBF_DIMMID] = dimmid;
cd_values[CBF_H5Z_FILTER_CBF_DIMSLOW] = dimslow;
valprop = H5Pcreate(H5P_DATASET_CREATE);
H5Pset_chunk(valprop,3,chunk);
H5Pset_filter(valprop,CBF_H5Z_FILTER_CBF,H5Z_FLAG_OPTIONAL,CBF_H5Z_FILTER_CBF_NELMTS,cd_values);
4. Installation
CBFlib should be built on a disk with at least 400 megabytes of free
space. CBFlib-0.9.2.11.tar.gz is a "gzipped" tar of the code as it now
stands. Place the gzipped tar in the directory that is intended to
contain a new directory, named CBFlib_0.9.2.11 (the "top-level"
directory) and uncompress it with gunzip and unpack it with tar:
gunzip CBFlib.tar.gz
tar xvf CBFLIB.tar
As with prior releases, to run the test programs, you will also need
Paul Ellis's sample MAR345 image, example.mar2300, and Chris Nielsen's
sample ADSC Quantum 315 image, mb_LP_1_001.img as sample data. Both
these files will be extracted by the Makefile from
CBFlib_0.7.7_Data_Files. Do not download copies into the top level
directory.
After unpacking the archive, the top-level directory should contain a
makefile:
Makefile Makefile for unix
and the subdirectories:
src/ CBFLIB source files
include/ CBFLIB header files
m4/ CBFLIB m4 macro files (used to build .f90 files)
examples/ Example program source files
doc/ Documentation
lib/ Compiled CBFLIB library
bin/ Executable example programs
html_images/ JPEG images used in rendering the HTML files
For instructions on compiling and testing the library, go to the
top-level directory and type:
make
The CBFLIB source and header files are in the "src" and "include"
subdirectories. The FCBLIB source and m4 files are in the "src" and "m4"
subdirectories. The files are:
src/ include/ m4/ Description
cbf.c cbf.h CBFLIB API
functions
cbf_alloc.c cbf_alloc.h Memory allocation
functions
cbf_ascii.c cbf_ascii.h Function for
writing ASCII
values
cbf_binary.c cbf_binary.h Functions for
binary values
cbf_byte_offset.c cbf_byte_offset.h Byte-offset
compression
cbf_canonical.c cbf_canonical.h Canonical-code
compression
cbf_codes.c cbf_codes.h Encoding and
message digest
functions
cbf_compress.c cbf_compress.h General
compression
routines
cbf_context.c cbf_context.h Control of
temporary files
cbf_file.c cbf_file.h File in/out
functions
cbf_lex.c cbf_lex.h Lexical analyser
cbf_packed.c cbf_packed.h CCP4-style
packing compression
cbf_predictor.c cbf_predictor.h Predictor-Huffman
compression (not
implemented)
cbf_read_binary.c cbf_read_binary.h Read binary
headers
cbf_read_mime.c cbf_read_mime.h Read MIME-encoded
binary sections
cbf_simple.c cbf_simple.h Higher-level
CBFlib functions
cbf_string.c cbf_string.h Case-insensitive
string comparisons
cbf_stx.c cbf_stx.h Parser (generated
from cbf.stx.y)
cbf_tree.c cbf_tree.h CBF
tree-structure
functions
cbf_uncompressed.c cbf_uncompressed.h Uncompressed
binary sections
cbf_write.c cbf_write.h Functions for
writing
cbf_write_binary.c cbf_write_binary.h Write binary
sections
cbf.stx.y bison grammar to
define cbf_stx.c
(see WARNING)
md5c.c md5.h RSA message
digest software
from mpack
global.h
fcb_atol_wcnt.f90 Function to
convert a string to
an integer
fcb_ci_strncmparr.f90 Function to do a
case-insensitive
comparison of a
string to a byte
array
fcb_nblen_array.f90 Function to
determine the
non-blank length of
a byte array
fcb_read_byte.f90 Function to read
a single byte
fcb_read_line.f90 Function to read
a line into a byte
array
fcb_skip_whitespace.f90 Function to skip
whitespace and
comments in a MIME
header
fcb_exit_binary.m4 Function to skip
past the end of the
current binary text
field
fcb_next_binary.m4 Function to skip
to the next binary
fcb_open_cifin.m4 Function to open
a CBF file for
reading
fcb_packed.m4 Functions to read
a JPA CCP4
compressed image
fcb_read_bits.m4 Functions to read
nay number of bits
as an integer
fcb_read_image.m4 Functions to read
the next image in
I2, I4, 3D_I2 and
3D_I4 format
fcb_read_xds_i2.m4 Function to read
a single xds image.
fcblib_defines.m4 General m4 macro
file for FCBLIB
routines.
In the "examples" subdirectory, there are 2 additional files used by the
example programs (section 5) for reading MAR300, MAR345 or ADSC CCD
images:
img.c img.h Simple image library
and the example programs themselves:
makecbf.c Make a CBF file from an image
img2cif.c Make an imgCIF or CBF from an image
cif2cbf.c Copy a CIF/CBF to a CIF/CBF
convert_image.c Convert an image file to a cbf using a template file
cif2c.c Convert a template cbf file into a function to
produce the same template in an internal cbf data
structure
testcell.C Exercise the cell functions
as well as three template files: template_adscquantum4_2304x2304.cbf,
template_mar345_2300x2300.cbf, and
template_adscquantum315_3072x3072.cbf.
Two additional examples (test_fcb_read_image.f90 and
test_xds_binary.f90) are created from two files (test_fcb_read_image.m4
and test_xds_binary.m4) in the m4 directory.
The documentation files are in the "doc" subdirectory:
CBFlib.html This document (HTML)
CBFlib.txt This document (ASCII)
CBFlib_NOTICES.html Important NOTICES -- PLEASE READ
CBFlib_NOTICES.txt Important NOTICES -- PLEASE READ
gpl.txt GPL -- PLEASE READ
lgpl.txt LGPL -- PLEASE READ
cbf_definition_rev.txt Draft CBF/ImgCIF definition (ASCII)
cbf_definition_rev.html Draft CBF/ImgCIF definition (HTML)
cif_img.html CBF/ImgCIF extensions dictionary (HTML)
cif_img.dic CBF/ImgCIF extensions dictionary (ASCII)
ChangeLog,html Summary of change history (HTML)
ChangeLog Summary of change history (ASCII)
5. Example programs
The example programs makecbf.c, img2cif.c and convert_image.c read an
image file from a MAR300, MAR345 or ADSC CCD detector and then uses
CBFlib to convert it to CBF format (makecbf) or either imgCIF or CBF
format (img2cif). makecbf writes the CBF-format image to disk, reads it
in again, and then compares it to the original. img2cif just writes the
desired file. makecbf works only from stated files on disk, so that
random I/O can be used. img2cif includes code to process files from
stdin and to stdout. convert_image reads a template as well as the image
file and produces a complete CBF. The program convert_minicbf reads a
minimal CBF file with just and image and some lines of text specifying
the parameters of the data collection as done at SLS and combines the
result with a template to produce a full CBF. The program cif2cbf can be
used to convert among carious compression and encoding schemes. The
program sauter_test.C is a C++ test program contributed by Nick Sauter
to help in resolving a memory leak he found. The programs adscimg2cbf
and cbf2adscimg are a "jiffies" contributed by Chris Nielsen of ADSC to
convert ADSC images to imgCIF/CBF format and vice versa.
makecbf.c is a good example of how many of the CBFlib functions can be
used. To compile makecbf and the other example programs use the Makefile
in the top-level directory:
make all
This will place the programs in the bin directory.
makecbf
To run makecbf with the example image, type:
./bin/makecbf example.mar2300 test.cbf
The program img2cif has the following command line interface:
img2cif [-i input_image] \
[-o output_cif] \
[-c {p[acked]|c[annonical]|[n[one]}] \
[-m {h[eaders]|n[oheaders]}] \
[-d {d[igest]|n[odigest]}] \
[-e {b[ase64]|q[uoted-printable]| \
d[ecimal]|h[exadecimal]|o[ctal]|n[one]}] \
[-b {f[orward]|b[ackwards]}] \
[input_image] [output_cif]
the options are:
-i input_image (default: stdin)
the input_image file in MAR300, MAR345 or ADSC CCD detector
format is given. If no input_image file is specified or is
given as "-", an image is copied from stdin to a temporary file.
-o output_cif (default: stdout)
the output cif (if base64 or quoted-printable encoding is used)
or cbf (if no encoding is used). if no output_cif is specified
or is given as "-", the output is written to stdout
-c compression_scheme (packed, canonical or none, default packed)
-m [no]headers (default headers for cifs, noheaders for cbfs)
selects MIME (N. Freed, N. Borenstein, RFC 2045, November 1996)
headers within binary data value text fields.
-d [no]digest (default md5 digest [R. Rivest, RFC 1321, April
1992 using"RSA Data Security, Inc. MD5 Message-Digest
Algorithm"] when MIME headers are selected)
-e encoding (base64, quoted-printable, decimal, hexadecimal,
octal or none, default: base64) specifies one of the standard
MIME encodings (base64 or quoted-printable) or a non-standard
decimal, hexamdecimal or octal encoding for an ascii cif
or "none" for a binary cbf
-b direction (forward or backwards, default: backwards)
specifies the direction of mapping of bytes into words
for decimal, hexadecimal or octal output, marked by '>' for
forward or '<' for backwards as the second character of each
line of output, and in '#' comment lines.
cif2cbf
The test program cif2cbf uses many of the same command line options as
img2cif, but accepts either a CIF or a CBF as input instead of an image
file:
cif2cbf [-i input_cif] [-o output_cbf] \
[-u update_cif] \
[-c {p[acked]|c[annonical]|{b[yte_offset]}|\
{v[2packed]}|{f[latpacked]}|{I|nIbble_offset}|n[one]}] \
[-C highclipvalue] \
[-D ] \
[-I {0|2|4|8}] \
[-R {0|4|8}] \
[-L {0|4|8}] \
[-m {h[eaders]|noh[eaders]}] \
[-m {d[imensions]|nod[imensions}] \
[-d {d[igest]|n[odigest]|w[arndigest]}] \
[-B {read|liberal|noread}] [-B {write|nowrite}] \
[-S {read|noread}] [-S {write|nowrite}] \
[-T {read|noread}] [-T {write|nowrite}] \
[-e {b[ase64]|q[uoted-printable]|\
d[ecimal]|h[examdecimal|o[ctal]|n[one]}] \
[-b {f[orward]|b[ackwards]}\
[-p {1|2|4}\
[-v dictionary]* [-w] [-W]\
[-5 {r|w|rw|rn|wn|rwn|n[oH5]}\
[-O] \
[input_cif] [output_cbf]
the options are:
the options are:
-i input_cif (default: stdin)
the input file in CIF or CBF format. If input_cif is not
specified or is given as "-", it is copied from stdin to a
temporary file.
-o output_cbf (default: stdout)
the output cif (if base64 or quoted-printable encoding is used)
or cbf (if no encoding is used). if no output_cif is specified
or is given as "-", the output is written to stdout
if the output_cbf is /dev/null, no output is written.
-u update_cif (no default)
and optional second input file in CIF or CBF format containing
data blocks to be merged with data blocks from the primary
input CIF or CBF
The remaining options specify the characteristics of the
output cbf. Most of the characteristics of the input cif are
derived from context, except when modified by the -B, -S, -T, -v
and -w flags.
-b byte_order (forward or backwards, default forward (1234) on
little-endian machines, backwards (4321) on big-endian machines
-B [no]read or liberal (default noread)
read to enable reading of DDLm style brackets
liberal to accept whitespace for commas
-B [no]write (default write)
write to enable writing of DDLm style brackets
-c compression_scheme (Packed, Canonical, Byte_offset,
V2packed, Flatpacked, nIbble or None,
default packed)
-C highclipvalue
specifies a double precision value to which to clip the data
-d [no]digest or warndigest (default md5 digest [R. Rivest,
RFC 1321, April 1992 using"RSA Data Security, Inc. MD5
Message-Digest Algorithm"] when MIME headers are selected)
-D test cbf_construct_detector
-e encoding (base64, k, quoted-printable or none, default base64)
specifies one of the standard MIME encodings for an ascii cif
or "none" for a binary cbf
-I 0 or integer element size
specifies integer conversion of the data, 0 to use the input
number of bytes, 2, 4 or 8 for short, long or long long
output integers
-L lowclipvalue
specifies a double precision value to cut off the data from
below
-m [no]headers (default headers)
selects MIME (N. Freed, N. Borenstein, RFC 2045, November 1996)
headers within binary data value text fields.
-m [nod]imensions (default dimensions)
selects detailed recovery of dimensions from the input CIF
for use in the MIME header of the output CIF
-p K_of_padding (0, 1, 2, 4) for no padding after binary data
1023, 2047 or 4095 bytes of padding after binary data
-R 0 or integer element size
specifies real conversion of the data, 0 to use the input
number of bytes, 4 or 8 for float or double output reals
-S [no]read or (default noread)
read to enable reading of whitespace and comments
-S [no]write (default write)
write to enable writing of whitespace and comments
-T [no]read or (default noread)
read to enable reading of DDLm style triple quotes
-T [no]write (default write)
write to enable writing of DDLm style triple quotes
-v dictionary specifies a dictionary to be used to validate
the input cif and to apply aliases to the output cif.
This option may be specified multiple times, with dictionaries
layered in the order given.
-w process wide (2048 character) lines
-W write wide (2048 character) lines
-5 hdf5mode specifies whether to read and/or write in hdf5 mode
the n parameter will cause the CIF H5 datablock to be deleted
on both read and write, for both CIF, CBF and HDF5 files
-O when in -5 w (hdf5 write) mode, -O forces the use of opaque
objects for CBF binaries
convert_image
The program convert_image requires two arguments: imagefile and cbffile.
Those are the primary input and output. The detector type is extracted
from the image file or from the command line, converted to lower case
and used to construct the name of a template cbf file to use for the
copy. The template file name is of the form template_name_columnsxrows.
The full set of options is:
convert_image [-i input_img] [-o output_cbf] [-p template_cbf]\
[-d detector name] -m [x|y|x=y] [-z distance] \
[-c category_alias=category_root]* \
[-t tag_alias=tag_root]* [-F] [-R] \
[input_img] [output_cbf]
the options are:
-i input_img (default: stdin)
the input file as an image in smv, mar300, or mar345 format.
If input_img is not specified or is given as "-", it is copied
from stdin to a temporary file.
-p template_cbf
the template for the final cbf to be produced. If template_cbf
is not specified the name is constructed from the first token
of the detector name and the image size as
template_<type>_<columns>x<rows>.cbf
-o output_cbf (default: stdout )
the output cbf combining the image and the template. If the
output_cbf is not specified or is given as "-", it is written
to stdout.
-d detectorname
a detector name to be used if none is provided in the image
header.
-F
when writing packed compression, treat the entire image as
one line with no averaging
-m [x|y|x=y] (default x=y, square arrays only)
mirror the array in the x-axis (y -> -y)
in the y-axis (x -> -x)
or in x=y ( x -> y, y-> x)
-r n
rotate the array n times 90 degrees counter clockwise
x -> y, y -> -x for each rotation, n = 1, 2 or 3
-R
if setting a beam center, set reference values of
axis settings as well as standard settings
-z distance
detector distance along Z-axis
-c category_alias=category_root
-t tag_alias=tagroot
map the given alias to the given root, so that instead
of outputting the alias, the root will be presented in the
output cbf instead. These options may be repeated as many
times as needed.
convert_minicbf
The program convert_minicbf requires two arguments: minicbf and cbffile.
Those are the primary input and output. The detector type is extracted
from the image file or from the command line, converted to lower case
and used to construct the name of a template cbf file to use for the
copy. The template file name is of the form template_name_columnsxrows.
The full set of options is:
convert_minicbf [-i input_cbf] [-o output_cbf] [-p template_cbf]\
[-q] [-C convention] \
[-d detector name] -m [x|y|x=y] [-z distance] \
[-c category_alias=category_root]* \
[-t tag_alias=tag_root]* [-F] [-R] \
[input_cbf] [output_cbf]
the options are:
-i input_cbf (default: stdin)
the input file as a CBF with at least an image.
-p template_cbf
the template for the final cbf to be produced. If template_cbf
is not specified the name is constructed from the first token
of the detector name and the image size as
template_<type>_<columns>x<rows>.cbf
-o output_cbf (default: stdout )
the output cbf combining the image and the template. If the
output_cbf is not specified or is given as "-", it is written
to stdout.
-q
exit quickly with just the miniheader expanded
after the data. No template is used.
-Q
exit quickly with just the miniheader unexpanded
before the data. No template is used.
-C convention
convert the comment form of miniheader into the
_array_data.header_convention convention
_array_data.header_contents
overriding any existing values
-d detectorname
a detector name to be used if none is provided in the image
header.
-F
when writing packed compression, treat the entire image as
one line with no averaging
-m [x|y|x=y] (default x=y, square arrays only)
mirror the array in the x-axis (y -> -y)
in the y-axis (x -> -x)
or in x=y ( x -> y, y-> x)
-r n
rotate the array n times 90 degrees counter clockwise
x -> y, y -> -x for each rotation, n = 1, 2 or 3
-R
if setting a beam center, set reference values of
axis settings as well as standard settings
-z distance
detector distance along Z-axis
-c category_alias=category_root
-t tag_alias=tagroot
map the given alias to the given root, so that instead
of outputting the alias, the root will be presented in the
output cbf instead. These options may be repeated as many
times as needed.
testreals, testflat and testflatpacked
The example programs testreals, testflat and testflatpacked exercise the
handling of reals, byte_offset compression and packed compression. Each
is run without any arguments. testreals will read real images from the
data file testrealin.cbf and write a file with real images in
testrealout.cbf, which should be identical to testrealin.cbf. testflat
and testflatpacked read 4 1000x1000 2D images and one 50x60x70 3D image
and produce an output file that should be identical to the input.
testflat reads testflatin.cbf and produces testflatout.cbf using
CBF_BYTE_OFFSET compression. testflatpacked reads testflatpackedin.cbf
and produces testflatpackedout.cbf. The images are:
* A 1000 x 1000 array of 32-bit integers forming a flat field with all
pixels set to 1000.
* A 1000 x 1000 array of 16-bit integers forming a flat field with all
pixels set to 1000.
* A 1000 x 1000 array of 32-bit integers forming a flat field with all
pixels set to 1000, except for -3 along the main diagonal and its
transpose.
* A 1000 x 1000 array of 16-bit integers forming a flat field with all
pixels set to 1000, except for -3 along the main diagonal and its
transpose.
* A 50 x 60 x 70 array of 32-bit integers in a flat field of 1000,
except for -3 along the main diagonal and the values i+j+k (counting
from zero) every 1000th pixel
test_fcb_read_image, test_xds_binary
The example programs test_fcb_read_image and test_xds_binary are
designed read the output of testflat and testflatpacked using the FCBlib
routines in lib/libfcb. test_xds_binary reads only the first image and
closes the file immediately. test_fcb_read_image reads all 5 images from
the input file. The name of the input file should be provided on stdin,
as in:
* echo testflatout.cbf | bin/test_xds_binary
* echo testflatpackedout.cbf | bin/test_xds_binary
* echo testflatout.cbf | bin/test_fcb_read_image
* echo testflatpackedout.cbf | bin/test_fcb_read_image
In order to compile these programs correctly for the G95 compiler it is
important to set the record size for reading to be no larger than the
padding after binary images. This in controlled in Makefile by the line
M4FLAGS = -Dfcb_bytes_in_rec=131072 which provides good performance for
gfortran. For g95, this line must be changed to M4FLAGS =
-Dfcb_bytes_in_rec=4096
sauter_test
The program sauter_test.C is a C++ test program contributed by Nick
Sauter to help in resolving a memory leak he found. The program is run
as bin/sauter_test and should run long enough to allow a check with top
to ensure that it has constant memory demands. In addition, starting
with release 0.7.8.1, the addition of -DCBFLIB_MEM_DEBUG to the compiler
flags will cause detailed reports on memory use to stderr to be
reported.
adscimg2cbf
The example program adscimg2cbf accepts any number of raw or compressed
ADSC images with .img, .img.gz, .img.bz2 or .img.Z extensions and
converts each of them to an imgCIF/CBF file with a .cbf extension.
adscimg2cbf [--flag[,modifier]] file1.img ... filen.img (creates file1.cbf ... filen.cbf)
Image files may also be compressed (.gz, .bz2, .Z)
Flags:
--cbf_byte_offset Use BYTE_OFFSET compression (DEFAULT)
--cbf_packed Use CCP4 packing (JPA) compression.
--cbf_packed_v2 Use CCP4 packing version 2 (JPA) compression.
--no_compression No compression.
The following two modifiers can be appended to the flags (syntax: --flag,modifier):
flat Flat (linear) images.
uncorrelated Uncorrelated sections.
adscimg2cbf
The example program cbf2adscimg accepts any number of cbfs of ADSC
images created by adscimg1cbf or convert_image and produces raw or
compressed adsc image files with .img, .img.gz or .img.bz2 extensions.
cbf2adscimg [--flag] file1.cbf ... filen.cbf (creates file1.img ... filen.img)
Image files may be compressed on output: (.gz, .bz2) by using the flags below.\n");
Flags:
--gz Output a .gz file (e.g., filen.img.gz).
--bz2 Output a .bz2 file (e.g., filen.img.bz2).
tiff2cbf
The test program tiff2cbf converts a tiff data file to a cbf data file.
The program converts the tiff data samples directly into a minicbf with
the tiff header stored at the value of _array_data.header_contents. This
conversion is supported for the sample formats SAMPLEFORMAT_UINT
(unsigned integer data), SAMPLEFORMAT_INT (unsigned integer data),
SAMPLEFORMAT_INT (signed integer data), SAMPLEFORMAT_IEEEFP (IEEE
floating point data), SAMPLEFORMAT_COMPLEXINT (complex signed int) and
SAMPLEFORMAT_COMPLEXIEEEFP (complex ieee floating). Conversions from
these formats to other CBF formats can be handled by cif2cbf. If you
wish to convert and xxx.tif written with IEEE floating point samples
into a CBF with integer values compressed by byte-offset compression for
use by XDS, creating an xxx_view.cbf with values clipped between 0 and
100, and an xxx_xds.cbf with unclipped values for processing:
tiff2cbf xxx.tif xxx.cbf
cif2cbf -I 4 -C 100. -L 0. -e n -c b -i xxx.cbf -o xxx_view.cbf
cif2cbf -I 4 -e n -c b -i xxx.cbf -o xxx_xds.cbf
minicbf2nexus
This program takes some minicbf files describing a single scan and axis
configuration settings for them and creates a nexus file containing the
same data. As this is an early version of the program it lacks a lot of
useful functionality and should not be assumed to be stable.
It currently takes several command line arguments:
* -c
--compression
These are optional and take a single case-insensitive argument which
describes the compression used for the dataset.
Currently implemented values are:
* cbf
Use the same CBFlib compression method as the miniCBF data uses
* none
Don't compress the data
* zlib
Use zlib compression
More compression options will be added in later versions, including
options for CBFlib compression schemes.
* -C
--config
This takes a single argument giving the file name of a configuration
file which describes how the axes of the minicbf file relate to each
other.
* -g
--group
This takes a string defining the name of the group where the data
should be inserted. Currently, the file will begin in an empty state
and this will cause a group of the given name to be created, but
this will eventually allow data to be inserted into an existing
user-defined group.
* -o
--output
This takes a single argument which is used as the filename for the
new nexus file. Any existing files of the same name are overwritten
without warning, so be careful that the name of any existing files
that you wish to keep are not passed as an argument here.
* -Z
--register
Takes a single case-insensitive argument of 'manual' or 'plugin'
defining the method of plugin registration used. May be specified
multiple times to define a system default (via an alias) and
optionally over-ride it later.
* Other arguments are interpreted as file names identifying the
miniCBF files to be packed into the new NeXus file. These must
currently be pilatus v1.2 miniCBF files, but this restriction will
be relaxed in later versions.
An example, from the test scripts, is:
minicbf2nexus -c zlib -C config X4_test_1.cbf X4_test_2&3.cbf
X4_test_4.cbf X4_test_5.cbf -o minicbf.h5
Where test files 1, 4 & 5 are each single-image miniCBF files and test
file 2 & 3 is created by 'cat'ing together two single-image miniCBF
files
The config file used for this example is:
# some sample config settings for a miniCBF file
map Start_angle to CBF_axis_omega
map Phi to CBF_axis_phi
map Kappa to CBF_axis_kappa
Sample depends-on CBF_axis_phi
CBF_axis_phi vector [1 0 0] depends-on CBF_axis_kappa
CBF_axis_kappa vector [0 1 0] depends-on .
CBF_axis_omega vector [0 0 0]
Text from any # character to the end of the line is ignored as a
comment.
Axes are declared by the map keyword as the name of the axis in the
minicbf file, which must match exactly, followed by the keyword to and
then the name that will be given to the axis in the resulting nexus
file. Each axis is treated as a rotation axis and should have a vector
which defines the axis of rotation in the 3D coordinate frame used by
nexus, this should be 3 numbers within square brackets separated by
spaces and does not need to be normalised. Each axis may also depend on
a nother axis by using the keyword depends-on folowed by the name of the
nexus axis it depends on, or . if it does not depend on another axis,
omitting a dependency as shown on the final line of the example above is
not recommended as it will eventually be a fatal error. The vector and
depends-on declarations do not need to be on the same line.
The Sample keyword is used to define a dependency for the sample being
scanned and should be followed by a depends-on declaration which defines
the name of the nexus axis that the sample depends on.
The final line of the config file should be blank to allow for some
simple integrity tests.
A continuous chain of dependencies should be formed from the sample to
the nexus coordinate system, otherwise there is insufficient information
available to properly describe the orientation of the sample. This will
be enforced in later versions, with a fatal error if insufficient
information is provided.
cbf2nexus
This program takes some CBF files describing a single scan and converts
them to a single NeXus file containing the same data. It can also be
used to merge a CBF file into an existing NeXus file.
It currently takes several command line arguments:
* -c
--compression
These are optional and take a single case-insensitive argument which
describes the compression used for the dataset.
Currently implemented values are:
* cbf
Use the same CBFlib compression method as the miniCBF data uses
* none
Don't compress the data
* zlib
Use zlib compression
More compression options will be added in later versions, including
options for CBFlib compression schemes.
* -g
--group
This takes a string defining the name of the group where the data
should be inserted. Currently, the file will begin in an empty state
and this will cause a group of the given name to be created, but
this will eventually allow data to be inserted into an existing
user-defined group.
* -o
--output
This takes a single argument which is used as the filename for the
new nexus file. Any existing files of the same name are overwritten
without warning, so be careful that the name of any existing files
that you wish to keep are not passed as an argument here.
* -u
--update
This take a single argument which is used as the filename for an
existing nexus file, to which the nexus translation of the input
file will be added. This is a direct change in the specified file.
It is not making a copy first.
* -Z
--register
Takes a single case-insensitive argument of 'manual' or 'plugin'
defining the method of plugin registration used. May be specified
multiple times to define a system default (via an alias) and
optionally over-ride it later. This is only relevant if the NeXus
file is written with CBF compression algorithms, it doesn't have any
effect for uncompressed data or data compressed uning HDF5's
built-in compression algorithms.
* --datablock
Gives the name of a datblock to attempt to extract data from, or may
be omitted to extract data from all datablocks.
* --scan
Gives the name of a scan to attempt to extract data from, or may be
omitted if there is only one scan in the datablock(s).
* --experiment_id
Should be a unique identifier for the scan, which will be stored in
/*:NXentry/entry_identifier.
* --sample_id
Should be a unique identifier for the sample, which will be stored
in /*:NXentry/*:NXsample/sample_identifier.
* --list & --no-list
Determines whether the list of recognised data items is printed or
not. These may be used multiple times, the last specified value is
the one that is actually used.
* Other arguments are interpreted as file names identifying the CBF
files to be packed into the new NeXus file.
An example, from the test scripts, is:
cbf2nexus -c zlib adscconverted.cbf adscconverted.cbf -o cbf.zlib.h5
This creates a single NeXus file containing two copies of the
'adscconverted' CBF file.
nexus2cbf
This program converts a single frame of data from a nexus file to a cbf
file with a given name. The primary purpose of this program is to help
verify that data can be recovered after being converted to NeXus format,
to check that it hasn't been lost or mangled.
It currently takes several command line arguments:
* -f
--frame
This should be an integer, in the range [0, frameCount), defining
the index of the frame that is to be extracted, and defaults to 0.
* -g
--group
This takes a string defining the name of the group where the data
should be inserted. Currently, the file will begin in an empty state
and this will cause a group of the given name to be created, but
this will eventually allow data to be inserted into an existing
user-defined group.
* -o
--output
This takes a single argument which is used as the filename for the
new NeXus file. Any existing files of the same name are overwritten
without warning, so be careful that the name of any existing files
that you wish to keep are not passed as an argument here.
* -Z
--register
Takes a single case-insensitive argument of 'manual' or 'plugin'
defining the method of plugin registration used. May be specified
multiple times to define a system default (via an alias) and
optionally over-ride it later. This is only relevant if the NeXus
file was written with CBF compression algorithms, it doesn't have
any effect for uncompressed data or data compressed uning HDF5's
built-in compression algorithms.
* The remaining argument(s) should be the file name of the NeXus file
that is to be converted.
testhdf5
This program runs a set of unit tests on the HDF5 abstraction layer.
These are designed to ensure everything is working correctly, to help
locate bugs and prevent regressions. A short summary will be printed
detailing the number of tests passed, the number of tests failed and the
number of components skipped. If any tests fail or are skipped then some
additional output should be produced to help identify the cause of the
error so that it is easier to fix.
The program does not take any command-line arguments, and creates a file
called testfile.h5 in its working directory for use in the tests.
testulp
This program runs a set of unit tests on the ULP comparison functions.
These are designed to ensure everything is working correctly, to help
locate bugs and prevent regressions. A short summary will be printed
detailing the number of tests passed, the number of tests failed and the
number of components skipped. If any tests fail or are skipped then some
additional output should be produced to help identify the cause of the
error so that it is easier to fix.
The program does not take any command-line arguments.
----------------------------------------------------------------------
----------------------------------------------------------------------
----------------------------------------------------------------------
Updated 22 February 2015. Contact: yaya at bernstein-plus-sons dot com
|