1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767
5768
5769
5770
5771
5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823
5824
5825
5826
5827
5828
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
5944
5945
5946
5947
5948
5949
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
7107
7108
7109
7110
7111
7112
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254
7255
7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
7419
7420
7421
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
7438
7439
7440
7441
7442
7443
7444
7445
7446
7447
7448
7449
7450
7451
7452
7453
7454
7455
7456
7457
7458
7459
7460
7461
7462
7463
7464
7465
7466
7467
7468
7469
7470
7471
7472
7473
7474
7475
7476
7477
7478
7479
7480
7481
7482
7483
7484
7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
7557
7558
7559
7560
7561
7562
7563
7564
7565
7566
7567
7568
7569
7570
7571
7572
7573
7574
7575
7576
7577
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
7640
7641
7642
7643
7644
7645
7646
7647
7648
7649
7650
7651
7652
7653
7654
7655
7656
7657
7658
7659
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671
7672
7673
7674
7675
7676
7677
7678
7679
7680
7681
7682
7683
7684
7685
7686
7687
7688
7689
7690
7691
7692
7693
7694
7695
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716
7717
7718
7719
7720
7721
7722
7723
7724
7725
7726
7727
7728
7729
7730
7731
7732
7733
7734
7735
7736
7737
7738
7739
7740
7741
7742
7743
7744
7745
7746
7747
7748
7749
7750
7751
7752
7753
7754
7755
7756
7757
7758
7759
7760
7761
7762
7763
7764
7765
7766
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
7780
7781
7782
7783
7784
7785
7786
7787
7788
7789
7790
7791
7792
7793
7794
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
7807
7808
7809
7810
7811
7812
7813
7814
7815
7816
7817
7818
7819
7820
7821
7822
7823
7824
7825
7826
7827
7828
7829
7830
7831
7832
7833
7834
7835
7836
7837
7838
7839
7840
7841
7842
7843
7844
7845
7846
7847
7848
7849
7850
7851
7852
7853
7854
7855
7856
7857
7858
7859
7860
7861
7862
7863
7864
7865
7866
7867
7868
7869
7870
7871
7872
7873
7874
7875
7876
7877
7878
7879
7880
7881
7882
7883
7884
7885
7886
7887
7888
7889
7890
7891
7892
7893
7894
7895
7896
7897
7898
7899
7900
7901
7902
7903
7904
7905
7906
7907
7908
7909
7910
7911
7912
7913
7914
7915
7916
7917
7918
7919
7920
7921
7922
7923
7924
7925
7926
7927
7928
7929
7930
7931
7932
7933
7934
7935
7936
7937
7938
7939
7940
7941
7942
7943
7944
7945
7946
7947
7948
7949
7950
7951
7952
7953
7954
7955
7956
7957
7958
7959
7960
7961
7962
7963
7964
7965
7966
7967
7968
7969
7970
7971
7972
7973
7974
7975
7976
7977
7978
7979
7980
7981
7982
7983
7984
7985
7986
7987
7988
7989
7990
7991
7992
7993
7994
7995
7996
7997
7998
7999
8000
8001
8002
8003
8004
8005
8006
8007
8008
8009
8010
8011
8012
8013
8014
8015
8016
8017
8018
8019
8020
8021
8022
8023
8024
8025
8026
8027
8028
8029
8030
8031
8032
8033
8034
8035
8036
8037
8038
8039
8040
8041
8042
8043
8044
8045
8046
8047
8048
8049
8050
8051
8052
8053
8054
8055
8056
8057
8058
8059
8060
8061
8062
8063
8064
8065
8066
8067
8068
8069
8070
8071
8072
8073
8074
8075
8076
8077
8078
8079
8080
8081
8082
8083
8084
8085
8086
8087
8088
8089
8090
8091
8092
8093
8094
8095
8096
8097
8098
8099
8100
8101
8102
8103
8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
8116
8117
8118
8119
8120
8121
8122
8123
8124
8125
8126
8127
8128
8129
8130
8131
8132
8133
8134
8135
8136
8137
8138
8139
8140
8141
8142
8143
8144
8145
8146
8147
8148
8149
8150
8151
8152
8153
8154
8155
8156
8157
8158
8159
8160
8161
8162
8163
8164
8165
8166
8167
8168
8169
8170
8171
8172
8173
8174
8175
8176
8177
8178
8179
8180
8181
8182
8183
8184
8185
8186
8187
8188
8189
8190
8191
8192
8193
8194
8195
8196
8197
8198
8199
8200
8201
8202
8203
8204
8205
8206
8207
8208
8209
8210
8211
8212
8213
8214
8215
8216
8217
8218
8219
8220
8221
8222
8223
8224
8225
8226
8227
8228
8229
8230
8231
8232
8233
8234
8235
8236
8237
8238
8239
8240
8241
8242
8243
8244
8245
8246
8247
8248
8249
8250
8251
8252
8253
8254
8255
8256
8257
8258
8259
8260
8261
8262
8263
8264
8265
8266
8267
8268
8269
8270
8271
8272
8273
8274
8275
8276
8277
8278
8279
8280
8281
8282
8283
8284
8285
8286
8287
8288
8289
8290
8291
8292
8293
8294
8295
8296
8297
8298
8299
8300
8301
8302
8303
8304
8305
8306
8307
8308
8309
8310
8311
8312
8313
8314
8315
8316
8317
8318
8319
8320
8321
8322
8323
8324
8325
8326
8327
8328
8329
8330
8331
8332
8333
8334
8335
8336
8337
8338
8339
8340
8341
8342
8343
8344
8345
8346
8347
8348
8349
8350
8351
8352
8353
8354
8355
8356
8357
8358
8359
8360
8361
8362
8363
8364
8365
8366
8367
8368
8369
8370
8371
8372
8373
8374
8375
8376
8377
8378
8379
8380
8381
8382
8383
8384
8385
8386
8387
8388
8389
8390
8391
8392
8393
8394
8395
8396
8397
8398
8399
8400
8401
8402
8403
8404
8405
8406
8407
8408
8409
8410
8411
8412
8413
8414
8415
8416
8417
8418
8419
8420
8421
8422
8423
8424
8425
8426
8427
8428
8429
8430
8431
8432
8433
8434
8435
8436
8437
8438
8439
8440
8441
8442
8443
8444
8445
8446
8447
8448
8449
8450
8451
8452
8453
8454
8455
8456
8457
8458
8459
8460
8461
8462
8463
8464
8465
8466
8467
8468
8469
8470
8471
8472
8473
8474
8475
8476
8477
8478
8479
8480
8481
8482
8483
8484
8485
8486
8487
8488
8489
8490
8491
8492
8493
8494
8495
8496
8497
8498
8499
8500
8501
8502
8503
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
8514
8515
8516
8517
8518
8519
8520
8521
8522
8523
8524
8525
8526
8527
8528
8529
8530
8531
8532
8533
8534
8535
8536
8537
8538
8539
8540
8541
8542
8543
8544
8545
8546
8547
8548
8549
8550
8551
8552
8553
8554
8555
8556
8557
8558
8559
8560
8561
8562
8563
8564
8565
8566
8567
8568
8569
8570
8571
8572
8573
8574
8575
8576
8577
8578
8579
8580
8581
8582
8583
8584
8585
8586
8587
8588
8589
8590
8591
8592
8593
8594
8595
8596
8597
8598
8599
8600
8601
8602
8603
8604
8605
8606
8607
8608
8609
8610
8611
8612
8613
8614
8615
8616
8617
8618
8619
8620
8621
8622
8623
8624
8625
8626
8627
8628
8629
8630
8631
8632
8633
8634
8635
8636
8637
8638
8639
8640
8641
8642
8643
8644
8645
8646
8647
8648
8649
8650
8651
8652
8653
8654
8655
8656
8657
8658
8659
8660
8661
8662
8663
8664
8665
8666
8667
8668
8669
8670
8671
8672
8673
8674
8675
8676
8677
8678
8679
8680
8681
8682
8683
8684
8685
8686
8687
8688
8689
8690
8691
8692
8693
8694
8695
8696
8697
8698
8699
8700
8701
8702
8703
8704
8705
8706
8707
8708
8709
8710
8711
8712
8713
8714
8715
8716
8717
8718
8719
8720
8721
8722
8723
8724
8725
8726
8727
8728
8729
8730
8731
8732
8733
8734
8735
8736
8737
8738
8739
8740
8741
8742
8743
8744
8745
8746
8747
8748
8749
8750
8751
8752
8753
8754
8755
8756
8757
8758
8759
8760
8761
8762
8763
8764
8765
8766
8767
8768
8769
8770
8771
8772
8773
8774
8775
8776
8777
8778
8779
8780
8781
8782
8783
8784
8785
8786
8787
8788
8789
8790
8791
8792
8793
8794
8795
8796
8797
8798
8799
8800
8801
8802
8803
8804
8805
8806
8807
8808
8809
8810
8811
8812
8813
8814
8815
8816
8817
8818
8819
8820
8821
8822
8823
8824
8825
8826
8827
8828
8829
8830
8831
8832
8833
8834
8835
8836
8837
8838
8839
8840
8841
8842
8843
8844
8845
8846
8847
8848
8849
8850
8851
8852
8853
8854
8855
8856
8857
8858
8859
8860
8861
8862
8863
8864
8865
8866
8867
8868
8869
8870
8871
8872
8873
8874
8875
8876
8877
8878
8879
8880
8881
8882
8883
8884
8885
8886
8887
8888
8889
8890
8891
8892
8893
8894
8895
8896
8897
8898
8899
8900
8901
8902
8903
8904
8905
8906
8907
8908
8909
8910
8911
8912
8913
8914
8915
8916
8917
8918
8919
8920
8921
8922
8923
8924
8925
8926
8927
8928
8929
8930
8931
8932
8933
8934
8935
8936
8937
8938
8939
8940
8941
8942
8943
8944
8945
8946
8947
8948
8949
8950
8951
8952
8953
8954
8955
8956
8957
8958
8959
8960
8961
8962
8963
8964
8965
8966
8967
8968
8969
8970
8971
8972
8973
8974
8975
8976
8977
8978
8979
8980
8981
8982
8983
8984
8985
8986
8987
8988
8989
8990
8991
8992
8993
8994
8995
8996
8997
8998
8999
9000
9001
9002
9003
9004
9005
9006
9007
9008
9009
9010
9011
9012
9013
9014
9015
9016
9017
9018
9019
9020
9021
9022
9023
9024
9025
9026
9027
9028
9029
9030
9031
9032
9033
9034
9035
9036
9037
9038
9039
9040
9041
9042
9043
9044
9045
9046
9047
9048
9049
9050
9051
9052
9053
9054
9055
9056
9057
9058
9059
9060
9061
9062
9063
9064
9065
9066
9067
9068
9069
9070
9071
9072
9073
9074
9075
9076
9077
9078
9079
9080
9081
9082
9083
9084
9085
9086
9087
9088
9089
9090
9091
9092
9093
9094
9095
9096
9097
9098
9099
9100
9101
9102
9103
9104
9105
9106
9107
9108
9109
9110
9111
9112
9113
9114
9115
9116
9117
9118
9119
9120
9121
9122
9123
9124
9125
9126
9127
9128
9129
9130
9131
9132
9133
9134
9135
9136
9137
9138
9139
9140
9141
9142
9143
9144
9145
9146
9147
9148
9149
9150
9151
9152
9153
9154
9155
9156
9157
9158
9159
9160
9161
9162
9163
9164
9165
9166
9167
9168
9169
9170
9171
9172
9173
9174
9175
9176
9177
9178
9179
9180
9181
9182
9183
9184
9185
9186
9187
9188
9189
9190
9191
9192
9193
9194
9195
9196
9197
9198
9199
9200
9201
9202
9203
9204
9205
9206
9207
9208
9209
9210
9211
9212
9213
9214
9215
9216
9217
9218
9219
9220
9221
9222
9223
9224
9225
9226
9227
9228
9229
9230
9231
9232
9233
9234
9235
9236
9237
9238
9239
9240
9241
9242
9243
9244
9245
9246
9247
9248
9249
9250
9251
9252
9253
9254
9255
9256
9257
9258
9259
9260
9261
9262
9263
9264
9265
9266
9267
9268
9269
9270
9271
9272
9273
9274
9275
9276
9277
9278
9279
9280
9281
9282
9283
9284
9285
9286
9287
9288
9289
9290
9291
9292
9293
9294
9295
9296
9297
9298
9299
9300
9301
9302
9303
9304
9305
9306
9307
9308
9309
9310
9311
9312
9313
9314
9315
9316
9317
9318
9319
9320
9321
9322
9323
9324
9325
9326
9327
9328
9329
9330
9331
9332
9333
9334
9335
9336
9337
9338
9339
9340
9341
9342
9343
9344
9345
9346
9347
9348
9349
9350
9351
9352
9353
9354
9355
9356
9357
9358
9359
9360
9361
9362
9363
9364
9365
9366
9367
9368
9369
9370
9371
9372
9373
9374
9375
9376
9377
9378
9379
9380
9381
9382
9383
9384
9385
9386
9387
9388
9389
9390
9391
9392
9393
9394
9395
9396
9397
9398
9399
9400
9401
9402
9403
9404
9405
9406
9407
9408
9409
9410
9411
9412
9413
9414
9415
9416
9417
9418
9419
9420
9421
9422
9423
9424
9425
9426
9427
9428
9429
9430
9431
9432
9433
9434
9435
9436
9437
9438
9439
9440
9441
9442
9443
9444
9445
9446
9447
9448
9449
9450
9451
9452
9453
9454
9455
9456
9457
9458
9459
9460
9461
9462
9463
9464
9465
9466
9467
9468
9469
9470
9471
9472
9473
9474
9475
9476
9477
9478
9479
9480
9481
9482
9483
9484
9485
9486
9487
9488
9489
9490
9491
9492
9493
9494
9495
9496
9497
9498
9499
9500
9501
9502
9503
9504
9505
9506
9507
9508
9509
9510
9511
9512
9513
9514
9515
9516
9517
9518
9519
9520
9521
9522
9523
9524
9525
9526
9527
9528
9529
9530
9531
9532
9533
9534
9535
9536
9537
9538
9539
9540
9541
9542
9543
9544
9545
9546
9547
9548
9549
9550
9551
9552
9553
9554
9555
9556
9557
9558
9559
9560
9561
9562
9563
9564
9565
9566
9567
9568
9569
9570
9571
9572
9573
9574
9575
9576
9577
9578
9579
9580
9581
9582
9583
9584
9585
9586
9587
9588
9589
9590
9591
9592
9593
9594
9595
9596
9597
9598
9599
9600
9601
9602
9603
9604
9605
9606
9607
9608
9609
9610
9611
9612
9613
9614
9615
9616
9617
9618
9619
9620
9621
9622
9623
9624
9625
9626
9627
9628
9629
9630
9631
9632
9633
9634
9635
9636
9637
9638
9639
9640
9641
9642
9643
9644
9645
9646
9647
9648
9649
9650
9651
9652
9653
9654
9655
9656
9657
9658
9659
9660
9661
9662
9663
9664
9665
9666
9667
9668
9669
9670
9671
9672
9673
9674
9675
9676
9677
9678
9679
9680
9681
9682
9683
9684
9685
9686
9687
9688
9689
9690
9691
9692
9693
9694
9695
9696
9697
9698
9699
9700
9701
9702
9703
9704
9705
9706
9707
9708
9709
9710
9711
9712
9713
9714
9715
9716
9717
9718
9719
9720
9721
9722
9723
9724
9725
9726
9727
9728
9729
9730
9731
9732
9733
9734
9735
9736
9737
9738
9739
9740
9741
9742
9743
9744
9745
9746
9747
9748
9749
9750
9751
9752
9753
9754
9755
9756
9757
9758
9759
9760
9761
9762
9763
9764
9765
9766
9767
9768
9769
9770
9771
9772
9773
9774
9775
9776
9777
9778
9779
9780
9781
9782
9783
9784
9785
9786
9787
9788
9789
9790
9791
9792
9793
9794
9795
9796
9797
9798
9799
9800
9801
9802
9803
9804
9805
9806
9807
9808
9809
9810
9811
9812
9813
9814
9815
9816
9817
9818
9819
9820
9821
9822
9823
9824
9825
9826
9827
9828
9829
9830
9831
9832
9833
9834
9835
9836
9837
9838
9839
9840
9841
9842
9843
9844
9845
9846
9847
9848
9849
9850
9851
9852
9853
9854
9855
9856
9857
9858
9859
9860
9861
9862
9863
9864
9865
9866
9867
9868
9869
9870
9871
9872
9873
9874
9875
9876
9877
9878
9879
9880
9881
9882
9883
9884
9885
9886
9887
9888
9889
9890
9891
9892
9893
9894
9895
9896
9897
9898
9899
9900
9901
9902
9903
9904
9905
9906
9907
9908
9909
9910
9911
9912
9913
9914
9915
9916
9917
9918
9919
9920
9921
9922
9923
9924
9925
9926
9927
9928
9929
9930
9931
9932
9933
9934
9935
9936
9937
9938
9939
9940
9941
9942
9943
9944
9945
9946
9947
9948
9949
9950
9951
9952
9953
9954
9955
9956
9957
9958
9959
9960
9961
9962
9963
9964
9965
9966
9967
9968
9969
9970
9971
9972
9973
9974
9975
9976
9977
9978
9979
9980
9981
9982
9983
9984
9985
9986
9987
9988
9989
9990
9991
9992
9993
9994
9995
9996
9997
9998
9999
10000
10001
10002
10003
10004
10005
10006
10007
10008
10009
10010
10011
10012
10013
10014
10015
10016
10017
10018
10019
10020
10021
10022
10023
10024
10025
10026
10027
10028
10029
10030
10031
10032
10033
10034
10035
10036
10037
10038
10039
10040
10041
10042
10043
10044
10045
10046
10047
10048
10049
10050
10051
10052
10053
10054
10055
10056
10057
10058
10059
10060
10061
10062
10063
10064
10065
10066
10067
10068
10069
10070
10071
10072
10073
10074
10075
10076
10077
10078
10079
10080
10081
10082
10083
10084
10085
10086
10087
10088
10089
10090
10091
10092
10093
10094
10095
10096
10097
10098
10099
10100
10101
10102
10103
10104
10105
10106
10107
10108
10109
10110
10111
10112
10113
10114
10115
10116
10117
10118
10119
10120
10121
10122
10123
10124
10125
10126
10127
10128
10129
10130
10131
10132
10133
10134
10135
10136
10137
10138
10139
10140
10141
10142
10143
10144
10145
10146
10147
10148
10149
10150
10151
10152
10153
10154
10155
10156
10157
10158
10159
10160
10161
10162
10163
10164
10165
10166
10167
10168
10169
10170
10171
10172
10173
10174
10175
10176
10177
10178
10179
10180
10181
10182
10183
10184
10185
10186
10187
10188
10189
10190
10191
10192
10193
10194
10195
10196
10197
10198
10199
10200
10201
10202
10203
10204
10205
10206
10207
10208
10209
10210
10211
10212
10213
10214
10215
10216
10217
10218
10219
10220
10221
10222
10223
10224
10225
10226
10227
10228
10229
10230
10231
10232
10233
10234
10235
10236
10237
10238
10239
10240
10241
10242
10243
10244
10245
10246
10247
10248
10249
10250
10251
10252
10253
10254
10255
10256
10257
10258
10259
10260
10261
10262
10263
10264
10265
10266
10267
10268
10269
10270
10271
10272
10273
10274
10275
10276
10277
10278
10279
10280
10281
10282
10283
10284
10285
10286
10287
10288
10289
10290
10291
10292
10293
10294
10295
10296
10297
10298
10299
10300
10301
10302
10303
10304
10305
10306
10307
10308
10309
10310
10311
10312
10313
10314
10315
10316
10317
10318
10319
10320
10321
10322
10323
10324
10325
10326
10327
10328
10329
10330
10331
10332
10333
10334
10335
10336
10337
10338
10339
10340
10341
10342
10343
10344
10345
10346
10347
10348
10349
10350
10351
10352
10353
10354
10355
10356
10357
10358
10359
10360
10361
10362
10363
10364
10365
10366
10367
10368
10369
10370
10371
10372
10373
10374
10375
10376
10377
10378
10379
10380
10381
10382
10383
10384
10385
10386
10387
10388
10389
10390
10391
10392
10393
10394
10395
10396
10397
10398
10399
10400
10401
10402
10403
10404
10405
10406
10407
10408
10409
10410
10411
10412
10413
10414
10415
10416
10417
10418
10419
10420
10421
10422
10423
10424
10425
10426
10427
10428
10429
10430
10431
10432
10433
10434
10435
10436
10437
10438
10439
10440
10441
10442
10443
10444
10445
10446
10447
10448
10449
10450
10451
10452
10453
10454
10455
10456
10457
10458
10459
10460
10461
10462
10463
10464
10465
10466
10467
10468
10469
10470
10471
10472
10473
10474
10475
10476
10477
10478
10479
10480
10481
10482
10483
10484
10485
10486
10487
10488
10489
10490
10491
10492
10493
10494
10495
10496
10497
10498
10499
10500
10501
10502
10503
10504
10505
10506
10507
10508
10509
10510
10511
10512
10513
10514
10515
10516
10517
10518
10519
10520
10521
10522
10523
10524
10525
10526
10527
10528
10529
10530
10531
10532
10533
10534
10535
10536
10537
10538
10539
10540
10541
10542
10543
10544
10545
10546
10547
10548
10549
10550
10551
10552
10553
10554
10555
10556
10557
10558
10559
10560
10561
10562
10563
10564
10565
10566
10567
10568
10569
10570
10571
10572
10573
10574
10575
10576
10577
10578
10579
10580
10581
10582
10583
10584
10585
10586
10587
10588
10589
10590
10591
10592
10593
10594
10595
10596
10597
10598
10599
10600
10601
10602
10603
10604
10605
10606
10607
10608
10609
10610
10611
10612
10613
10614
10615
10616
10617
10618
10619
10620
10621
10622
10623
10624
10625
10626
10627
10628
10629
10630
10631
10632
10633
10634
10635
10636
10637
10638
10639
10640
10641
10642
10643
10644
10645
10646
10647
10648
10649
10650
10651
10652
10653
10654
10655
10656
10657
10658
10659
10660
10661
10662
10663
10664
10665
10666
10667
10668
10669
10670
10671
10672
10673
10674
10675
10676
10677
10678
10679
10680
10681
10682
10683
10684
10685
10686
10687
10688
10689
10690
10691
10692
10693
10694
10695
10696
10697
10698
10699
10700
10701
10702
10703
10704
10705
10706
10707
10708
10709
10710
10711
10712
10713
10714
10715
10716
10717
10718
10719
10720
10721
10722
10723
10724
10725
10726
10727
10728
10729
10730
10731
10732
10733
10734
10735
10736
10737
10738
10739
10740
10741
10742
10743
10744
10745
10746
10747
10748
10749
10750
10751
10752
10753
10754
10755
10756
10757
10758
10759
10760
10761
10762
10763
10764
10765
10766
10767
10768
10769
10770
10771
10772
10773
10774
10775
10776
10777
10778
10779
10780
10781
10782
10783
10784
10785
10786
10787
10788
10789
10790
10791
10792
10793
10794
10795
10796
10797
10798
10799
10800
10801
10802
10803
10804
10805
10806
10807
10808
10809
10810
10811
10812
10813
10814
10815
10816
10817
10818
10819
10820
10821
10822
10823
10824
10825
10826
10827
10828
10829
10830
10831
10832
10833
10834
10835
10836
10837
10838
10839
10840
10841
10842
10843
10844
10845
10846
10847
10848
10849
10850
10851
10852
10853
10854
10855
10856
10857
10858
10859
10860
10861
10862
10863
10864
10865
10866
10867
10868
10869
10870
10871
10872
10873
10874
10875
10876
10877
10878
10879
10880
10881
10882
10883
10884
10885
10886
10887
10888
10889
10890
10891
10892
10893
10894
10895
10896
10897
10898
10899
10900
10901
10902
10903
10904
10905
10906
10907
10908
10909
10910
10911
10912
10913
10914
10915
10916
10917
10918
10919
10920
10921
10922
10923
10924
10925
10926
10927
10928
10929
10930
10931
10932
10933
10934
10935
10936
10937
10938
10939
10940
10941
10942
10943
10944
10945
10946
10947
10948
10949
10950
10951
10952
10953
10954
10955
10956
10957
10958
10959
10960
10961
10962
10963
10964
10965
10966
10967
10968
10969
10970
10971
10972
10973
10974
10975
10976
10977
10978
10979
10980
10981
10982
10983
10984
10985
10986
10987
10988
10989
10990
10991
10992
10993
10994
10995
10996
10997
10998
10999
11000
11001
11002
11003
11004
11005
11006
11007
11008
11009
11010
11011
11012
11013
11014
11015
11016
11017
11018
11019
11020
11021
11022
11023
11024
11025
11026
11027
11028
11029
11030
11031
11032
11033
11034
11035
11036
11037
11038
11039
11040
11041
11042
11043
11044
11045
11046
11047
11048
11049
11050
11051
11052
11053
11054
11055
11056
11057
11058
11059
11060
11061
11062
11063
11064
11065
11066
11067
11068
11069
11070
11071
11072
11073
11074
11075
11076
11077
11078
11079
11080
11081
11082
11083
11084
11085
11086
11087
11088
11089
11090
11091
11092
11093
11094
11095
11096
11097
11098
11099
11100
11101
11102
11103
11104
11105
11106
11107
11108
11109
11110
11111
11112
11113
11114
11115
11116
11117
11118
11119
11120
11121
11122
11123
11124
11125
11126
11127
11128
11129
11130
11131
11132
11133
11134
11135
11136
11137
11138
11139
11140
11141
11142
11143
11144
11145
11146
11147
11148
11149
11150
11151
11152
11153
11154
11155
11156
11157
11158
11159
11160
11161
11162
11163
11164
11165
11166
11167
11168
11169
11170
11171
11172
11173
11174
11175
11176
11177
11178
11179
11180
11181
11182
11183
11184
11185
11186
11187
11188
11189
11190
11191
11192
11193
11194
11195
11196
11197
11198
11199
11200
11201
11202
11203
11204
11205
11206
11207
11208
11209
11210
11211
11212
11213
11214
11215
11216
11217
11218
11219
11220
11221
11222
11223
11224
11225
11226
11227
11228
11229
11230
11231
11232
11233
11234
11235
11236
11237
11238
11239
11240
11241
11242
11243
11244
11245
11246
11247
11248
11249
11250
11251
11252
11253
11254
11255
11256
11257
11258
11259
11260
11261
11262
11263
11264
11265
11266
11267
11268
11269
11270
11271
11272
11273
11274
11275
11276
11277
11278
11279
11280
11281
11282
11283
11284
11285
11286
11287
11288
11289
11290
11291
11292
11293
11294
11295
11296
11297
11298
11299
11300
11301
11302
11303
11304
11305
11306
11307
11308
11309
11310
11311
11312
11313
11314
11315
11316
11317
11318
11319
11320
11321
11322
11323
11324
11325
11326
11327
11328
11329
11330
11331
11332
11333
11334
11335
11336
11337
11338
11339
11340
11341
11342
11343
11344
11345
11346
11347
11348
11349
11350
11351
11352
11353
11354
11355
11356
11357
11358
11359
11360
11361
11362
11363
11364
11365
11366
11367
11368
11369
11370
11371
11372
11373
11374
11375
11376
11377
11378
11379
11380
11381
11382
11383
11384
11385
11386
11387
11388
11389
11390
11391
11392
11393
11394
11395
11396
11397
11398
11399
11400
11401
11402
11403
11404
11405
11406
11407
11408
11409
11410
11411
11412
11413
11414
11415
11416
11417
11418
11419
11420
11421
11422
11423
11424
11425
11426
11427
11428
11429
11430
11431
11432
11433
11434
11435
11436
11437
11438
11439
11440
11441
11442
11443
11444
11445
11446
11447
11448
11449
11450
11451
11452
11453
11454
11455
11456
11457
11458
11459
11460
11461
11462
11463
11464
11465
11466
11467
11468
11469
11470
11471
11472
11473
11474
11475
11476
11477
11478
11479
11480
11481
11482
11483
11484
11485
11486
11487
11488
11489
11490
11491
11492
11493
11494
11495
11496
11497
11498
11499
11500
11501
11502
11503
11504
11505
11506
11507
11508
11509
11510
11511
11512
11513
11514
11515
11516
11517
11518
11519
11520
11521
11522
11523
11524
11525
11526
11527
11528
11529
11530
11531
11532
11533
11534
11535
11536
11537
11538
11539
11540
11541
11542
11543
11544
11545
11546
11547
11548
11549
11550
11551
11552
11553
11554
11555
11556
11557
11558
11559
11560
11561
11562
11563
11564
11565
11566
11567
11568
11569
11570
11571
11572
11573
11574
11575
11576
11577
11578
11579
11580
11581
11582
11583
11584
11585
11586
11587
11588
11589
11590
11591
11592
11593
11594
11595
11596
11597
11598
11599
11600
11601
11602
11603
11604
11605
11606
11607
11608
11609
11610
11611
11612
11613
11614
11615
11616
11617
11618
11619
11620
11621
11622
11623
11624
11625
11626
11627
11628
11629
11630
11631
11632
11633
11634
11635
11636
11637
11638
11639
11640
11641
11642
11643
11644
11645
11646
11647
11648
11649
11650
11651
11652
11653
11654
11655
11656
11657
11658
11659
11660
11661
11662
11663
11664
11665
11666
11667
11668
11669
11670
11671
11672
11673
11674
11675
11676
11677
11678
11679
11680
11681
11682
11683
11684
11685
11686
11687
11688
11689
11690
11691
11692
11693
11694
11695
11696
11697
11698
11699
11700
11701
11702
11703
11704
11705
11706
11707
11708
11709
11710
11711
11712
11713
11714
11715
11716
11717
11718
11719
11720
11721
11722
11723
11724
11725
11726
11727
11728
11729
11730
11731
11732
11733
11734
11735
11736
11737
11738
11739
11740
11741
11742
11743
11744
11745
11746
11747
11748
11749
11750
11751
11752
11753
11754
11755
11756
11757
11758
11759
11760
11761
11762
11763
11764
11765
11766
11767
11768
11769
11770
11771
11772
11773
11774
11775
11776
11777
11778
11779
11780
11781
11782
11783
11784
11785
11786
11787
11788
11789
11790
11791
11792
11793
11794
11795
11796
11797
11798
11799
11800
11801
11802
11803
11804
11805
11806
11807
11808
11809
11810
11811
11812
11813
11814
11815
11816
11817
11818
11819
11820
11821
11822
11823
11824
11825
11826
11827
11828
11829
11830
11831
11832
11833
11834
11835
11836
11837
11838
11839
11840
11841
11842
11843
11844
11845
11846
11847
11848
11849
11850
11851
11852
11853
11854
11855
11856
11857
11858
11859
11860
11861
11862
11863
11864
11865
11866
11867
11868
11869
11870
11871
11872
11873
11874
11875
11876
11877
11878
11879
11880
11881
11882
11883
11884
11885
11886
11887
11888
11889
11890
11891
11892
11893
11894
11895
11896
11897
11898
11899
11900
11901
11902
11903
11904
11905
11906
11907
11908
11909
11910
11911
11912
11913
11914
11915
11916
11917
11918
11919
11920
11921
11922
11923
11924
11925
11926
11927
11928
11929
11930
11931
11932
11933
11934
11935
11936
11937
11938
11939
11940
11941
11942
11943
11944
11945
11946
11947
11948
11949
11950
11951
11952
11953
11954
11955
11956
11957
11958
11959
11960
11961
11962
11963
11964
11965
11966
11967
11968
11969
11970
11971
11972
11973
11974
11975
11976
11977
11978
11979
11980
11981
11982
11983
11984
11985
11986
11987
11988
11989
11990
11991
11992
11993
11994
11995
11996
11997
11998
11999
12000
12001
12002
12003
12004
12005
12006
12007
12008
12009
12010
12011
12012
12013
12014
12015
12016
12017
12018
12019
12020
12021
12022
12023
12024
12025
12026
12027
12028
12029
12030
12031
12032
12033
12034
12035
12036
12037
12038
12039
12040
12041
12042
12043
12044
12045
12046
12047
12048
12049
12050
12051
12052
12053
12054
12055
12056
12057
12058
12059
12060
12061
12062
12063
12064
12065
12066
12067
12068
12069
12070
12071
12072
12073
12074
12075
12076
12077
12078
12079
12080
12081
12082
12083
12084
12085
12086
12087
12088
12089
12090
12091
12092
12093
12094
12095
12096
12097
12098
12099
12100
12101
12102
12103
12104
12105
12106
12107
12108
12109
12110
12111
12112
12113
12114
12115
12116
12117
12118
12119
12120
12121
12122
12123
12124
12125
12126
12127
12128
12129
12130
12131
12132
12133
12134
12135
12136
12137
12138
12139
12140
12141
12142
12143
12144
12145
12146
12147
12148
12149
12150
12151
12152
12153
12154
12155
12156
12157
12158
12159
12160
12161
12162
12163
12164
12165
12166
12167
12168
12169
12170
12171
12172
12173
12174
12175
12176
12177
12178
12179
12180
12181
12182
12183
12184
12185
12186
12187
12188
12189
12190
12191
12192
12193
12194
12195
12196
12197
12198
12199
12200
12201
12202
12203
12204
12205
12206
12207
12208
12209
12210
12211
12212
12213
12214
12215
12216
12217
12218
12219
12220
12221
12222
12223
12224
12225
12226
12227
12228
12229
12230
12231
12232
12233
12234
12235
12236
12237
12238
12239
12240
12241
12242
12243
12244
12245
12246
12247
12248
12249
12250
12251
12252
12253
12254
12255
12256
12257
12258
12259
12260
12261
12262
12263
12264
12265
12266
12267
12268
12269
12270
12271
12272
12273
12274
12275
12276
12277
12278
12279
12280
12281
12282
12283
12284
12285
12286
12287
12288
12289
12290
12291
12292
12293
12294
12295
12296
12297
12298
12299
12300
12301
12302
12303
12304
12305
12306
12307
12308
12309
12310
12311
12312
12313
12314
12315
12316
12317
12318
12319
12320
12321
12322
12323
12324
12325
12326
12327
12328
12329
12330
12331
12332
12333
12334
12335
12336
12337
12338
12339
12340
12341
12342
12343
12344
12345
12346
12347
12348
12349
12350
12351
12352
12353
12354
12355
12356
12357
12358
12359
12360
12361
12362
12363
12364
12365
12366
12367
12368
12369
12370
12371
12372
12373
12374
12375
12376
12377
12378
12379
12380
12381
12382
12383
12384
12385
12386
12387
12388
12389
12390
12391
12392
12393
12394
12395
12396
12397
12398
12399
12400
12401
12402
12403
12404
12405
12406
12407
12408
12409
12410
12411
12412
12413
12414
12415
12416
12417
12418
12419
12420
12421
12422
12423
12424
12425
12426
12427
12428
12429
12430
12431
12432
12433
12434
12435
12436
12437
12438
12439
12440
12441
12442
12443
12444
12445
12446
12447
12448
12449
12450
12451
12452
12453
12454
12455
12456
12457
12458
12459
12460
12461
12462
12463
12464
12465
12466
12467
12468
12469
12470
12471
12472
12473
12474
12475
12476
12477
12478
12479
12480
12481
12482
12483
12484
12485
12486
12487
12488
12489
12490
12491
12492
12493
12494
12495
12496
12497
12498
12499
12500
12501
12502
12503
12504
12505
12506
12507
12508
12509
12510
12511
12512
12513
12514
12515
12516
12517
12518
12519
12520
12521
12522
12523
12524
12525
12526
12527
12528
12529
12530
12531
12532
12533
12534
12535
12536
12537
12538
12539
12540
12541
12542
12543
12544
12545
12546
12547
12548
12549
12550
12551
12552
12553
12554
12555
12556
12557
12558
12559
12560
12561
12562
12563
12564
12565
12566
12567
12568
12569
12570
12571
12572
12573
12574
12575
12576
12577
12578
12579
12580
12581
12582
12583
12584
12585
12586
12587
12588
12589
12590
12591
12592
12593
12594
12595
12596
12597
12598
12599
12600
12601
12602
12603
12604
12605
12606
12607
12608
12609
12610
12611
12612
12613
12614
12615
12616
12617
12618
12619
12620
12621
12622
12623
12624
12625
12626
12627
12628
12629
12630
12631
12632
12633
12634
12635
12636
12637
12638
12639
12640
12641
12642
12643
12644
12645
12646
12647
12648
12649
12650
12651
12652
12653
12654
12655
12656
12657
12658
12659
12660
12661
12662
12663
12664
12665
12666
12667
12668
12669
12670
12671
12672
12673
12674
12675
12676
12677
12678
12679
12680
12681
12682
12683
12684
12685
12686
12687
12688
12689
12690
12691
12692
12693
12694
12695
12696
12697
12698
12699
12700
12701
12702
12703
12704
12705
12706
12707
12708
12709
12710
12711
12712
12713
12714
12715
12716
12717
12718
12719
12720
12721
12722
12723
12724
12725
12726
12727
12728
12729
12730
12731
12732
12733
12734
12735
12736
12737
12738
12739
12740
12741
12742
12743
12744
12745
12746
12747
12748
12749
12750
12751
12752
12753
12754
12755
12756
12757
12758
12759
12760
12761
12762
12763
12764
12765
12766
12767
12768
12769
12770
12771
12772
12773
12774
12775
12776
12777
12778
12779
12780
12781
12782
12783
12784
12785
12786
12787
12788
12789
12790
12791
12792
12793
12794
12795
12796
12797
12798
12799
12800
12801
12802
12803
12804
12805
12806
12807
12808
12809
12810
12811
12812
12813
12814
12815
12816
12817
12818
12819
12820
12821
12822
12823
12824
12825
12826
12827
12828
12829
12830
12831
12832
12833
12834
12835
12836
12837
12838
12839
12840
12841
12842
12843
12844
12845
12846
12847
12848
12849
12850
12851
12852
12853
12854
12855
12856
12857
12858
12859
12860
12861
12862
12863
12864
12865
12866
12867
12868
12869
12870
12871
12872
12873
12874
12875
12876
12877
12878
12879
12880
12881
12882
12883
12884
12885
12886
12887
12888
12889
12890
12891
12892
12893
12894
12895
12896
12897
12898
12899
12900
12901
12902
12903
12904
12905
12906
12907
12908
12909
12910
12911
12912
12913
12914
12915
12916
12917
12918
12919
12920
12921
12922
12923
12924
12925
12926
12927
12928
12929
12930
12931
12932
12933
12934
12935
12936
12937
12938
12939
12940
12941
12942
12943
12944
12945
12946
12947
12948
12949
12950
12951
12952
12953
12954
12955
12956
12957
12958
12959
12960
12961
12962
12963
12964
12965
12966
12967
12968
12969
12970
12971
12972
12973
12974
12975
12976
12977
12978
12979
12980
12981
12982
12983
12984
12985
12986
12987
12988
12989
12990
12991
12992
12993
12994
12995
12996
12997
12998
12999
13000
13001
13002
13003
13004
13005
13006
13007
13008
13009
13010
13011
13012
13013
13014
13015
13016
13017
13018
13019
13020
13021
13022
13023
13024
13025
13026
13027
13028
13029
13030
13031
13032
13033
13034
13035
13036
13037
13038
13039
13040
13041
13042
13043
13044
13045
13046
13047
13048
13049
13050
13051
13052
13053
13054
13055
13056
13057
13058
13059
13060
13061
13062
13063
13064
13065
13066
13067
13068
13069
13070
13071
13072
13073
13074
13075
13076
13077
13078
13079
13080
13081
13082
13083
13084
13085
13086
13087
13088
13089
13090
13091
13092
13093
13094
13095
13096
13097
13098
13099
13100
13101
13102
13103
13104
13105
13106
13107
13108
13109
13110
13111
13112
13113
13114
13115
13116
13117
13118
13119
13120
13121
13122
13123
13124
13125
13126
13127
13128
13129
13130
13131
13132
13133
13134
13135
13136
13137
13138
13139
13140
13141
13142
13143
13144
13145
13146
13147
13148
13149
13150
13151
13152
13153
13154
13155
13156
13157
13158
13159
13160
13161
13162
13163
13164
13165
13166
13167
13168
13169
13170
13171
13172
13173
13174
13175
13176
13177
13178
13179
13180
13181
13182
13183
13184
13185
13186
13187
13188
13189
13190
13191
13192
13193
13194
13195
13196
13197
13198
13199
13200
13201
13202
13203
13204
13205
13206
13207
13208
13209
13210
13211
13212
13213
13214
13215
13216
13217
13218
13219
13220
13221
13222
13223
13224
13225
13226
13227
13228
13229
13230
13231
13232
13233
13234
13235
13236
13237
13238
13239
13240
13241
13242
13243
13244
13245
13246
13247
13248
13249
13250
13251
13252
13253
13254
13255
13256
13257
13258
13259
13260
13261
13262
13263
13264
13265
13266
13267
13268
13269
13270
13271
13272
13273
13274
13275
13276
13277
13278
13279
13280
13281
13282
13283
13284
13285
13286
13287
13288
13289
13290
13291
13292
13293
13294
13295
13296
13297
13298
13299
13300
13301
13302
13303
13304
13305
13306
13307
13308
13309
13310
13311
13312
13313
13314
13315
13316
13317
13318
13319
13320
13321
13322
13323
13324
13325
13326
13327
13328
13329
13330
13331
13332
13333
13334
13335
13336
13337
13338
13339
13340
13341
13342
13343
13344
13345
13346
13347
13348
13349
13350
13351
13352
13353
13354
13355
13356
13357
13358
13359
13360
13361
13362
13363
13364
13365
13366
13367
13368
13369
13370
13371
13372
13373
13374
13375
13376
13377
13378
13379
13380
13381
13382
13383
13384
13385
13386
13387
13388
13389
13390
13391
13392
13393
13394
13395
13396
13397
13398
13399
13400
13401
13402
13403
13404
13405
13406
13407
13408
13409
13410
13411
13412
13413
13414
13415
13416
13417
13418
13419
13420
13421
13422
13423
13424
13425
13426
13427
13428
13429
13430
13431
13432
13433
13434
13435
13436
13437
13438
13439
13440
13441
13442
13443
13444
13445
13446
13447
13448
13449
13450
13451
13452
13453
13454
13455
13456
13457
13458
13459
13460
13461
13462
13463
13464
13465
13466
13467
13468
13469
13470
13471
13472
13473
13474
13475
13476
13477
13478
13479
13480
13481
13482
13483
13484
13485
13486
13487
13488
13489
13490
13491
13492
13493
13494
13495
13496
13497
13498
13499
13500
13501
13502
13503
13504
13505
13506
13507
13508
13509
13510
13511
13512
13513
13514
13515
13516
13517
13518
13519
13520
13521
13522
13523
13524
13525
13526
13527
13528
13529
13530
13531
13532
13533
13534
13535
13536
13537
13538
13539
13540
13541
13542
13543
13544
13545
13546
13547
13548
13549
13550
13551
13552
13553
13554
13555
13556
13557
13558
13559
13560
13561
13562
13563
13564
13565
13566
13567
13568
13569
13570
13571
13572
13573
13574
13575
13576
13577
13578
13579
13580
13581
13582
13583
13584
13585
13586
13587
13588
13589
13590
13591
13592
13593
13594
13595
13596
13597
13598
13599
13600
13601
13602
13603
13604
13605
13606
13607
13608
13609
13610
13611
13612
13613
13614
13615
13616
13617
13618
13619
13620
13621
13622
13623
13624
13625
13626
13627
13628
13629
13630
13631
13632
13633
13634
13635
13636
13637
13638
13639
13640
13641
13642
13643
13644
13645
13646
13647
13648
13649
13650
13651
13652
13653
13654
13655
13656
13657
13658
13659
13660
13661
13662
13663
13664
13665
13666
13667
13668
13669
13670
13671
13672
13673
13674
13675
13676
13677
13678
13679
13680
13681
13682
13683
13684
13685
13686
13687
13688
13689
13690
13691
13692
13693
13694
13695
13696
13697
13698
13699
13700
13701
13702
13703
13704
13705
13706
13707
13708
13709
13710
13711
13712
13713
13714
13715
13716
13717
13718
13719
13720
13721
13722
13723
13724
13725
13726
13727
13728
13729
13730
13731
13732
13733
13734
13735
13736
13737
13738
13739
13740
13741
13742
13743
13744
13745
13746
13747
13748
13749
13750
13751
13752
13753
13754
13755
13756
13757
13758
13759
13760
13761
13762
13763
13764
13765
13766
13767
13768
13769
13770
13771
13772
13773
13774
13775
13776
13777
13778
13779
13780
13781
13782
13783
13784
13785
13786
13787
13788
13789
13790
13791
13792
13793
13794
13795
13796
13797
13798
13799
13800
13801
13802
13803
13804
13805
13806
13807
13808
13809
13810
13811
13812
13813
13814
13815
13816
13817
13818
13819
13820
13821
13822
13823
13824
13825
13826
13827
13828
13829
13830
13831
13832
13833
13834
13835
13836
13837
13838
13839
13840
13841
13842
13843
13844
13845
13846
13847
13848
13849
13850
13851
13852
13853
13854
13855
13856
13857
13858
13859
13860
13861
13862
13863
13864
13865
13866
13867
13868
13869
13870
13871
13872
13873
13874
13875
13876
13877
13878
13879
13880
13881
13882
13883
13884
13885
13886
13887
13888
13889
13890
13891
13892
13893
13894
13895
13896
13897
13898
13899
13900
13901
13902
13903
13904
13905
13906
13907
13908
13909
13910
13911
13912
13913
13914
13915
13916
13917
13918
13919
13920
13921
13922
13923
13924
13925
13926
13927
13928
13929
13930
13931
13932
13933
13934
13935
13936
13937
13938
13939
13940
13941
13942
13943
13944
13945
13946
13947
13948
13949
13950
13951
13952
13953
13954
13955
13956
13957
13958
13959
13960
13961
13962
13963
13964
13965
13966
13967
13968
13969
13970
13971
13972
13973
13974
13975
13976
13977
13978
13979
13980
13981
13982
13983
13984
13985
13986
13987
13988
13989
13990
13991
13992
13993
13994
13995
13996
13997
13998
13999
14000
14001
14002
14003
14004
14005
14006
14007
14008
14009
14010
14011
14012
14013
14014
14015
14016
14017
14018
14019
14020
14021
14022
14023
14024
14025
14026
14027
14028
14029
14030
14031
14032
14033
14034
14035
14036
14037
14038
14039
14040
14041
14042
14043
14044
14045
14046
14047
14048
14049
14050
14051
14052
14053
14054
14055
14056
14057
14058
14059
14060
14061
14062
14063
14064
14065
14066
14067
14068
14069
14070
14071
14072
14073
14074
14075
14076
14077
14078
14079
14080
14081
14082
14083
14084
14085
14086
14087
14088
14089
14090
14091
14092
14093
14094
14095
14096
14097
14098
14099
14100
14101
14102
14103
14104
14105
14106
14107
14108
14109
14110
14111
14112
14113
14114
14115
14116
14117
14118
14119
14120
14121
14122
14123
14124
14125
14126
14127
14128
14129
14130
14131
14132
14133
14134
14135
14136
14137
14138
14139
14140
14141
14142
14143
14144
14145
14146
14147
14148
14149
14150
14151
14152
14153
14154
14155
14156
14157
14158
14159
14160
14161
14162
14163
14164
14165
14166
14167
14168
14169
14170
14171
14172
14173
14174
14175
14176
14177
14178
14179
14180
14181
14182
14183
14184
14185
14186
14187
14188
14189
14190
14191
14192
14193
14194
14195
14196
14197
14198
14199
14200
14201
14202
14203
14204
14205
14206
14207
14208
14209
14210
14211
14212
14213
14214
14215
14216
14217
14218
14219
14220
14221
14222
14223
14224
14225
14226
14227
14228
14229
14230
14231
14232
14233
14234
14235
14236
14237
14238
14239
14240
14241
14242
14243
14244
14245
14246
14247
14248
14249
14250
14251
14252
14253
14254
14255
14256
14257
14258
14259
14260
14261
14262
14263
14264
14265
14266
14267
14268
14269
14270
14271
14272
14273
14274
14275
14276
14277
14278
14279
14280
14281
14282
14283
14284
14285
14286
14287
14288
14289
14290
14291
14292
14293
14294
14295
14296
14297
14298
14299
14300
14301
14302
14303
14304
14305
14306
14307
14308
14309
14310
14311
14312
14313
14314
14315
14316
14317
14318
14319
14320
14321
14322
14323
14324
14325
14326
14327
14328
14329
14330
14331
14332
14333
14334
14335
14336
14337
14338
14339
14340
14341
14342
14343
14344
14345
14346
14347
14348
14349
14350
14351
14352
14353
14354
14355
14356
14357
14358
14359
14360
14361
14362
14363
14364
14365
14366
14367
14368
14369
14370
14371
14372
14373
14374
14375
14376
14377
14378
14379
14380
14381
14382
14383
14384
14385
14386
14387
14388
14389
14390
14391
14392
14393
14394
14395
14396
14397
14398
14399
14400
14401
14402
14403
14404
14405
14406
14407
14408
14409
14410
14411
14412
14413
14414
14415
14416
14417
14418
14419
14420
14421
14422
14423
14424
14425
14426
14427
14428
14429
14430
14431
14432
14433
14434
14435
14436
14437
14438
14439
14440
14441
14442
14443
14444
14445
14446
14447
14448
14449
14450
14451
14452
14453
14454
14455
14456
14457
14458
14459
14460
14461
14462
14463
14464
14465
14466
14467
14468
14469
14470
14471
14472
14473
14474
14475
14476
14477
14478
14479
14480
14481
14482
14483
14484
14485
14486
14487
14488
14489
14490
14491
14492
14493
14494
14495
14496
14497
14498
14499
14500
14501
14502
14503
14504
14505
14506
14507
14508
14509
14510
14511
14512
14513
14514
14515
14516
14517
14518
14519
14520
14521
14522
14523
14524
14525
14526
14527
14528
14529
14530
14531
14532
14533
14534
14535
14536
14537
14538
14539
14540
14541
14542
14543
14544
14545
14546
14547
14548
14549
14550
14551
14552
14553
14554
14555
14556
14557
14558
14559
14560
14561
14562
14563
14564
14565
14566
14567
14568
14569
14570
14571
14572
14573
14574
14575
14576
14577
14578
14579
14580
14581
14582
14583
14584
14585
14586
14587
14588
14589
14590
14591
14592
14593
14594
14595
14596
14597
14598
14599
14600
14601
14602
14603
14604
14605
14606
14607
14608
14609
14610
14611
14612
14613
14614
14615
14616
14617
14618
14619
14620
14621
14622
14623
14624
14625
14626
14627
14628
14629
14630
14631
14632
14633
14634
14635
14636
14637
14638
14639
14640
14641
14642
14643
14644
14645
14646
14647
14648
14649
14650
14651
14652
14653
14654
14655
14656
14657
14658
14659
14660
14661
14662
14663
14664
14665
14666
14667
14668
14669
14670
14671
14672
14673
14674
14675
14676
14677
14678
14679
14680
14681
14682
14683
14684
14685
14686
14687
14688
14689
14690
14691
14692
14693
14694
14695
14696
14697
14698
14699
14700
14701
14702
14703
14704
14705
14706
14707
14708
14709
14710
14711
14712
14713
14714
14715
14716
14717
14718
14719
14720
14721
14722
14723
14724
14725
14726
14727
14728
14729
14730
14731
14732
14733
14734
14735
14736
14737
14738
14739
14740
14741
14742
14743
14744
14745
14746
14747
14748
14749
14750
14751
14752
14753
14754
14755
14756
14757
14758
14759
14760
14761
14762
14763
14764
14765
14766
14767
14768
14769
14770
14771
14772
14773
14774
14775
14776
14777
14778
14779
14780
14781
14782
14783
14784
14785
14786
14787
14788
14789
14790
14791
14792
14793
14794
14795
14796
14797
14798
14799
14800
14801
14802
14803
14804
14805
14806
14807
14808
14809
14810
14811
14812
14813
14814
14815
14816
14817
14818
14819
14820
14821
14822
14823
14824
14825
14826
14827
14828
14829
14830
14831
14832
14833
14834
14835
14836
14837
14838
14839
14840
14841
14842
14843
14844
14845
14846
14847
14848
14849
14850
14851
14852
14853
14854
14855
14856
14857
14858
14859
14860
14861
14862
14863
14864
14865
14866
14867
14868
14869
14870
14871
14872
14873
14874
14875
14876
14877
14878
14879
14880
14881
14882
14883
14884
14885
14886
14887
14888
14889
14890
14891
14892
14893
14894
14895
14896
14897
14898
14899
14900
14901
14902
14903
14904
14905
14906
14907
14908
14909
14910
14911
14912
14913
14914
14915
14916
14917
14918
14919
14920
14921
14922
14923
14924
14925
14926
14927
14928
14929
14930
14931
14932
14933
14934
14935
14936
14937
14938
14939
14940
14941
14942
14943
14944
14945
14946
14947
14948
14949
14950
14951
14952
14953
14954
14955
14956
14957
14958
14959
14960
14961
14962
14963
14964
14965
14966
14967
14968
14969
14970
14971
14972
14973
14974
14975
14976
14977
14978
14979
14980
14981
14982
14983
14984
14985
14986
14987
14988
14989
14990
14991
14992
14993
14994
14995
14996
14997
14998
14999
15000
15001
15002
15003
15004
15005
15006
15007
15008
15009
15010
15011
15012
15013
15014
15015
15016
15017
15018
15019
15020
15021
15022
15023
15024
15025
15026
15027
15028
15029
15030
15031
15032
15033
15034
15035
15036
15037
15038
15039
15040
15041
15042
15043
15044
15045
15046
15047
15048
15049
15050
15051
15052
15053
15054
15055
15056
15057
15058
15059
15060
15061
15062
15063
15064
15065
15066
15067
15068
15069
15070
15071
15072
15073
15074
15075
15076
15077
15078
15079
15080
15081
15082
15083
15084
15085
15086
15087
15088
15089
15090
15091
15092
15093
15094
15095
15096
15097
15098
15099
15100
15101
15102
15103
15104
15105
15106
15107
15108
15109
15110
15111
15112
15113
15114
15115
15116
15117
15118
15119
15120
15121
15122
15123
15124
15125
15126
15127
15128
15129
15130
15131
15132
15133
15134
15135
15136
15137
15138
15139
15140
15141
15142
15143
15144
15145
15146
15147
15148
15149
15150
15151
15152
15153
15154
15155
15156
15157
15158
15159
15160
15161
15162
15163
15164
15165
15166
15167
15168
15169
15170
15171
15172
15173
15174
15175
15176
15177
15178
15179
15180
15181
15182
15183
15184
15185
15186
15187
15188
15189
15190
15191
15192
15193
15194
15195
15196
15197
15198
15199
15200
15201
15202
15203
15204
15205
15206
15207
15208
15209
15210
15211
15212
15213
15214
15215
15216
15217
15218
15219
15220
15221
15222
15223
15224
15225
15226
15227
15228
15229
15230
15231
15232
15233
15234
15235
15236
15237
15238
15239
15240
15241
15242
15243
15244
15245
15246
15247
15248
15249
15250
15251
15252
15253
15254
15255
15256
15257
15258
15259
15260
15261
15262
15263
15264
15265
15266
15267
15268
15269
15270
15271
15272
15273
15274
15275
15276
15277
15278
15279
15280
15281
15282
15283
15284
15285
15286
15287
15288
15289
15290
15291
15292
15293
15294
15295
15296
15297
15298
15299
15300
15301
15302
15303
15304
15305
15306
15307
15308
15309
15310
15311
15312
15313
15314
15315
15316
15317
15318
15319
15320
15321
15322
15323
15324
15325
15326
15327
15328
15329
15330
15331
15332
15333
15334
15335
15336
15337
15338
15339
15340
15341
15342
15343
15344
15345
15346
15347
15348
15349
15350
15351
15352
15353
15354
15355
15356
15357
15358
15359
15360
15361
15362
15363
15364
15365
15366
15367
15368
15369
15370
15371
15372
15373
15374
15375
15376
15377
15378
15379
15380
15381
15382
15383
15384
15385
15386
15387
15388
15389
15390
15391
15392
15393
15394
15395
15396
15397
15398
15399
15400
15401
15402
15403
15404
15405
15406
15407
15408
15409
15410
15411
15412
15413
15414
15415
15416
15417
15418
15419
15420
15421
15422
15423
15424
15425
15426
15427
15428
15429
15430
15431
15432
15433
15434
15435
15436
15437
15438
15439
15440
15441
15442
15443
15444
15445
15446
15447
15448
15449
15450
15451
15452
15453
15454
15455
15456
15457
15458
15459
15460
15461
15462
15463
15464
15465
15466
15467
15468
15469
15470
15471
15472
15473
15474
15475
15476
15477
15478
15479
15480
15481
15482
15483
15484
15485
15486
15487
15488
15489
15490
15491
15492
15493
15494
15495
15496
15497
15498
15499
15500
15501
15502
15503
15504
15505
15506
15507
15508
15509
15510
15511
15512
15513
15514
15515
15516
15517
15518
15519
15520
15521
15522
15523
15524
15525
15526
15527
15528
15529
15530
15531
15532
15533
15534
15535
15536
15537
15538
15539
15540
15541
15542
15543
15544
15545
15546
15547
15548
15549
15550
15551
15552
15553
15554
15555
15556
15557
15558
15559
15560
15561
15562
15563
15564
15565
15566
15567
15568
15569
15570
15571
15572
15573
15574
15575
15576
15577
15578
15579
15580
15581
15582
15583
15584
15585
15586
15587
15588
15589
15590
15591
15592
15593
15594
15595
15596
15597
15598
15599
15600
15601
15602
15603
15604
15605
15606
15607
15608
15609
15610
15611
15612
15613
15614
15615
15616
15617
15618
15619
15620
15621
15622
15623
15624
15625
15626
15627
15628
15629
15630
15631
15632
15633
15634
15635
15636
15637
15638
15639
15640
15641
15642
15643
15644
15645
15646
15647
15648
15649
15650
15651
15652
15653
15654
15655
15656
15657
15658
15659
15660
15661
15662
15663
15664
15665
15666
15667
15668
15669
15670
15671
15672
15673
15674
15675
15676
15677
15678
15679
15680
15681
15682
15683
15684
15685
15686
15687
15688
15689
15690
15691
15692
15693
15694
15695
15696
15697
15698
15699
15700
15701
15702
15703
15704
15705
15706
15707
15708
15709
15710
15711
15712
15713
15714
15715
15716
15717
15718
15719
15720
15721
15722
15723
15724
15725
15726
15727
15728
15729
15730
15731
15732
15733
15734
15735
15736
15737
15738
15739
15740
15741
15742
15743
15744
15745
15746
15747
15748
15749
15750
15751
15752
15753
15754
15755
15756
15757
15758
15759
15760
15761
15762
15763
15764
15765
15766
15767
15768
15769
15770
15771
15772
15773
15774
15775
15776
15777
15778
15779
15780
15781
15782
15783
15784
15785
15786
15787
15788
15789
15790
15791
15792
15793
15794
15795
15796
15797
15798
15799
15800
15801
15802
15803
15804
15805
15806
15807
15808
15809
15810
15811
15812
15813
15814
15815
15816
15817
15818
15819
15820
15821
15822
15823
15824
15825
15826
15827
15828
15829
15830
15831
15832
15833
15834
15835
15836
15837
15838
15839
15840
15841
15842
15843
15844
15845
15846
15847
15848
15849
15850
15851
15852
15853
15854
15855
15856
15857
15858
15859
15860
15861
15862
15863
15864
15865
15866
15867
15868
15869
15870
15871
15872
15873
15874
15875
15876
15877
15878
15879
15880
15881
15882
15883
15884
15885
15886
15887
15888
15889
15890
15891
15892
15893
15894
15895
15896
15897
15898
15899
15900
15901
15902
15903
15904
15905
15906
15907
15908
15909
15910
15911
15912
15913
15914
15915
15916
15917
15918
15919
15920
15921
15922
15923
15924
15925
15926
15927
15928
15929
15930
15931
15932
15933
15934
15935
15936
15937
15938
15939
15940
15941
15942
15943
15944
15945
15946
15947
15948
15949
15950
15951
15952
15953
15954
15955
15956
15957
15958
15959
15960
15961
15962
15963
15964
15965
15966
15967
15968
15969
15970
15971
15972
15973
15974
15975
15976
15977
15978
15979
15980
15981
15982
15983
15984
15985
15986
15987
15988
15989
15990
15991
15992
15993
15994
15995
15996
15997
15998
15999
16000
16001
16002
16003
16004
16005
16006
16007
16008
16009
16010
16011
16012
16013
16014
16015
16016
16017
16018
16019
16020
16021
16022
16023
16024
16025
16026
16027
16028
16029
16030
16031
16032
16033
16034
16035
16036
16037
16038
16039
16040
16041
16042
16043
16044
16045
16046
16047
16048
16049
16050
16051
16052
16053
16054
16055
16056
16057
16058
16059
16060
16061
16062
16063
16064
16065
16066
16067
16068
16069
16070
16071
16072
16073
16074
16075
16076
16077
16078
16079
16080
16081
16082
16083
16084
16085
16086
16087
16088
16089
16090
16091
16092
16093
16094
16095
16096
16097
16098
16099
16100
16101
16102
16103
16104
16105
16106
16107
16108
16109
16110
16111
16112
16113
16114
16115
16116
16117
16118
16119
16120
16121
16122
16123
16124
16125
16126
16127
16128
16129
16130
16131
16132
16133
16134
16135
16136
16137
16138
16139
16140
16141
16142
16143
16144
16145
16146
16147
16148
16149
16150
16151
16152
16153
16154
16155
16156
16157
16158
16159
16160
16161
16162
16163
16164
16165
16166
16167
16168
16169
16170
16171
16172
16173
16174
16175
16176
16177
16178
16179
16180
16181
16182
16183
16184
16185
16186
16187
16188
16189
16190
16191
16192
16193
16194
16195
16196
16197
16198
16199
16200
16201
16202
16203
16204
16205
16206
16207
16208
16209
16210
16211
16212
16213
16214
16215
16216
16217
16218
16219
16220
16221
16222
16223
16224
16225
16226
16227
16228
16229
16230
16231
16232
16233
16234
16235
16236
16237
16238
16239
16240
16241
16242
16243
16244
16245
16246
16247
16248
16249
16250
16251
16252
16253
16254
16255
16256
16257
16258
16259
16260
16261
16262
16263
16264
16265
16266
16267
16268
16269
16270
16271
16272
16273
16274
16275
16276
16277
16278
16279
16280
16281
16282
16283
16284
16285
16286
16287
16288
16289
16290
16291
16292
16293
16294
16295
16296
16297
16298
16299
16300
16301
16302
16303
16304
16305
16306
16307
16308
16309
16310
16311
16312
16313
16314
16315
16316
16317
16318
16319
16320
16321
16322
16323
16324
16325
16326
16327
16328
16329
16330
16331
16332
16333
16334
16335
16336
16337
16338
16339
16340
16341
16342
16343
16344
16345
16346
16347
16348
16349
16350
16351
16352
16353
16354
16355
16356
16357
16358
16359
16360
16361
16362
16363
16364
16365
16366
16367
16368
16369
16370
16371
16372
16373
16374
16375
16376
16377
16378
16379
16380
16381
16382
16383
16384
16385
16386
16387
16388
16389
16390
16391
16392
16393
16394
16395
16396
16397
16398
16399
16400
16401
16402
16403
16404
16405
16406
16407
16408
16409
16410
16411
16412
16413
16414
16415
16416
16417
16418
16419
16420
16421
16422
16423
16424
16425
16426
16427
16428
16429
16430
16431
16432
16433
16434
16435
16436
16437
16438
16439
16440
16441
16442
16443
16444
16445
16446
16447
16448
16449
16450
16451
16452
16453
16454
16455
16456
16457
16458
16459
16460
16461
16462
16463
16464
16465
16466
16467
16468
16469
16470
16471
16472
16473
16474
16475
16476
16477
16478
16479
16480
16481
16482
16483
16484
16485
16486
16487
16488
16489
16490
16491
16492
16493
16494
16495
16496
16497
16498
16499
16500
16501
16502
16503
16504
16505
16506
16507
16508
16509
16510
16511
16512
16513
16514
16515
16516
16517
16518
16519
16520
16521
16522
16523
16524
16525
16526
16527
16528
16529
16530
16531
16532
16533
16534
16535
16536
16537
16538
16539
16540
16541
16542
16543
16544
16545
16546
16547
16548
16549
16550
16551
16552
16553
16554
16555
16556
16557
16558
16559
16560
16561
16562
16563
16564
16565
16566
16567
16568
16569
16570
16571
16572
16573
16574
16575
16576
16577
16578
16579
16580
16581
16582
16583
16584
16585
16586
16587
16588
16589
16590
16591
16592
16593
16594
16595
16596
16597
16598
16599
16600
16601
16602
16603
16604
16605
16606
16607
16608
16609
16610
16611
16612
16613
16614
16615
16616
16617
16618
16619
16620
16621
16622
16623
16624
16625
16626
16627
16628
16629
16630
16631
16632
16633
16634
16635
16636
16637
16638
16639
16640
16641
16642
16643
16644
16645
16646
16647
16648
16649
16650
16651
16652
16653
16654
16655
16656
16657
16658
16659
16660
16661
16662
16663
16664
16665
16666
16667
16668
16669
16670
16671
16672
16673
16674
16675
16676
16677
16678
16679
16680
16681
16682
16683
16684
16685
16686
16687
16688
16689
16690
16691
16692
16693
16694
16695
16696
16697
16698
16699
16700
16701
16702
16703
16704
16705
16706
16707
16708
16709
16710
16711
16712
16713
16714
16715
16716
16717
16718
16719
16720
16721
16722
16723
16724
16725
16726
16727
16728
16729
16730
16731
16732
16733
16734
16735
16736
16737
16738
16739
16740
16741
16742
16743
16744
16745
16746
16747
16748
16749
16750
16751
16752
16753
16754
16755
16756
16757
16758
16759
16760
16761
16762
16763
16764
16765
16766
16767
16768
16769
16770
16771
16772
16773
16774
16775
16776
16777
16778
16779
16780
16781
16782
16783
16784
16785
16786
16787
16788
16789
16790
16791
16792
16793
16794
16795
16796
16797
16798
16799
16800
16801
16802
16803
16804
16805
16806
16807
16808
16809
16810
16811
16812
16813
16814
16815
16816
16817
16818
16819
16820
16821
16822
16823
16824
16825
16826
16827
16828
16829
16830
16831
16832
16833
16834
16835
16836
16837
16838
16839
16840
16841
16842
16843
16844
16845
16846
16847
16848
16849
16850
16851
16852
16853
16854
16855
16856
16857
16858
16859
16860
16861
16862
16863
16864
16865
16866
16867
16868
16869
16870
16871
16872
16873
16874
16875
16876
16877
16878
16879
16880
16881
16882
16883
16884
16885
16886
16887
16888
16889
16890
16891
16892
16893
16894
16895
16896
16897
16898
16899
16900
16901
16902
16903
16904
16905
16906
16907
16908
16909
16910
16911
16912
16913
16914
16915
16916
16917
16918
16919
16920
16921
16922
16923
16924
16925
16926
16927
16928
16929
16930
16931
16932
16933
16934
16935
16936
16937
16938
16939
16940
16941
16942
16943
16944
16945
16946
16947
16948
16949
16950
16951
16952
16953
16954
16955
16956
16957
16958
16959
16960
16961
16962
16963
16964
16965
16966
16967
16968
16969
16970
16971
16972
16973
16974
16975
16976
16977
16978
16979
16980
16981
16982
16983
16984
16985
16986
16987
16988
16989
16990
16991
16992
16993
16994
16995
16996
16997
16998
16999
17000
17001
17002
17003
17004
17005
17006
17007
17008
17009
17010
17011
17012
17013
17014
17015
17016
17017
17018
17019
17020
17021
17022
17023
17024
17025
17026
17027
17028
17029
17030
17031
17032
17033
17034
17035
17036
17037
17038
17039
17040
17041
17042
17043
17044
17045
17046
17047
17048
17049
17050
17051
17052
17053
17054
17055
17056
17057
17058
17059
17060
17061
17062
17063
17064
17065
17066
17067
17068
17069
17070
17071
17072
17073
17074
17075
17076
17077
17078
17079
17080
17081
17082
17083
17084
17085
17086
17087
17088
17089
17090
17091
17092
17093
17094
17095
17096
17097
17098
17099
17100
17101
17102
17103
17104
17105
17106
17107
17108
17109
17110
17111
17112
17113
17114
17115
17116
17117
17118
17119
17120
17121
17122
17123
17124
17125
17126
17127
17128
17129
17130
17131
17132
17133
17134
17135
17136
17137
17138
17139
17140
17141
17142
17143
17144
17145
17146
17147
17148
17149
17150
17151
17152
17153
17154
17155
17156
17157
17158
17159
17160
17161
17162
17163
17164
17165
17166
17167
17168
17169
17170
17171
17172
17173
17174
17175
17176
17177
17178
17179
17180
17181
17182
17183
17184
17185
17186
17187
17188
17189
17190
17191
17192
17193
17194
17195
17196
17197
17198
17199
17200
17201
17202
17203
17204
17205
17206
17207
17208
17209
17210
17211
17212
17213
17214
17215
17216
17217
17218
17219
17220
17221
17222
17223
17224
17225
17226
17227
17228
17229
17230
17231
17232
17233
17234
17235
17236
17237
17238
17239
17240
17241
17242
17243
17244
17245
17246
17247
17248
17249
17250
17251
17252
17253
17254
17255
17256
17257
17258
17259
17260
17261
17262
17263
17264
17265
17266
17267
17268
17269
17270
17271
17272
17273
17274
17275
17276
17277
17278
17279
17280
17281
17282
17283
17284
17285
17286
17287
17288
17289
17290
17291
17292
17293
17294
17295
17296
17297
17298
17299
17300
17301
17302
17303
17304
17305
17306
17307
17308
17309
17310
17311
17312
17313
17314
17315
17316
17317
17318
17319
17320
17321
17322
17323
17324
17325
17326
17327
17328
17329
17330
17331
17332
17333
17334
17335
17336
17337
17338
17339
17340
17341
17342
17343
17344
17345
17346
17347
17348
17349
17350
17351
17352
17353
17354
17355
17356
17357
17358
17359
17360
17361
17362
17363
17364
17365
17366
17367
17368
17369
17370
17371
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- This file copyright Persistence of Vision Raytracer Pty. Ltd. 2009-2011 -->
<html lang="en">
<head>
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<title>Reference Section 4</title>
<link rel="StyleSheet" href="povray37.css" type="text/css">
<link rel="shortcut icon" href="favicon.ico">
<!-- NOTE: In order to help users find information about POV-Ray using web -->
<!-- search engines, we ask that you *not* let them index documentation -->
<!-- mirrors because effectively, when searching, users will get hundreds of -->
<!-- results containing the same information! For this reason, these meta tags -->
<!-- below disable archiving of this page by search engines. -->
<meta name="robots" content="noarchive">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="expires" content="0">
</head>
<body>
<div class="Page">
<!-- NavPanel Begin -->
<div class="NavPanel">
<table class="NavTable">
<tr>
<td class="FixedPanelHeading"><a title="3.4" href="#r3_4">Scene File Elements</a></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.1" href="#r3_4_1">Global Settings</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.1" href="#r3_4_1_1">ADC_Bailout</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.2" href="#r3_4_1_2">Ambient_Light</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.3" href="#r3_4_1_3">Assumed_Gamma</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.4" href="#r3_4_1_4">HF_Gray_16</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.5" href="#r3_4_1_5">Irid_Wavelength</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.6" href="#r3_4_1_6">Charset</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.7" href="#r3_4_1_7">Max_Trace_Level</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.8" href="#r3_4_1_8">Max_Intersections</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.9" href="#r3_4_1_9">Mm_Per_Unit</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.10" href="#r3_4_1_10">Number_Of_Waves</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.11" href="#r3_4_1_11">Noise_generator</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.1.12" href="#r3_4_1_12">Subsurface</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.2" href="#r3_4_2">Camera</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.2.1" href="#r3_4_2_1">Placing the Camera</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.1" href="#r3_4_2_1_1">Location and Look_At</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.2" href="#r3_4_2_1_2">The Sky Vector</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.3" href="#r3_4_2_1_3">Angles</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.4" href="#r3_4_2_1_4">The Direction Vector</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.5" href="#r3_4_2_1_5">Up and Right Vectors</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.6" href="#r3_4_2_1_6">Aspect Ratio</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.7" href="#r3_4_2_1_7">Handedness</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.1.8" href="#r3_4_2_1_8">Transforming the Camera</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.2.2" href="#r3_4_2_2">Types of Projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.1" href="#r3_4_2_2_1">Perspective projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.2" href="#r3_4_2_2_2">Orthographic projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.3" href="#r3_4_2_2_3">Mesh projection</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.2.2.3.1" href="#r3_4_2_2_3_1">Rays Per Pixel</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.2.2.3.2" href="#r3_4_2_2_3_2">Distribution Type</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.2.2.3.3" href="#r3_4_2_2_3_3">Max Distance</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.2.2.3.4" href="#r3_4_2_2_3_4">Mesh Object</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.2.2.3.5" href="#r3_4_2_2_3_5">About the Location Vector</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.2.2.3.6" href="#r3_4_2_2_3_6">About the Direction Vector</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.2.2.3.7" href="#r3_4_2_2_3_7">The Smooth Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.4" href="#r3_4_2_2_4">Fisheye projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.5" href="#r3_4_2_2_5">Ultra wide angle projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.6" href="#r3_4_2_2_6">Omnimax projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.7" href="#r3_4_2_2_7">Panoramic projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.8" href="#r3_4_2_2_8">Cylindrical projection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.2.2.9" href="#r3_4_2_2_9">Spherical projection</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.2.3" href="#r3_4_2_3">Focal Blur</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.2.4" href="#r3_4_2_4">Camera Ray Perturbation</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.2.5" href="#r3_4_2_5">Camera Identifiers</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.3" href="#r3_4_3">Atmospheric Effects</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.3.1" href="#r3_4_3_1">Atmospheric Media</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.3.2" href="#r3_4_3_2">Background</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.3.3" href="#r3_4_3_3">Fog</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.3.4" href="#r3_4_3_4">Sky Sphere</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.3.5" href="#r3_4_3_5">Rainbow</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.4" href="#r3_4_4">Lighting Types</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.4.1" href="#r3_4_4_1">Light Source</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.1" href="#r3_4_4_1_1">Point Lights</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.2" href="#r3_4_4_1_2">Spotlights</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.3" href="#r3_4_4_1_3">Cylindrical Lights</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.4" href="#r3_4_4_1_4">Parallel Lights</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.5" href="#r3_4_4_1_5">Area Lights</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.6" href="#r3_4_4_1_6">Shadowless Lights</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.7" href="#r3_4_4_1_7">Looks_like</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.8" href="#r3_4_4_1_8">Projected_Through</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.9" href="#r3_4_4_1_9">Light Fading</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.10" href="#r3_4_4_1_10">Atmospheric Media Interaction</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.1.11" href="#r3_4_4_1_11">Atmospheric Attenuation</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.4.2" href="#r3_4_4_2">Light Group</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.4.3" href="#r3_4_4_3">Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.3.1" href="#r3_4_4_3_1">Radiosity Basics</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.3.2" href="#r3_4_4_3_2">How Radiosity Works</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.3.3" href="#r3_4_4_3_3">Adjusting Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.1" href="#r3_4_4_3_3_1">adc_bailout</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.2" href="#r3_4_4_3_3_2">always_sample</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.3" href="#r3_4_4_3_3_3">brightness</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.4" href="#r3_4_4_3_3_4">count</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.5" href="#r3_4_4_3_3_5">error_bound</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.6" href="#r3_4_4_3_3_6">gray_threshold</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.7" href="#r3_4_4_3_3_7">low_error_factor</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.8" href="#r3_4_4_3_3_8">max_sample</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.9" href="#r3_4_4_3_3_9">maximum_reuse</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.10" href="#r3_4_4_3_3_10">minimum_reuse</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.11" href="#r3_4_4_3_3_11">nearest_count</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.12" href="#r3_4_4_3_3_12">pretrace_start and pretrace_end</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.3.13" href="#r3_4_4_3_3_13">recursion_limit</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.3.4" href="#r3_4_4_3_4">Configuring Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.4.1" href="#r3_4_4_3_4_1">Importance</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.4.2" href="#r3_4_4_3_4_2">Media and Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.4.3" href="#r3_4_4_3_4_3">No Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.4.4" href="#r3_4_4_3_4_4">Normal and Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.4.5" href="#r3_4_4_3_4_5">Save and Load Radiosity Data</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.3.4.6" href="#r3_4_4_3_4_6">Subsurface and Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.3.5" href="#r3_4_4_3_5">Tips on Radiosity</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.4.4" href="#r3_4_4_4">Photons</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.1" href="#r3_4_4_4_1">Examples</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.2" href="#r3_4_4_4_2">Using Photon Mapping in Your Scene</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.3" href="#r3_4_4_4_3">Photon Global Settings</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.4" href="#r3_4_4_4_4">Shooting Photons at an Object</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.5" href="#r3_4_4_4_5">Photons and Light Sources</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.6" href="#r3_4_4_4_6">Photons and Media</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.7" href="#r3_4_4_4_7">Photons FAQ</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.8" href="#r3_4_4_4_8">Photon Tips</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.4.4.9" href="#r3_4_4_4_9">Advanced Techniques</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.4.9.1" href="#r3_4_4_4_9_1">Autostop</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.4.9.2" href="#r3_4_4_4_9_2">Adaptive Search Radius</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.4.9.3" href="#r3_4_4_4_9_3">Photons and Dispersion</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.4.4.9.4" href="#r3_4_4_4_9_4">Saving and Loading Photon Maps</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.5" href="#r3_4_5">Object</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.5.1" href="#r3_4_5_1">Finite Solid Primitives</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.1" href="#r3_4_5_1_1">Blob</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.2" href="#r3_4_5_1_2">Box</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.3" href="#r3_4_5_1_3">Cone</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.4" href="#r3_4_5_1_4">Cylinder</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.5" href="#r3_4_5_1_5">Height Field</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.6" href="#r3_4_5_1_6">Isosurface</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.7" href="#r3_4_5_1_7">Julia Fractal</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.8" href="#r3_4_5_1_8">Lathe</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.9" href="#r3_4_5_1_9">Ovus</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.10" href="#r3_4_5_1_10">Parametric</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.11" href="#r3_4_5_1_11">Prism</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.12" href="#r3_4_5_1_12">Sphere</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.13" href="#r3_4_5_1_13">Sphere Sweep</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.14" href="#r3_4_5_1_14">Superquadric Ellipsoid</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.15" href="#r3_4_5_1_15">Surface of Revolution</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.16" href="#r3_4_5_1_16">Text</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.1.17" href="#r3_4_5_1_17">Torus</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.5.2" href="#r3_4_5_2">Finite Patch Primitives</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.2.1" href="#r3_4_5_2_1">Bicubic Patch</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.2.2" href="#r3_4_5_2_2">Disc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.2.3" href="#r3_4_5_2_3">Mesh</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.5.2.3.1" href="#r3_4_5_2_3_1">Solid Mesh</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.2.4" href="#r3_4_5_2_4">Mesh2</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.5.2.4.1" href="#r3_4_5_2_4_1">Smooth and Flat triangles in the same mesh</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.5.2.4.2" href="#r3_4_5_2_4_2">Mesh Triangle Textures</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.2.5" href="#r3_4_5_2_5">Polygon</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.2.6" href="#r3_4_5_2_6">Triangle</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.2.7" href="#r3_4_5_2_7">Smooth Triangle</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.5.3" href="#r3_4_5_3">Infinite Solid Primitives</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.3.1" href="#r3_4_5_3_1">Plane</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.3.2" href="#r3_4_5_3_2">Poly</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.3.3" href="#r3_4_5_3_3">Cubic</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.3.4" href="#r3_4_5_3_4">Quartic</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.3.5" href="#r3_4_5_3_5">Polynomial</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.3.6" href="#r3_4_5_3_6">Quadric</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.5.4" href="#r3_4_5_4">Constructive Solid Geometry</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.4.1" href="#r3_4_5_4_1">Inside and Outside</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.4.2" href="#r3_4_5_4_2">Union</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.5.4.2.1" href="#r3_4_5_4_2_1">Split_Union</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.4.3" href="#r3_4_5_4_3">Intersection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.4.4" href="#r3_4_5_4_4">Difference</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.4.5" href="#r3_4_5_4_5">Merge</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.5.5" href="#r3_4_5_5">Object Modifiers</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.1" href="#r3_4_5_5_1">Clipped By Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.2" href="#r3_4_5_5_2">Bounded By Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.3" href="#r3_4_5_5_3">Material</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.4" href="#r3_4_5_5_4">Hollow Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.5" href="#r3_4_5_5_5">Inverse Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.6" href="#r3_4_5_5_6">No Shadow Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.7" href="#r3_4_5_5_7">No Image Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.8" href="#r3_4_5_5_8">No Reflection Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.9" href="#r3_4_5_5_9">Double Illuminate Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.10" href="#r3_4_5_5_10">No Radiosity Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.5.5.11" href="#r3_4_5_5_11">Sturm Object Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.6" href="#r3_4_6">Texture</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.1" href="#r3_4_6_1">Pigment</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.1.1" href="#r3_4_6_1_1">Solid Color Pigments</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.1.2" href="#r3_4_6_1_2">Color Map</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.1.3" href="#r3_4_6_1_3">Pigment Map</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.1.4" href="#r3_4_6_1_4">Color List Pigments</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.1.5" href="#r3_4_6_1_5">Quick Color</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.2" href="#r3_4_6_2">Normal</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.2.1" href="#r3_4_6_2_1">Normal Map</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.2.2" href="#r3_4_6_2_2">Slope Map</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.2.2.1" href="#r3_4_6_2_2_1">Normals, Accuracy</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.2.3" href="#r3_4_6_2_3">Bump Map</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.2.3.1" href="#r3_4_6_2_3_1">Specifying a Bump Map</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.2.3.2" href="#r3_4_6_2_3_2">Bump_Size</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.2.3.3" href="#r3_4_6_2_3_3">Use_Index and Use_Color</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.2.4" href="#r3_4_6_2_4">Scaling normals</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.3" href="#r3_4_6_3">Finish</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.3.1" href="#r3_4_6_3_1">Ambient</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.3.2" href="#r3_4_6_3_2">Emission</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.3.3" href="#r3_4_6_3_3">Diffuse Reflection Items</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.3.3.1" href="#r3_4_6_3_3_1">Diffuse</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.3.3.2" href="#r3_4_6_3_3_2">Brilliance</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.3.3.3" href="#r3_4_6_3_3_3">Crand Graininess</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.3.3.4" href="#r3_4_6_3_3_4">Subsurface Light Transport</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.3.4" href="#r3_4_6_3_4">Highlights</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.3.4.1" href="#r3_4_6_3_4_1">Phong Highlights</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.3.4.2" href="#r3_4_6_3_4_2">Specular Highlight</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.3.4.3" href="#r3_4_6_3_4_3">Metallic Highlight Modifier</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.3.5" href="#r3_4_6_3_5">Specular Reflection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.3.6" href="#r3_4_6_3_6">Conserve Energy for Reflection</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.3.7" href="#r3_4_6_3_7">Iridescence</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.4" href="#r3_4_6_4">Halo</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.5" href="#r3_4_6_5">Patterned Textures</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.5.1" href="#r3_4_6_5_1">Texture Maps</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.5.2" href="#r3_4_6_5_2">Tiles</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.5.3" href="#r3_4_6_5_3">Material Maps</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.6.5.3.1" href="#r3_4_6_5_3_1">Specifying a Material Map</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.6" href="#r3_4_6_6">Layered Textures</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.7" href="#r3_4_6_7">UV Mapping</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.7.1" href="#r3_4_6_7_1">Supported Objects</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.6.7.2" href="#r3_4_6_7_2">UV Vectors</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.8" href="#r3_4_6_8">Triangle Texture Interpolation</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.9" href="#r3_4_6_9">Interior Texture</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.6.10" href="#r3_4_6_10">Cutaway Textures</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.7" href="#r3_4_7">Pattern</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.7.1" href="#r3_4_7_1">General Patterns</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.1" href="#r3_4_7_1_1">Agate Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.2" href="#r3_4_7_1_2">Boxed Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.3" href="#r3_4_7_1_3">Bozo Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.4" href="#r3_4_7_1_4">Brick Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.5" href="#r3_4_7_1_5">Bumps Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.6" href="#r3_4_7_1_6">Cubic Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.7" href="#r3_4_7_1_7">Cylindrical Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.8" href="#r3_4_7_1_8">Density File Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.1.8.1" href="#r3_4_7_1_8_1">df3 file format</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.9" href="#r3_4_7_1_9">Dents Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.10" href="#r3_4_7_1_10">Facets Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.11" href="#r3_4_7_1_11">Fractal Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.12" href="#r3_4_7_1_12">Function Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.1.12.1" href="#r3_4_7_1_12_1">What can be used</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.1.12.2" href="#r3_4_7_1_12_2">Function Image</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.13" href="#r3_4_7_1_13">Gradient Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.14" href="#r3_4_7_1_14">Granite Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.15" href="#r3_4_7_1_15">Leopard Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.16" href="#r3_4_7_1_16">Marble Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.17" href="#r3_4_7_1_17">Onion Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.18" href="#r3_4_7_1_18">Pavement Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.19" href="#r3_4_7_1_19">Pigment Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.20" href="#r3_4_7_1_20">Planar Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.21" href="#r3_4_7_1_21">Quilted Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.22" href="#r3_4_7_1_22">Radial Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.23" href="#r3_4_7_1_23">Ripples Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.24" href="#r3_4_7_1_24">Spherical Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.25" href="#r3_4_7_1_25">Spiral1 Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.26" href="#r3_4_7_1_26">Spiral2 Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.27" href="#r3_4_7_1_27">Spotted Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.28" href="#r3_4_7_1_28">Tiling Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.29" href="#r3_4_7_1_29">Waves Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.30" href="#r3_4_7_1_30">Wood Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.1.31" href="#r3_4_7_1_31">Wrinkles Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.7.2" href="#r3_4_7_2">Discontinuous Patterns</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.2.1" href="#r3_4_7_2_1">Cells Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.2.2" href="#r3_4_7_2_2">Checker Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.2.3" href="#r3_4_7_2_3">Crackle Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.2.4" href="#r3_4_7_2_4">Hexagon Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.2.5" href="#r3_4_7_2_5">Object Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.2.6" href="#r3_4_7_2_6">Square Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.2.7" href="#r3_4_7_2_7">Triangular Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.7.3" href="#r3_4_7_3">Normal-Dependent Patterns</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.3.1" href="#r3_4_7_3_1">Aoi Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.3.2" href="#r3_4_7_3_2">Slope Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.7.4" href="#r3_4_7_4">Special Patterns</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.4.1" href="#r3_4_7_4_1">Average Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.4.2" href="#r3_4_7_4_2">Image Pattern</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.7.5" href="#r3_4_7_5">Pattern Modifiers</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.5.1" href="#r3_4_7_5_1">Transforming Patterns</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.5.2" href="#r3_4_7_5_2">Frequency and Phase</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.5.3" href="#r3_4_7_5_3">Waveforms</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.5.4" href="#r3_4_7_5_4">Noise Generators</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.5.5" href="#r3_4_7_5_5">Warp</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.1" href="#r3_4_7_5_5_1">Black Hole Warp</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.2" href="#r3_4_7_5_5_2">Repeat Warp</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.3" href="#r3_4_7_5_5_3">Turbulence Warp</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.4" href="#r3_4_7_5_5_4">Octaves</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.5" href="#r3_4_7_5_5_5">Lambda</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.6" href="#r3_4_7_5_5_6">Omega</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.7" href="#r3_4_7_5_5_7">Mapping using warps</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.8" href="#r3_4_7_5_5_8">Turbulence versus Turbulence Warp</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.7.5.5.9" href="#r3_4_7_5_5_9">Turbulence</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.7.6" href="#r3_4_7_6">Image Map</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.6.1" href="#r3_4_7_6_1">Specifying an Image Map</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.6.2" href="#r3_4_7_6_2">The Gamma Option</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.6.3" href="#r3_4_7_6_3">The Filter and Transmit Bitmap Modifiers</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.6.4" href="#r3_4_7_6_4">Using the Alpha Channel</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.7.7" href="#r3_4_7_7">Bitmap Modifiers</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.7.1" href="#r3_4_7_7_1">The once Option</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.7.2" href="#r3_4_7_7_2">The map_type Option</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.7.7.3" href="#r3_4_7_7_3">The interpolate Option</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.8" href="#r3_4_8">Media</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.8.1" href="#r3_4_8_1">Interior</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.1" href="#r3_4_8_1_1">Why are Interior and Media Necessary?</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.2" href="#r3_4_8_1_2">Empty and Solid Objects</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.3" href="#r3_4_8_1_3">Scaling objects with an interior</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.4" href="#r3_4_8_1_4">Refraction</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.5" href="#r3_4_8_1_5">Dispersion</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.8.1.5.1" href="#r3_4_8_1_5_1">Dispersion & Caustics</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.6" href="#r3_4_8_1_6">Attenuation</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.7" href="#r3_4_8_1_7">Simulated Caustics</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.1.8" href="#r3_4_8_1_8">Object-Media</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.8.2" href="#r3_4_8_2">Media Types</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.2.1" href="#r3_4_8_2_1">Absorption</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.2.2" href="#r3_4_8_2_2">Emission</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.2.3" href="#r3_4_8_2_3">Scattering</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.8.3" href="#r3_4_8_3">Sampling Parameters & Methods</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.8.4" href="#r3_4_8_4">Density</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.4.1" href="#r3_4_8_4_1">General Density Modifiers</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.4.2" href="#r3_4_8_4_2">Density with color_map</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.4.3" href="#r3_4_8_4_3">Density Maps and Density Lists</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.8.4.4" href="#r3_4_8_4_4">Multiple Density vs. Multiple Media</a></div></td>
</tr>
<tr>
<td><div class="divh2"><strong><a title="3.4.9" href="#r3_4_9">Include Files</a></strong></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.9.1" href="#r3_4_9_1">Main Files</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.1" href="#r3_4_9_1_1">Arrays.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.2" href="#r3_4_9_1_2">Chars.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.3" href="#r3_4_9_1_3">Colors.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.3.1" href="#r3_4_9_1_3_1">Predefined colors</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.3.2" href="#r3_4_9_1_3_2">Color macros</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.4" href="#r3_4_9_1_4">Consts.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.1" href="#r3_4_9_1_4_1">Vector constants</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.2" href="#r3_4_9_1_4_2">Map type constants</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.3" href="#r3_4_9_1_4_3">Interpolation type constants</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.4" href="#r3_4_9_1_4_4">Fog type constants</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.5" href="#r3_4_9_1_4_5">Focal blur hexgrid constants</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.6" href="#r3_4_9_1_4_6">IORs</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.7" href="#r3_4_9_1_4_7">Dispersion amounts</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.4.8" href="#r3_4_9_1_4_8">Scattering media type constants</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.5" href="#r3_4_9_1_5">Debug.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.6" href="#r3_4_9_1_6">Finish.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.7" href="#r3_4_9_1_7">Functions.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.1" href="#r3_4_9_1_7_1">Common Parameters</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.2" href="#r3_4_9_1_7_2">Cross Section Type</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.3" href="#r3_4_9_1_7_3">Field Strength</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.4" href="#r3_4_9_1_7_4">Field Limit</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.5" href="#r3_4_9_1_7_5">SOR Switch</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.6" href="#r3_4_9_1_7_6">SOR Offset</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.7" href="#r3_4_9_1_7_7">SOR Angle</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.8" href="#r3_4_9_1_7_8">Invert Isosurface</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.9" href="#r3_4_9_1_7_9">Internal Functions</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.10" href="#r3_4_9_1_7_10">Pre defined functions</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.7.11" href="#r3_4_9_1_7_11">Pattern functions</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.8" href="#r3_4_9_1_8">Glass.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.8.1" href="#r3_4_9_1_8_1">Glass colors (with transparency)</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.8.2" href="#r3_4_9_1_8_2">Glass colors (without transparency, for fade_color)</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.8.3" href="#r3_4_9_1_8_3">Glass finishes</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.8.4" href="#r3_4_9_1_8_4">Glass interiors</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.8.5" href="#r3_4_9_1_8_5">Glass interior macros</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.9" href="#r3_4_9_1_9">Golds.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.10" href="#r3_4_9_1_10">Logo.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.11" href="#r3_4_9_1_11">Makegrass.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.12" href="#r3_4_9_1_12">Math.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.12.1" href="#r3_4_9_1_12_1">Float functions and macros</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.12.2" href="#r3_4_9_1_12_2">Vector functions and macros</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.12.3" href="#r3_4_9_1_12_3">Vector Analysis</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.13" href="#r3_4_9_1_13">Meshmaker.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.14" href="#r3_4_9_1_14">Metals.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.15" href="#r3_4_9_1_15">Rad_def.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.16" href="#r3_4_9_1_16">Rand.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.16.1" href="#r3_4_9_1_16_1">Flat Distributions</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.16.2" href="#r3_4_9_1_16_2">Other Distributions</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.16.3" href="#r3_4_9_1_16_3">Continuous Symmetric Distributions</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.16.4" href="#r3_4_9_1_16_4">Continuous Skewed Distributions</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.16.5" href="#r3_4_9_1_16_5">Discrete Distributions </a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.17" href="#r3_4_9_1_17">Screen.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.18" href="#r3_4_9_1_18">Shapes.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.18.1" href="#r3_4_9_1_18_1">The HF Macros</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.19" href="#r3_4_9_1_19">Shapes2.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.20" href="#r3_4_9_1_20">Shapes3.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.21" href="#r3_4_9_1_21">Shapesq.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.22" href="#r3_4_9_1_22">Skies.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.23" href="#r3_4_9_1_23">Stars.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.24" href="#r3_4_9_1_24">Stones.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.25" href="#r3_4_9_1_25">Stdinc.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.26" href="#r3_4_9_1_26">Strings.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.27" href="#r3_4_9_1_27">Sunpos.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.28" href="#r3_4_9_1_28">Textures.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.28.1" href="#r3_4_9_1_28_1">Stones</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.28.2" href="#r3_4_9_1_28_2">Skies</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.28.3" href="#r3_4_9_1_28_3">Woods</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.28.4" href="#r3_4_9_1_28_4">Glass</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.28.5" href="#r3_4_9_1_28_5">Metals</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.28.6" href="#r3_4_9_1_28_6">Special textures</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.1.28.7" href="#r3_4_9_1_28_7">Texture and pattern macros</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.29" href="#r3_4_9_1_29">Transforms.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.30" href="#r3_4_9_1_30">Woods.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.1.31" href="#r3_4_9_1_31">Woodmaps.inc</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.9.2" href="#r3_4_9_2">Old Files</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.2.1" href="#r3_4_9_2_1">Glass_old.inc</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.2.1.1" href="#r3_4_9_2_1_1">Glass finishes</a></div></td>
</tr>
<tr>
<td><div class="divh5"><a title="3.4.9.2.1.2" href="#r3_4_9_2_1_2">Glass textures</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.2.2" href="#r3_4_9_2_2">Shapes_old.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.2.3" href="#r3_4_9_2_3">Stage1.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.2.4" href="#r3_4_9_2_4">Stdcam.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.2.5" href="#r3_4_9_2_5">Stones1.inc</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.2.6" href="#r3_4_9_2_6">Stones2.inc</a></div></td>
</tr>
<tr>
<td><div class="divh3"><a title="3.4.9.3" href="#r3_4_9_3">Other Files</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.3.1" href="#r3_4_9_3_1">Font Files</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.3.2" href="#r3_4_9_3_2">Color Map Files</a></div></td>
</tr>
<tr>
<td><div class="divh4"><a title="3.4.9.3.3" href="#r3_4_9_3_3">Image Files</a></div></td>
</tr>
<tr>
<td><div class="divh1"> </div></td>
</tr>
<tr>
<td><div class="divh1"> </div></td>
</tr>
</table>
</div>
<!-- NavPanel End -->
<div class="Content">
<table class="HeaderFooter" width="100%">
<tr>
<td colspan=5 align="left" class="HeaderFooter">
POV-Ray for Unix <strong class="HeaderFooter">version 3.7</strong>
</td>
</tr>
<tr >
<td colspan=5>
<hr align="right" width="70%">
</td>
</tr>
<tr>
<td width="30%"></td>
<td class="NavBar"><a href="index.html" title="The Front Door">Home</a></td>
<td class="NavBar"><a href="u1_0.html" title="Unix Table of Contents">POV-Ray for Unix</a></td>
<td class="NavBar"><a href="t2_0.html" title="Tutorial Table of Contents">POV-Ray Tutorial</a></td>
<td class="NavBar"><a href="r3_0.html" title="Reference Table of Contents">POV-Ray Reference</a></td>
</tr>
</table>
<a name="r3_4"></a>
<div class="content-level-h2" contains="Scene File Elements" id="r3_4">
<h2>3.4 Scene File Elements</h2>
<p>This section details settings, camera types, objects, and textures used in POV-Ray scene files. It is divided into the following sub-sections:</p>
<ol>
<li><a href="r3_4.html#r3_4_1">Global Settings</a></li>
<li><a href="r3_4.html#r3_4_2">Camera</a></li>
<li><a href="r3_4.html#r3_4_3">Atmospheric Effects</a></li>
<li><a href="r3_4.html#r3_4_4">LightingTypes</a></li>
<li><a href="r3_4.html#r3_4_5">Object</a></li>
<li><a href="r3_4.html#r3_4_6">Texture</a></li>
<li><a href="r3_4.html#r3_4_7">Pattern</a></li>
<li><a href="r3_4.html#r3_4_8">Media</a></li>
<li><a href="r3_4.html#r3_4_9">Include Files</a></li>
</ol></div>
<a name="r3_4_1"></a>
<div class="content-level-h3" contains="Global Settings" id="r3_4_1">
<h3>3.4.1 Global Settings</h3>
<p>The <code>global_settings</code> statement is a catch-all statement that
gathers together a number of global parameters. The statement may appear
anywhere in a scene as long as it is not inside any other statement. You may
have multiple <code>global_settings</code> statements in a scene. Whatever
values were specified in the last <code>global_settings</code> statement
override any previous settings.</p>
<p class="Note"><strong>Note:</strong> Some items which were language directives in earlier versions of
POV-Ray have been moved inside the <code>global_settings</code> statement so
that it is more obvious to the user that their effect is global. The old
syntax is permitted but generates a warning.</p>
<p> The new syntax is:</p>
<pre>
GLOBAL_SETTINGS:
global_settings { [GLOBAL_SETTINGS_ITEMS...] }
GLOBAL_SETTINGS_ITEM:
adc_bailout Value | ambient_light COLOR | assumed_gamma GAMMA_VALUE |
hf_gray_16 [Bool] | irid_wavelength COLOR | charset GLOBAL_CHARSET |
max_intersections Number | max_trace_level Number |
mm_per_unit Number | number_of_waves Number | noise_generator Number |
radiosity { RADIOSITY_ITEMS... } | subsurface { SUBSURFACE_ITEMS } |
photon { PHOTON_ITEMS... }
GLOBAL_CHARSET:
ascii | utf8 | sys
GAMMA_VALUE:
Value | srgb
</pre>
<p>Global setting default values:</p>
<pre>
charset : ascii
adc_bailout : 1/255
ambient_light : <1,1,1>
assumed_gamma : 1.0 (undefined for legacy scenes)
hf_gray_16 : deprecated
irid_wavelength : <0.25,0.18,0.14>
max_trace_level : 5
max_intersections : 64
mm_per_unit : 10
number_of_waves : 10
noise_generator : 2
Radiosity:
adc_bailout : 0.01
always_sample : off
brightness : 1.0
count : 35 (supports adaptive mode)
error_bound : 1.8
gray_threshold : 0.0
low_error_factor : 0.5
max_sample : non-positive value
maximum_reuse : 0.2
minimum_reuse : 0.015
nearest_count : 5 (max = 20; supports adaptive mode)
normal : off
pretrace_start : 0.08
pretrace_end : 0.04
recursion_limit : 2
subsurface : off
Subsurface:
radiosity : off
samples : 50,50
</pre>
<p>Each item is optional and may appear in any order. If an item is specified
more than once, the last setting overrides previous values. Details on each
item are given in the following sections.</p>
</div>
<a name="r3_4_1_1"></a>
<div class="content-level-h4" contains="ADC_Bailout" id="r3_4_1_1">
<h4>3.4.1.1 ADC_Bailout</h4>
<p>In scenes with many reflective and transparent surfaces, POV-Ray can get
bogged down tracing multiple reflections and refractions that contribute very
little to the color of a particular pixel. The program uses a system called
<em>Adaptive Depth Control</em> (ADC) to stop computing additional reflected
or refracted rays when their contribution is insignificant.</p>
<p>
You may use the global setting <code>adc_bailout</code> keyword followed by
float value to specify the point at which a ray's contribution is
considered insignificant. For example:</p>
<pre>
global_settings { adc_bailout 0.01 }
</pre>
<p>The default value is 1/255, or approximately 0.0039, since a change
smaller than that could not be visible in a 24 bit image. Generally this
setting is perfectly adequate and should be left alone. Setting
<code>adc_bailout</code> to 0 will disable ADC, relying completely on
<code>max_trace_level</code> to set an upper limit on the number of rays spawned.</p>
<p>
See the section <a href="r3_4.html#r3_4_1_7">Max_Trace_Level</a> for details on how ADC and <code>max_trace_level</code> interact.</p>
</div>
<a name="r3_4_1_2"></a>
<div class="content-level-h4" contains="Ambient_Light" id="r3_4_1_2">
<h4>3.4.1.2 Ambient_Light</h4>
<p>Ambient light is used to simulate the effect of inter-diffuse reflection
that is responsible for lighting areas that partially or completely lie in
shadow. POV-Ray provides the <code>ambient_light</code> keyword to let you
easily change the brightness of the ambient lighting without changing every
ambient value in all finish statements. It also lets you create interesting
effects by changing the color of the ambient light source. The syntax is:</p>
<pre>
global_settings { ambient_light COLOR }
</pre>
<p>The default is a white ambient light source set at <code>rgb
<1,1,1></code>. Only the rgb components are used. The actual ambient
used is: <em>Ambient = Finish_Ambient * Global_Ambient</em>.</p>
<p>
See the section <a href="r3_4.html#r3_4_6_3_1">Ambient</a> for more information.</p>
</div>
<a name="r3_4_1_3"></a>
<div class="content-level-h4" contains="Assumed_Gamma" id="r3_4_1_3">
<h4>3.4.1.3 Assumed_Gamma</h4>
<p>The <code>assumed_gamma</code> statement specifies a dsiplay gamma for which all color literals in the scene are presumed to be pre-corrected; at the same time it also defines the <em>working gamma space</em> in which POV-Ray will perform all its color computations.</p>
<p class="Note"><strong>Note:</strong> Using any value other than 1.0 will produce physically inaccurate results. Furthermore, if you decide to go for a different value for convenience, it is highly recommended to set this value to the same as your <code>Display_Gamma</code>. Using this parameter for artistic purposes is strongly discouraged.</p>
<p class="Note"><strong>Note:</strong> As of POV-Ray 3.7 this keyword is considered mandatory (except in legacy scenes) and consequently enables the <em>experimental</em> gamma handling feature. Future versions of POV-Ray may treat the absence of this keyword in non-legacy scenes as an error.</p>
<p>See section <a href="t2_3.html#t2_3_4">Gamma Handling</a> for more information about gamma.</p>
</div>
<a name="r3_4_1_4"></a>
<div class="content-level-h4" contains="HF_Gray_16" id="r3_4_1_4">
<h4>3.4.1.4 HF_Gray_16</h4>
<p>Grayscale output can be used to generate heightfields for use in other POV-Ray scenes, and may be specified via <code>Grayscale_Output=true</code> as an INI option, or <code>+Fxg</code> (for output type 'x') as a command-line option. For example, <code>+Fng</code> for PNG and <code>+Fpg</code> for PPM (effectively PGM) grayscale output. By default this option is off.</p>
<p class="Note"><strong>Note:</strong> In version 3.7 the <code>hf_gray_16</code> keyword in the <code>global_settings</code> block has been deprecated. If encountered, it has no effect on the output type and will additionally generate a warning message.</p>
<p>With <code>Grayscale_Output=true</code>, the output file will be in the form of a heightfield, with the height at any point being dependent on the brightness of the pixel. The brightness of a pixel is calculated in the same way that color images are converted to grayscale images:<em><code> height = 0.3 * red + 0.59 * green + 0.11 * blue</code></em>.</p>
<p>
Setting the <code>Grayscale_Output=true</code> option will cause the preview display, if used, to be grayscale rather than color. This is to allow you to see how the heightfield will look because some file formats store heightfields in a way that is difficult to understand afterwards. See the section <a href="r3_4.html#r3_4_5_1_5">Height Field</a> for a description of how POV-Ray heightfields are stored for each file type.</p>
<p class="Warning"><strong>Caveat:</strong> Grayscale output implies the maximum bit-depth the format supports is 16, it is not valid to specify bits per color channel with 'g' (e.g. <code>+Fng16</code> is not allowed, and nor for that matter is <code>+Fn16g</code>). If bits per channel is provided via an INI option, it is ignored.</p>
<p>Currently PNG, and PPM are the only file formats that support grayscale output.</p>
</div>
<a name="r3_4_1_5"></a>
<div class="content-level-h4" contains="Irid_Wavelength" id="r3_4_1_5">
<h4>3.4.1.5 Irid_Wavelength</h4>
<p>Iridescence calculations depend upon the dominant wavelengths of the
primary colors of red, green and blue light. You may adjust the values using
the global setting <code>irid_wavelength</code> as follows...</p>
<pre>
global_settings { irid_wavelength COLOR }
</pre>
<p>The default value is <code>rgb <0.70,0.52,0.48></code> and any
filter or transmit values are ignored. These values are proportional to the
wavelength of light but they represent no real world units.</p>
<p>
In general, the default values should prove adequate but we provide this
option as a means to experiment with other values.</p>
</div>
<a name="r3_4_1_6"></a>
<div class="content-level-h4" contains="Charset" id="r3_4_1_6">
<h4>3.4.1.6 Charset</h4>
<p>This allows you to specify the assumed character set of all text strings.
If you specify <code>ascii</code> only standard ASCII character codes in the
range from 0 to 127 are valid. You can easily find a table of ASCII
characters on the internet. The option <code>utf8</code> is a special Unicode
text encoding and it allows you to specify characters of nearly all languages
in use today. We suggest you use a text editor with the capability to export
text to UTF8 to generate input files. You can find more information,
including tables with codes of valid characters on the
<a href="http://www.unicode.org/">Unicode website</a>
The last possible option is to use a system specific character set. For
details about the <code>sys</code> character set option refer to the platform
specific documentation.</p>
</div>
<a name="r3_4_1_7"></a>
<div class="content-level-h4" contains="Max_Trace_Level" id="r3_4_1_7">
<h4>3.4.1.7 Max_Trace_Level</h4>
<p>In scenes with many reflective and transparent surfaces POV-Ray can get
bogged down tracing multiple reflections and refractions that contribute very
little to the color of a particular pixel. The global setting <code>
max_trace_level</code> defines the integer maximum number of recursive levels
that POV-Ray will trace a ray.</p>
<pre>
global_settings { max_trace_level Level }
</pre>
<p>This is used when a ray is reflected or is passing through a transparent
object and when shadow rays are cast. When a ray hits a reflective surface,
it spawns another ray to see what that point reflects. That is trace level
one. If it hits another reflective surface another ray is spawned and it goes
to trace level two. The maximum level by default is five.</p>
<p>
One speed enhancement added to POV-Ray in version 3.0 is <em>Adaptive Depth
Control</em> (ADC). Each time a new ray is spawned as a result of reflection
or refraction its contribution to the overall color of the pixel is reduced
by the amount of reflection or the filter value of the refractive surface. At
some point this contribution can be considered to be insignificant and there
is no point in tracing any more rays. Adaptive depth control is what tracks
this contribution and makes the decision of when to bail out. On scenes that
use a lot of partially reflective or refractive surfaces this can result in a
considerable reduction in the number of rays fired and makes it safer to use
much higher <code> max_trace_level</code> values.</p>
<p>
This reduction in color contribution is a result of scaling by the
reflection amount and/or the filter values of each surface, so a perfect
mirror or perfectly clear surface will not be optimizable by ADC. You can see
the results of ADC by watching the <code> Rays Saved</code> and <code>Highest
Trace Level</code> displays on the statistics screen.</p>
<p>
The point at which a ray's contribution is considered insignificant is
controlled by the <code>adc_bailout</code> value. The default is 1/255 or
approximately 0.0039 since a change smaller than that could not be visible in
a 24 bit image. Generally this setting is perfectly adequate and should be
left alone. Setting <code><a href="r3_4.html#r3_4_1_1">adc_bailout</a></code> to 0 will disable ADC, relying
completely on <code> max_trace_level</code> to set an upper limit on the
number of rays spawned.</p>
<p>
If <code>max_trace_level</code> is reached before a non-reflecting surface
is found and if ADC has not allowed an early exit from the ray tree the
color is returned as black. Raise <code>max_trace_level</code> if you see
black areas in a reflective surface where there should be a color.</p>
<p>
The other symptom you could see is with transparent objects. For instance,
try making a union of concentric spheres with a clear texture on them. Make
ten of them in the union with radius's from 1 to 10 and render the scene.
The image will show the first few spheres correctly, then black. This is
because a new level is used every time you pass through a transparent
surface. Raise <code>max_trace_level</code> to fix this problem.</p>
<p class="Note"><strong>Note:</strong> Raising <code>max_trace_level</code> will use more memory and time
and it could cause the program to crash with a stack overflow error, although
ADC will alleviate this to a large extent.</p>
<p>Values for <code>max_trace_level</code> can be set up to a maximum of 256.
If there is no <code>max_trace_level</code> set and during rendering the default value is reached, a warning is issued.
</p>
</div>
<a name="r3_4_1_8"></a>
<div class="content-level-h4" contains="Max_Intersections" id="r3_4_1_8">
<h4>3.4.1.8 Max_Intersections</h4>
<p>POV-Ray uses a set of internal stacks to collect ray/object intersection points. The usual maximum number of entries in these <em>I-Stacks</em> is 64. Complex scenes may cause these stacks to overflow. POV-Ray does not stop but it may incorrectly render your scene. When POV-Ray finishes rendering, a number of statistics are displayed. If you see <code>I-Stack overflows</code> reported in the statistics you should increase the stack size. Add a global setting to your scene as follows:</p>
<pre>
global_settings { max_intersections Integer }
</pre>
<p>If the <code>I-Stack Overflows</code> remain increase this value until they stop.</p>
</div>
<a name="r3_4_1_9"></a>
<div class="content-level-h4" contains="Mm_Per_Unit" id="r3_4_1_9">
<h4>3.4.1.9 Mm_Per_Unit</h4>
<p>See the section <a href="r3_4.html#r3_4_6_3_3_4">Subsurface Light Transport</a> for more information about the role of <code>mm_per_unit</code> in the global settings block.</p>
</div>
<a name="r3_4_1_10"></a>
<div class="content-level-h4" contains="Number_Of_Waves" id="r3_4_1_10">
<h4>3.4.1.10 Number_Of_Waves</h4>
<p>The <code><a href="r3_4.html#r3_4_7_1_29">waves</a></code> and <code><a href="r3_4.html#r3_4_7_1_23">ripples</a></code>
patterns are generated by summing a series of waves, each with a slightly different center and size. By default, ten waves are summed but this amount can be globally controlled by changing the <code>number_of_waves</code> setting.</p>
<pre>
global_settings { number_of_waves Integer }
</pre>
<p>Changing this value affects both waves and ripples alike on all patterns in the scene.</p>
</div>
<a name="r3_4_1_11"></a>
<div class="content-level-h4" contains="Noise_generator" id="r3_4_1_11">
<h4>3.4.1.11 Noise_generator</h4>
<p> There are three noise generators implemented. </p>
<ul>
<li><code>noise_generator 1</code> the noise that was used in POV_Ray 3.1</li>
<li><code>noise_generator 2</code> 'range corrected' version of the old noise, it does not show the plateaus seen with <code>noise_generator 1</code> </li>
<li><code>noise_generator 3</code> generates Perlin noise</li>
</ul>
<p>The default is <code>noise_generator 2</code></p>
<p class="Note"><strong>Note:</strong> The noise_generators can also be used within the pigment/normal/etc. statement.</p>
</div>
<a name="r3_4_1_12"></a>
<div class="content-level-h4" contains="Subsurface" id="r3_4_1_12">
<h4>3.4.1.12 Subsurface</h4>
<p>See the section <a href="r3_4.html#r3_4_6_3_3_4">Subsurface Light Transport</a> for more information about the role of <code>subsurface</code> in the global settings block.</p></div>
<a name="r3_4_2"></a>
<div class="content-level-h3" contains="Camera" id="r3_4_2">
<h3>3.4.2 Camera</h3>
<p>The camera definition describes the position, projection type and
properties of the camera viewing the scene. Its syntax is:</p>
<pre>
CAMERA:
camera{ [CAMERA_ITEMS...] }
CAMERA_ITEMS:
CAMERA_TYPE | CAMERA_VECTOR | CAMERA_MODIFIER |
CAMERA_IDENTIFIER
CAMERA_TYPE:
perspective | orthographic | mesh_camera{MESHCAM_MODIFIERS} | fisheye | ultra_wide_angle |
omnimax | panoramic | cylinder CylinderType | spherical
CAMERA_VECTOR:
location <Location> | right <Right> | up <Up> |
direction <Direction> | sky <Sky>
CAMERA_MODIFIER:
angle HORIZONTAL [VERTICAL] | look_at <Look_At> |
blur_samples [MIN_SAMPLES,] MAX_SAMPLES | aperture Size |
focal_point <Point> | confidence Blur_Confidence |
variance Blur_Variance | [bokeh{pigment{BOKEH}}] |
NORMAL | TRANSFORMATION | [MESHCAM_SMOOTH]
MESHCAM_MODIFIERS:
rays per pixel & distribution type & [max distance] & MESH_OBJECT & [MESH_OBJECT...]
BOKEH:
a COLOR_VECTOR in the range of <0,0,0> ... <1,1,0>
MESHCAM_SMOOTH:
optional smooth modifier valid only when using mesh_camera
</pre>
<p>
Camera default values:</p>
<pre>
DEFAULT CAMERA:
camera {
perspective
location <0,0,0>
direction <0,0,1>
right 1.33*x
up y
sky <0,1,0>
}
CAMERA TYPE: perspective
angle : ~67.380 ( direction_length=0.5*
right_length/tan(angle/2) )
confidence : 0.9 (90%)
direction : <0,0,1>
focal_point: <0,0,0>
location : <0,0,0>
look_at : z
right : 1.33*x
sky : <0,1,0>
up : y
variance : 1/128
</pre>
<p>Depending on the projection type zero or more of the parameters are required:</p>
<ul>
<li>If no camera is specified the default camera is used.</li>
<li>If no projection type is given the perspective camera will be used
(pinhole camera).</li>
<li>The <em>CAMERA_TYPE</em> has to be the first item in the camera
statement.</li>
<li>Other <em>CAMERA_ITEMs</em> may legally appear in any order.</li>
<li>For other than the perspective camera, the minimum that has to be
specified is the CAMERA_TYPE, the cylindrical camera also requires the
<em>CAMERA_TYPE</em> to be followed by a float.</li>
<li>The Orthographic camera has two 'modes'. For the pure orthographic
projection up or right have to be specified. For an orthographic camera,
with the same area of view as a perspective camera at the plane which goes
through the look_at point, the angle keyword has to be use. A value for the
angle is optional.</li>
<li>All other <em>CAMERA_ITEM</em>s are taken from the default camera,
unless they are specified differently.</li>
</ul>
</div>
<a name="r3_4_2_1"></a>
<div class="content-level-h4" contains="Placing the Camera" id="r3_4_2_1">
<h4>3.4.2.1 Placing the Camera</h4>
<p>The POV-Ray camera has 9 different models and they are as follows:</p>
<ol>
<li><a href="r3_4.html#r3_4_2_2_1">perspective</a></li>
<li><a href="r3_4.html#r3_4_2_2_2">orthographic</a></li>
<li><a href="r3_4.html#r3_4_2_2_3">mesh</a></li>
<li><a href="r3_4.html#r3_4_2_2_4">fisheye</a></li>
<li><a href="r3_4.html#r3_4_2_2_5">ultra-wide angle</a></li>
<li><a href="r3_4.html#r3_4_2_2_6">onmimax</a></li>
<li><a href="r3_4.html#r3_4_2_2_7">panoramic</a></li>
<li><a href="r3_4.html#r3_4_2_2_8">cylindrical</a></li>
<li><a href="r3_4.html#r3_4_2_2_9">spherical</a></li>
</ol>
<p>Each of which uses a different projection method to project the scene onto your screen. Regardless of the projection type all cameras use <code>location</code>, <code>right</code>, <code>up</code>, <code>direction</code>, and other keywords to determine the location and orientation of the camera. The type keywords and these four vectors fully define the camera. All other camera modifiers adjust how the camera does its job. The meaning of these vectors and other modifiers differ with the projection type used. A more detailed explanation of the camera types follows later. In the sub-sections which follows, we explain how to place and orient the camera by the use of these four vectors and the <code>sky</code> and <code>look_at</code> modifiers. You may wish to refer to the illustration of the perspective camera below as you read about these
vectors.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/f/fd/RefImgPerspcam.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Basic (default) camera geometry</p>
</td>
</tr>
</table>
</div>
<a name="r3_4_2_1_1"></a>
<div class="content-level-h5" contains="Location and Look_At" id="r3_4_2_1_1">
<h5>3.4.2.1.1 Location and Look_At</h5>
<p>Under many circumstances just two vectors in the camera statement are all
you need to position the camera: <code>location</code> and <code>look_at</code>
vectors. For example:</p>
<pre>
camera {
location <3,5,-10>
look_at <0,2,1>
}
</pre>
<p>The location is simply the x, y, z coordinates of the camera. The camera
can be located anywhere in the ray-tracing universe. The default location is
<code><0,0,0></code>. The <code>look_at</code> vector tells POV-Ray to
pan and tilt the camera until it is looking at the specified x, y, z
coordinates. By default the camera looks at a point one unit in the
z-direction from the location.</p>
<p>
The <code>look_at</code> modifier should almost always be the last item in
the camera statement. If other camera items are placed after the <code>
look_at</code> vector then the camera may not continue to look at the
specified point.</p>
</div>
<a name="r3_4_2_1_2"></a>
<div class="content-level-h5" contains="The Sky Vector" id="r3_4_2_1_2">
<h5>3.4.2.1.2 The Sky Vector</h5>
<p>Normally POV-Ray pans left or right by rotating about the y-axis until it
lines up with the <code>look_at</code> point and then tilts straight up or
down until the point is met exactly. However you may want to slant the camera
sideways like an airplane making a banked turn. You may change the tilt of
the camera using the <code>sky</code> vector. For example:</p>
<pre>
camera {
location <3,5,-10>
sky <1,1,0>
look_at <0,2,1>
}
</pre>
<p>This tells POV-Ray to roll the camera until the top of the camera is in
line with the sky vector. Imagine that the sky vector is an antenna pointing
out of the top of the camera. Then it uses the <code>sky</code> vector as the
axis of rotation left or right and then to tilt up or down in line with the
<code>sky</code> until pointing at the <code>look_at</code> point. In effect
you are telling POV-Ray to assume that the sky isn't straight up.</p>
<p>
The <code>sky</code> vector does nothing on its own. It only modifies the
way the <code>look_at</code> vector turns the camera. The default value is
<code>sky<0,1,0></code>.</p>
</div>
<a name="r3_4_2_1_3"></a>
<div class="content-level-h5" contains="Angles" id="r3_4_2_1_3">
<h5>3.4.2.1.3 Angles</h5>
<p>The <code>angle</code> keyword followed by a float expression specifies
the (horizontal) viewing angle in degrees of the camera used. Even though it
is possible to use the <code>direction</code> vector to determine the viewing
angle for the perspective camera it is much easier to use the <code>
angle</code> keyword.</p>
<p>
When you specify the <code>angle</code>, POV-Ray adjusts the length of the
<code>direction</code> vector accordingly. The formula used is <em>
direction_length = 0.5 * right_length / tan(angle / 2)</em> where <em>
right_length</em> is the length of the <code>right</code> vector. You should
therefore specify the <code>direction</code> and <code>right</code> vectors
before the <code>angle</code> keyword. The <code>right</code> vector is
explained in the next section.</p>
<p>
There is no limitation to the viewing angle except for the perspective
projection. If you choose viewing angles larger than 360 degrees you will
see repeated images of the scene (the way the repetition takes place depends
on the camera). This might be useful for special effects.</p>
<p>
The <code>spherical</code> camera has the option to also specify a vertical
angle. If not specified it defaults to the horizontal angle/2</p>
<p>
For example if you render an image with a 2:1 aspect ratio and map it
to a sphere using spherical mapping, it will recreate the scene. Another
use is to map it onto an object and if you specify transformations for
the object before the texture, say in an animation, it will look like
reflections of the environment (sometimes called environment mapping).</p>
</div>
<a name="r3_4_2_1_4"></a>
<div class="content-level-h5" contains="The Direction Vector" id="r3_4_2_1_4">
<h5>3.4.2.1.4 The Direction Vector</h5>
<p>You will probably not need to explicitly specify or change the camera
<code>direction</code> vector but it is described here in case you do. It
tells POV-Ray the initial direction to point the camera before moving it with
the <code>look_at</code> or <code>rotate</code> vectors (the default value is
<code>direction<0,0,1></code>). It may also be used to control the
(horizontal) field of view with some types of projection. The length of the
vector determines the distance of the viewing plane from the camera's
location. A shorter <code>direction</code> vector gives a wider view while a
longer vector zooms in for close-ups. In early versions of POV-Ray, this was
the only way to adjust field of view. However zooming should now be done
using the easier to use <code>angle</code> keyword.</p>
<p>
If you are using the <code>ultra_wide_angle</code>, <code>panoramic</code>,
or <code>cylindrical</code> projection you should use a unit length <code>
direction</code> vector to avoid strange results. The length of the <code>
direction</code> vector does not matter when using the <code>
orthographic</code>, <code>fisheye</code>, or <code>omnimax</code> projection
types.</p>
</div>
<a name="r3_4_2_1_5"></a>
<div class="content-level-h5" contains="Up and Right Vectors" id="r3_4_2_1_5">
<h5>3.4.2.1.5 Up and Right Vectors</h5>
<p>The primary purpose of the <code>up</code> and <code>right</code> vectors
is to tell POV-Ray the relative height and width of the view screen. The
default values are:</p>
<pre>
right 4/3*x
up y
</pre>
<p>In the default <code>perspective</code> camera, these two vectors also
define the initial plane of the view screen before moving it with the <code>
look_at</code> or <code>rotate</code> vectors. The length of the <code>
right</code> vector (together with the <code>direction</code> vector) may
also be used to control the (horizontal) field of view with some types of
projection. The <code>look_at</code> modifier changes both the <code>up</code>
and <code>right</code> vectors. The <code>angle</code> calculation depends on the <code>
right</code> vector.</p>
<p>
Most camera types treat the <code>up</code> and <code>right</code> vectors
the same as the <code>perspective</code> type. However several make special
use of them. In the <code>orthographic</code> projection: The lengths of the
<code>up</code> and <code>right</code> vectors set the size of the viewing
window regardless of the <code>direction</code> vector length, which is not
used by the orthographic camera.</p>
<p>
When using <code>cylindrical</code> projection: types 1 and 3, the axis of
the cylinder lies along the <code>up</code> vector and the width is
determined by the length of <code>right</code> vector or it may be overridden
with the <code>angle</code> vector. In type 3 the <code>up</code> vector
determines how many units high the image is. For example if you have <code>up
4*y</code> on a camera at the origin. Only points from y=2 to y=-2 are
visible. All viewing rays are perpendicular to the y-axis. For type 2 and 4,
the cylinder lies along the <code>right</code> vector. Viewing rays for type
4 are perpendicular to the <code>right</code> vector.</p>
<p class="Note"><strong>Note:</strong> The <code>up</code>, <code>right</code>, and <code>direction</code> vectors should always remain perpendicular to each other or the image will be distorted. If this is not the case a warning message will be printed. The vista buffer will not work for non-perpendicular camera vectors.</p>
</div>
<a name="r3_4_2_1_6"></a>
<div class="content-level-h5" contains="Aspect Ratio" id="r3_4_2_1_6">
<h5>3.4.2.1.6 Aspect Ratio</h5>
<p>Together the <code>up</code> and <code>right</code> vectors define the
<em>aspect ratio</em> (height to width ratio) of the resulting image. The
default values <code>up<0,1,0></code> and <code>
right<1.33,0,0></code> result in an aspect ratio of 4 to 3. This is the
aspect ratio of a typical computer monitor. If you wanted a tall skinny image
or a short wide panoramic image or a perfectly square image you should adjust
the <code>up</code> and <code>right</code> vectors to the appropriate
proportions.</p>
<p>
Most computer video modes and graphics printers use perfectly square pixels.
For example Macintosh displays and IBM SVGA modes 640x480, 800x600 and
1024x768 all use square pixels. When your intended viewing method uses square
pixels then the width and height you set with the <code>Width</code> and
<code>Height</code> options or <code>+W</code> or <code>+H</code> switches
should also have the same ratio as the <code>up</code> and <code>right</code>
vectors.</p>
<p class="Note"><strong>Note:</strong> 640/480 = 4/3 so the ratio is proper for this square pixel mode.</p>
<p>
Not all display modes use square pixels however. For example IBM VGA mode
320x200 and Amiga 320x400 modes do not use square pixels. These two modes
still produce a 4/3 aspect ratio image. Therefore images intended to be
viewed on such hardware should still use 4/3 ratio on their <code>up</code>
and <code>right</code> vectors but the pixel settings will not be 4/3.</p>
<p>
For example:</p>
<pre>
camera {
location <3,5,-10>
up <0,1,0>
right <1,0,0>
look_at <0,2,1>
}
</pre>
<p>This specifies a perfectly square image. On a square pixel display like
SVGA you would use pixel settings such as <code>+W480 +H480</code> or <code>
+W600 +H600</code>. However on the non-square pixel Amiga 320x400 mode you
would want to use values of <code>+W240 +H400</code> to render a square
image.</p>
<p>
The bottom line issue is this: the <code>up</code> and <code>right</code>
vectors should specify the artist's intended aspect ratio for the image
and the pixel settings should be adjusted to that same ratio for square
pixels and to an adjusted pixel resolution for non-square pixels. The <code>
up</code> and <code>right</code> vectors should <em> not</em> be adjusted
based on non-square pixels.</p>
</div>
<a name="r3_4_2_1_7"></a>
<div class="content-level-h5" contains="Handedness" id="r3_4_2_1_7">
<h5>3.4.2.1.7 Handedness</h5>
<p>The <code>right</code> vector also describes the direction to the right of
the camera. It tells POV-Ray where the right side of your screen is. The sign
of the <code>right</code> vector can be used to determine the handedness of
the coordinate system in use. The default value is: <code>
right<1.33,0,0></code>. This means that the +x-direction is to the
right. It is called a <em>left-handed</em> system because you can use your
left hand to keep track of the axes. Hold out your left hand with your palm
facing to your right. Stick your thumb up. Point straight ahead with your
index finger. Point your other fingers to the right. Your bent fingers are
pointing to the +x-direction. Your thumb now points into +y-direction. Your
index finger points into the +z-direction.</p>
<p>
To use a right-handed coordinate system, as is popular in some CAD programs
and other ray-tracers, make the same shape using your right hand. Your thumb
still points up in the +y-direction and your index finger still points
forward in the +z-direction but your other fingers now say the +x-direction
is to the left. That means that the right side of your screen is now in the
-x-direction. To tell POV-Ray to act like this you can use a negative x value
in the <code>right</code> vector such as: <code>
right<-1.33,0,0></code>. Since having x values increasing to the left
does not make much sense on a 2D screen you now rotate the whole thing 180
degrees around by using a positive z value in your camera's location. You
end up with something like this.</p>
<pre>
camera {
location <0,0,10>
up <0,1,0>
right <-1.33,0,0>
look_at <0,0,0>
}
</pre>
<p>Now when you do your ray-tracer's aerobics, as explained in the
section <a href="t2_2.html#t2_2_1_1">Understanding POV-Ray's Coordinate System</a>, you use your right hand to determine the direction of rotations.</p>
<p>
In a two dimensional grid, x is always to the right and y is up. The two
versions of handedness arise from the question of whether z points into the
screen or out of it and which axis in your computer model relates to up in
the real world.</p>
<p>
Architectural CAD systems, like AutoCAD, tend to use the <em> God's
Eye</em> orientation that the z-axis is the elevation and is the model's
up direction. This approach makes sense if you are an architect looking at
a building blueprint on a computer screen. z means up, and it increases
towards you, with x and y still across and up the screen. This is the basic
right handed system.</p>
<p>
Stand alone rendering systems, like POV-Ray, tend to consider you as a
participant. You are looking at the screen as if you were a photographer
standing in the scene. The up direction in the model is now y, the same as up
in the real world and x is still to the right, so z must be depth, which
increases away from you into the screen. This is the basic left handed
system.</p>
</div>
<a name="r3_4_2_1_8"></a>
<div class="content-level-h5" contains="Transforming the Camera" id="r3_4_2_1_8">
<h5>3.4.2.1.8 Transforming the Camera</h5>
<p>The various transformations such as <code>translate</code> and <code>
rotate</code> modifiers can re-position the camera once you have defined
it. For example:</p>
<pre>
camera {
location < 0, 0, 0>
direction < 0, 0, 1>
up < 0, 1, 0>
right < 1, 0, 0>
rotate <30, 60, 30>
translate < 5, 3, 4>
}
</pre>
<p>In this example, the camera is created, then rotated by 30 degrees about
the x-axis, 60 degrees about the y-axis and 30 degrees about the z-axis, then
translated to another point in space.</p>
</div>
<a name="r3_4_2_2"></a>
<div class="content-level-h4" contains="Types of Projection" id="r3_4_2_2">
<h4>3.4.2.2 Types of Projection</h4>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/0/09/RefImgCameraSampleScene.jpg">
</td>
<td>
<p class="tabletext">The following sections explain the different projection types that can be used with the scene camera. The most common types are the perspective and orthographic projections. The <em>CAMERA_TYPE</em> should be the <em>first</em> item in a <code>camera</code> statement. If none is specified, the <code>perspective</code> camera is the default.</p>
</td>
</tr>
<tr>
<td>
<p class="caption">The camera sample scene global view</p>
</td>
<td></td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> The <a href="r3_2.html#r3_2_8_4">vista buffer</a> feature can only be used with the perspective and orthographic camera.</p>
</div>
<a name="r3_4_2_2_1"></a>
<div class="content-level-h5" contains="Perspective projection" id="r3_4_2_2_1">
<h5>3.4.2.2.1 Perspective projection</h5>
<p>The <code>perspective</code> keyword specifies the default perspective camera which simulates the classic pinhole camera. The <em>horizontal</em> viewing angle is either determined by the ratio between the length of the <code>direction</code> vector and the length of the <code>right</code> vector or by the optional keyword <code>angle</code>, which is the preferred way. The viewing angle has to be larger than 0 degrees and smaller than 180 degrees.</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/8/82/RefImgCameraViewPerspective.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/f/f6/RefImgCameraSampleperspective.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The perspective projection diagram</p>
</td>
<td>
<p class="caption">A perspective camera sample image</p>
</td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> The <code>angle</code> keyword can be used as long as less than 180 degrees. It recomputes the length of right and up vectors using <code>direction</code>. The proper aspect ratio between the <code>up</code> and <code>right</code> vectors is maintained.</p>
</div>
<a name="r3_4_2_2_2"></a>
<div class="content-level-h5" contains="Orthographic projection" id="r3_4_2_2_2">
<h5>3.4.2.2.2 Orthographic projection</h5>
<p>The orthographic camera offers two modes of operation:</p>
<p>The pure <code>orthographic</code> projection. This projection uses parallel camera rays to create an image of the scene. The area of view is determined by the lengths of the <code>right</code> and <code>up</code> vectors. One of these has to be specified, they are not taken from the default camera. If omitted the second method of the camera is used.</p>
<p>If, in a perspective camera, you replace the <code>perspective</code> keyword by <code>orthographic</code> and leave all other parameters the same, you will get an orthographic view with the same image area, i.e. the size of the image is
the same. The same can be achieved by adding the <code>angle</code> keyword to an orthographic camera. A value for the angle is optional. So this second mode is active if no up and right are within the camera statement, or when the angle keyword is within the camera statement.</p>
<p>You should be aware though that the visible parts of the scene change when switching from perspective to orthographic view. As long as all objects of interest are near the look_at point they will be still visible if the orthographic camera is used. Objects farther away may get out of view while nearer objects will stay in view.</p>
<p>If objects are too close to the camera location they may disappear. Too close here means, behind the orthographic camera projection plane (the plane that goes through the <code>location</code> point).</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/c/ce/RefImgCameraViewOrthographic.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/b/b2/RefImgCameraSampleorthographic.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The orthographic projection diagram</p>
</td>
<td>
<p class="caption">An orthographic camera sample image</p>
</td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> The length of direction is irrelevant unless angle is used. The lengths of up and right define the dimensions of the view. The <code>angle</code> keyword can be used, as long as less than 180. It will override the length of the right and up vectors (the aspect ratio between up and right will be kept nevertheless) with a scope of a perspective camera having the same direction and angle.</p>
</div>
<a name="r3_4_2_2_3"></a>
<div class="content-level-h5" contains="Mesh projection" id="r3_4_2_2_3">
<h5>3.4.2.2.3 Mesh projection</h5>
<p>The mesh projection is a special camera type that allows complete control of the ray origin and direction for each pixel of the output image. The basic concept is to associate pixels with faces defined within a <em>previously declared</em> <code>mesh</code> or <code>mesh2</code> object. The <code>MESH_OBJECT_IDENTIFIER</code> need not be instantiated in the scene, though it can be, and doing so can lead to some interesting uses, such as texture baking or illumination calculations.</p>
<p>In its simplest form, each pixel of the output image is assigned to a face of the mesh according to <code>(width * (int) y) + (int) x</code>, however, more complex mapping is possible via multiple meshes and multiple rays per pixel. The type of mapping in use is determined by the distribution type parameter in the camera declaration. Except for mapping #3, the ray origin will be set to the centroid of the face, and the direction will be that of the face's normal. For mapping #3, barycentric co-ordinates are determined from the UV co-ordinates of the first face to match the X and Y position, and those are then converted to a position on the face which will serve as the ray origin. Support is provided to move the origin off the face along the normal, and to reverse the ray direction.</p>
<p>For most of the distribution methods, any POV feature that causes sub-pixel positioning to be used for shooting rays (e.g. anti-aliasing or jitter) will not do anything useful, because X and Y are converted to integers for indexing purposes. At this time, no warning is issued if anti-aliasing or jitter is requested when rendering a non-applicable distribution; this may be added later.</p>
<p>The syntax for the mesh camera is as follows:</p>
<pre>
camera {
mesh_camera {
rays per pixel
distribution type
[max distance]
mesh {
MESH_OBJECT_IDENTIFIER
[TRANSFORMATIONS]
}
[mesh ...]
}
[location]
[direction]
[smooth]
}
</pre>
<p class="Note"><strong>Note:</strong> The mesh camera is an <strong>experimental feature</strong> introduced in version 3.7 beta 39 and its syntax is likely to change. Additionally, many of the normal camera concepts presented in this section (such as location and direction) either do not work as they do for other cameras or do not work at all (for example, the concept of 'up' simply does not apply to a mesh camera). It should also be kept in mind that the camera has not yet been tested with many of POV-Ray's advanced features such as photons and radiosity, and more work in that area is likely to be needed.</p>
</div>
<a name="r3_4_2_2_3_1"></a>
<div class="content-level-h6" contains="Rays Per Pixel" id="r3_4_2_2_3_1">
<h6>3.4.2.2.3.1 Rays Per Pixel</h6>
<p>This float parameter controls the number of rays that will be shot for each pixel in the output image. Each distribution allows different values, but the minimum is always 1.</p>
</div>
<a name="r3_4_2_2_3_2"></a>
<div class="content-level-h6" contains="Distribution Type" id="r3_4_2_2_3_2">
<h6>3.4.2.2.3.2 Distribution Type</h6>
<p>This float parameter controls how pixels are assigned to faces as documented below:</p>
<ul>
<li><strong>distribution #0</strong></li>
</ul>
<p>This method allows single or multiple rays per pixel, with the ray number for that pixel allocated to each mesh in turn. The index into the meshes is the ray number, where <em>rays per pixel</em> is greater than one, and the index into the selected mesh is the pixel number within the output image. If there is no face at that pixel position, the resulting output pixel is unaffected.</p>
<p>You must supply at least as many meshes as <em>rays per pixel</em>. Each pixel is shot <em>rays per pixel</em> times, and the results averaged. Any ray that does not correspond with a face (i.e. the pixel number is greater than or equal to the face count) does not affect the resulting pixel color. Generally, it would be expected that the number of faces in each mesh is the same, but this is not a requirement. Keep in mind that a ray that is not associated with a face is not the same thing as a ray that is but that, when shot, hits nothing. The latter will return a pixel (even if it is transparent or the background color), whereas the former causes the ray to not be shot in the first place; hence, it is not included in the calculation of the average for the pixel.</p>
<p>Using multiple rays per pixel is useful for generating anti-aliasing (since standard AA won't work) or for special effects such as focal blur, motion blur, and so forth, with each additional mesh specified in the camera representing a slightly different camera position.</p>
<p class="Note"><strong>Note:</strong> It is legal to use transformations on meshes specified in the camera body, hence it's possible to obtain basic anti-aliasing by using a single mesh multiple times, with subsequent ones jittered slightly from the first combined with a suitable <em>rays per pixel</em> count.</p>
<ul>
<li><strong>distribution #1</strong></li>
</ul>
<p>This method allows both multiple rays per pixel and summing of meshes, in other words the faces of all the supplied meshes are logically summed together as if they were one single mesh. In this mode, if you specify more than one ray per pixel, the second ray for a given pixel will go to the face at <code>(width * height * ray_number) + pixel_number</code>, where <em>ray_number</em> is the count of rays shot into a specific pixel. If the calculated face index exceeds the total number of faces for all the meshes, no ray is shot.</p>
<p>The primary use for this summing method is convenience in generation of the meshes, as some modelers slow down to an irritating extent with very large meshes. Using <em>distribution #1</em> allows these to be split up.</p>
<ul>
<li><strong>distribution #2</strong></li>
</ul>
<p>Distribution method 2 is a horizontal array of sub-cameras, one per mesh (i.e. like method #0, it does not sum meshes). The image is divided horizontally into <em>#num_meshes</em> blocks, with the first mesh listed being the left-most camera, and the last being the right-most. The most obvious use of this would be with two meshes to generate a stereo camera arrangement.</p>
<p>In this mode, you can (currently) only have a single ray per pixel.</p>
<ul>
<li><strong>distribution #3</strong></li>
</ul>
<p>This method will reverse-map the face from the UV co-ordinates. Currently, only a single ray per pixel is supported, however, unlike the preceding methods, standard AA and jitter will work. This method is particularly useful for texture baking and resolution-independent mesh cameras, but requires that the mesh have a UV map supplied with it.</p>
<p>You can use the smooth modifier to allow interpolation of the normals at the vertices. This allows for use of UV mapped meshes as cameras with the benefit of not being resolution dependent, unlike the other distributions. The interpolation is identical to that used for smooth_triangles.</p>
<p>If used for texture baking, the generated image may have visible seams when applied back to the mesh, this can be mitigated. Also, depending on the way the original UV map was set up, using AA may produce incorrect pixels on the outside edge of the generated maps.</p>
</div>
<a name="r3_4_2_2_3_3"></a>
<div class="content-level-h6" contains="Max Distance" id="r3_4_2_2_3_3">
<h6>3.4.2.2.3.3 Max Distance</h6>
This is an optional floating-point value which, if greater than EPSILON (a very small value used internally for comparisons with 0), will be used as the limit for the length of any rays cast. Objects at a distance greater than this from the ray origin will not be intersected by the ray.
The primary use for this parameter is to allow a mesh camera to 'probe' a scene in order to determine whether or not a given location contains a visible object. Two examples would be a camera that divides the scene into slices for use in 3d printing or to generate an STL file, and a camera that divides the scene into cubes to generate voxel information. In both cases, some external means of processing the generated image into a useful form would be required.
It should be kept in mind that this method of determining spatial information is not guaranteed to generate an accurate result, as it is entirely possible for a ray to miss an object that is within its section of the scene, should that object have features that are smaller than the resolution of the mesh being used. In other words, it is (literally) hit and miss. This issue is conceptually similar to aliasing in a normal render.
It is left as an exercise for the reader to come up with means of generating pixel information that carries useful information, given the lack of light sources within the interior of an opaque object (hint: try ambient).
</div>
<a name="r3_4_2_2_3_4"></a>
<div class="content-level-h6" contains="Mesh Object" id="r3_4_2_2_3_4">
<h6>3.4.2.2.3.4 Mesh Object</h6>
<p>One or more <code>mesh</code> or <code>mesh2</code> objects to be used for the camera. These will be treated differently depending on the distribution method, as explained above. Transformations on the meshes can be used here, and will reflect on the resulting image as it would be expected for a regular camera.</p>
</div>
<a name="r3_4_2_2_3_5"></a>
<div class="content-level-h6" contains="About the Location Vector" id="r3_4_2_2_3_5">
<h6>3.4.2.2.3.5 About the Location Vector</h6>
<p>With this special camera, location doesn't affect where the camera is placed per se (that information is on the mesh object itself), but is used to move the origin of the ray off the face, along the normal of that face. This would typically be done for texture baking or illumination calculation scenes where the camera mesh is also instantiated into the scene, usually only a tiny amount of displacement is needed. The X and Y for location is not currently used, and the Z always refers to the normal of the face, rather than the real Z direction in the scene.</p>
</div>
<a name="r3_4_2_2_3_6"></a>
<div class="content-level-h6" contains="About the Direction Vector" id="r3_4_2_2_3_6">
<h6>3.4.2.2.3.6 About the Direction Vector</h6>
<p>Like location, this doesn't correspond to the real direction vector of the camera. It serves only to reverse the normal of all the faces, if necessary. If the Z component is less than -EPSILON, then the rays will be shot in the opposite direction than they would otherwise have been. X and Y are not used.</p>
</div>
<a name="r3_4_2_2_3_7"></a>
<div class="content-level-h6" contains="The Smooth Modifier" id="r3_4_2_2_3_7">
<h6>3.4.2.2.3.7 The Smooth Modifier</h6>
<p>This optional parameter is only useful with distribution #3, and will cause the ray direction to be interpolated according to the same rules as are applied to smooth triangles. For this to work, the mesh must have provided a normal for each vertex.</p>
<p class="Note"><strong>Note:</strong> See the sample scene files located in <em>~scenes/camera/mesh_camera/</em> for additional usages and other samples of mesh cameras. There are also some useful macros to assist in generating and processing meshes for use as cameras.</p>
</div>
<a name="r3_4_2_2_4"></a>
<div class="content-level-h5" contains="Fisheye projection" id="r3_4_2_2_4">
<h5>3.4.2.2.4 Fisheye projection</h5>
<p> This is a spherical projection. The viewing angle is specified by the <code>angle</code> keyword. An angle of 180 degrees creates the "standard" fisheye while an angle of 360 degrees creates a super-fisheye or "I-see-everything-view". If you use this projection you should get a circular image. If this is not the case, i.e. you get an elliptical image, you should read <a href="r3_4.html#r3_4_2_1_6">Aspect Ratio</a>.</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/a/a1/RefImgCameraViewFisheye.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/f/f5/RefImgCameraSamplefisheye.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The fisheye projection diagram</p>
</td>
<td>
<p class="caption">A fisheye camera sample image</p>
</td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> The length of the direction, up and right vectors are irrelevant. The <code>angle</code> keyword is the important setting.</p>
</div>
<a name="r3_4_2_2_5"></a>
<div class="content-level-h5" contains="Ultra wide angle projection" id="r3_4_2_2_5">
<h5>3.4.2.2.5 Ultra wide angle projection</h5>
<p>The ultra wide angle projection is somewhat similar to the fisheye, but it projects the image onto a rectangle instead of a circle. The viewing angle can be specified by using the <code>angle</code> keyword. The aspect ratio of the lengths of the up/right vectors are used to provide the vertical angle from the horizontal angle, so that the ratio of vertical angle on horizontal angle is identical to the ratio of the length of up on length of right. When the ratio is one, a square is wrapped on a quartic surface defined as follows:</p>
<p>x<sup>2</sup>+y<sup>2</sup>+z<sup>2</sup> = x<sup>2</sup>y<sup>2</sup> + 1</p>
<p>The section where z=0 is a square, the section where x=0 or y=0 is a circle, and the sections parallel to x=0 or y=0 are ellipses. When the ratio is not one, the bigger angle obviously gets wrapped further. When the angle reaches 180, the border meets the square section. The angle can be greater than 180, in that case, when both (vertical and horizontal) angles are greater than 180, the parts around the corners of the square section will be wrapped more than once. The classical usage (using an angle of 360) but with a up/right ratio of 1/2 <code>up 10*y</code> and <code>right 20*x</code> will keep the top of the image as the zenith, and the bottom of the image as the nadir, avoiding perception issues and giving a full 360 degree view.</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/3/3d/RefImgCameraViewUltrawideangle.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/0/01/RefImgCameraSampleultra_wide_angle.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The ultra wide angle projection diagram</p>
</td>
<td>
<p class="caption">An ultra wide angle sample image</p>
</td>
</tr>
</table>
</div>
<a name="r3_4_2_2_6"></a>
<div class="content-level-h5" contains="Omnimax projection" id="r3_4_2_2_6">
<h5>3.4.2.2.6 Omnimax projection</h5>
<p>The omnimax projection is a 180 degrees fisheye that has a reduced viewing angle in the vertical direction. In reality this projection is used to make movies that can be viewed in the dome-like Omnimax theaters. The image will look somewhat elliptical.</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/5/56/RefImgCameraViewOmnimax.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/b/bb/RefImgCameraSampleomnimax.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The omnimax projection diagram</p>
</td>
<td>
<p class="caption">An omnimax camera sample image</p>
</td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> The use of the <code>angle</code> keyword is irrelevant, the relative length of up and right vectors are what is important.</p>
</div>
<a name="r3_4_2_2_7"></a>
<div class="content-level-h5" contains="Panoramic projection" id="r3_4_2_2_7">
<h5>3.4.2.2.7 Panoramic projection</h5>
<p>This projection is called "cylindrical equirectangular projection". It overcomes the degeneration problem of the perspective projection if the viewing angle approaches 180 degrees. It uses a type of cylindrical projection to be able to use viewing angles larger than 180 degrees with a tolerable lateral-stretching distortion. The <code>angle</code> keyword is used to determine the viewing angle.</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/b/b1/RefImgCameraViewPanoramic.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/7/77/RefImgCameraSamplepanoramic.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The panoramic projection diagram</p>
</td>
<td>
<p class="caption">A panoramic camera sample image</p>
</td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> The <code>angle</code> keyword is irrelevant. The relative length of direction, up and right vectors are important as they define the lengths of the 3 axis of the ellipsoid. With identical length and orthogonal vectors (both strongly recommended, unless used on purpose), it's identical to a spherical camera with angle 180,90.</p>
</div>
<a name="r3_4_2_2_8"></a>
<div class="content-level-h5" contains="Cylindrical projection" id="r3_4_2_2_8">
<h5>3.4.2.2.8 Cylindrical projection</h5>
<p>Using this projection the scene is projected onto a cylinder. There are four different types of cylindrical projections depending on the orientation of the cylinder and the position of the viewpoint. An integer value in the range 1 to 4 must follow the <code>cylinder</code> keyword. The viewing angle and the length of the <code>up</code> or <code>right</code> vector determine the dimensions of the camera and the visible image. The characteristics of different types are as follows:</p>
<ol>
<li>vertical cylinder, fixed viewpoint</li>
<li>horizontal cylinder, fixed viewpoint</li>
<li>vertical cylinder, viewpoint moves along the cylinder's axis</li>
<li>horizontal cylinder, viewpoint moves along the cylinder's axis</li>
</ol>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/7/73/RefImgCameraViewCylinder1.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/4/46/RefImgCameraSamplecylinder_1.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The type 1 cylindrical projection diagram</p>
</td>
<td>
<p class="caption">A type 1 cylindrical camera sample image</p>
</td>
</tr>
</table>
<p></p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/a/ae/RefImgCameraViewCylinder2.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/6/61/RefImgCameraSamplecylinder_2.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The type 2 cylindrical projection diagram</p>
</td>
<td>
<p class="caption">A type 2 cylindrical camera sample image</p>
</td>
</tr>
</table>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/d/d3/RefImgCameraViewCylinder3.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/2/2c/RefImgCameraSamplecylinder_3.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The type 3 cylindrical projection diagram</p>
</td>
<td>
<p class="caption">A type 3 cylindrical camera sample image</p>
</td>
</tr>
</table>
<p></p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/8/81/RefImgCameraViewCylinder4.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/3/33/RefImgCameraSamplecylinder_4.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The type 4 cylindrical projection diagram</p>
</td>
<td>
<p class="caption">A type 4 cylindrical camera sample image</p>
</td>
</tr>
</table>
</div>
<a name="r3_4_2_2_9"></a>
<div class="content-level-h5" contains="Spherical projection" id="r3_4_2_2_9">
<h5>3.4.2.2.9 Spherical projection</h5>
<p>Using this projection the scene is projected onto a sphere.</p>
<p>The syntax is:</p>
<pre>
camera {
spherical
[angle HORIZONTAL [VERTICAL]]
[CAMERA_ITEMS...]
}
</pre>
<p>The first value after <code>angle</code> sets the horizontal viewing angle of the camera. With the optional second value, the vertical viewing angle is set: both in degrees. If the vertical angle is not specified, it defaults to half the horizontal angle.</p>
<p>The spherical projection is similar to the fisheye projection, in that the scene is projected on a sphere. But unlike the fisheye camera, it uses rectangular coordinates instead of polar coordinates; in this it works the same way as spherical mapping (map_type 1).</p>
<p>This has a number of uses. Firstly, it allows an image rendered with the spherical camera to be mapped on a sphere without distortion (with the fisheye camera, you first have to convert the image from polar to rectangular coordinates in some image editor). Also, it allows effects such as "environment mapping", often used for simulating reflections in scanline renderers.</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="leftpanel" width="320px" src="images/e/e6/RefImgCameraViewSpherical.png">
</td>
<td>
<img class="rightpanel" width="320px" src="images/4/47/RefImgCameraSamplespherical.jpg">
</td>
</tr>
<tr>
<td>
<p class="caption">The spherical projection diagram</p>
</td>
<td>
<p class="caption">A spherical camera sample image</p>
</td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> The lengths of the direction, up and right vectors are irrelevant. Angle is the important setting, and it gets two values separated by a comma: the first is the horizontal angle, the second is the vertical angle. Both values can reach 360. If the second value is missing, it is set to half the value of the first.</p>
</div>
<a name="r3_4_2_3"></a>
<div class="content-level-h4" contains="Focal Blur" id="r3_4_2_3">
<h4>3.4.2.3 Focal Blur</h4>
<p>POV-Ray can simulate focal depth-of-field by shooting a number of sample rays from jittered points within each pixel and averaging the results.</p>
<p>To turn on focal blur, you must specify the <code>aperture</code> keyword followed by a float value which determines the depth of the sharpness zone. Large apertures give a lot of blurring, while narrow apertures will give a wide zone of sharpness.</p>
<p class="Note"><strong>Note:</strong> While this behaves as a real camera does, the values for aperture are purely arbitrary and are not related to <em>f</em>-stops.</p>
<p>You must also specify the <code>blur_samples</code> keyword followed by an integer value specifying the maximum number of rays to use for each pixel. More rays give a smoother appearance but is slower. By default no focal blur is used, i. e. the default aperture is 0 and the default number of samples is 0.</p>
<p>The center of the <em>zone of sharpness</em> is specified by the <code>focal_point</code> vector. The <em>zone of sharpness</em> is a plane through the <code>focal_point</code> and is parallel to the camera. Objects close to this plane of focus are in focus and those farther from that plane are more blurred. The default value is <code>focal_point<0,0,0></code>.</p>
<p>Although <code>blur_samples</code> specifies the maximum number of samples, there is an adaptive mechanism that stops shooting rays when a certain degree of confidence has been reached. At that point, shooting more rays would not result in a significant change.</p>
<p>Extra samples are generated in a circular rather than square pattern when <code>blur_samples</code> is <strong>not</strong> set to either 4, 7, 19 or 37, leading to a circular rather than square bokeh. The extra samples are generated from a <em>Halton</em> sequence rather than a random stream. You can also optionally specify a minimum number of samples to be taken before testing against the <code>confidence</code> and <code>variance</code> settings. The default is 4, if the <code>blur_samples</code> maximum is less than 7, otherwise the default is 7, to provide a means to get rid of stray non-blurred pixels.</p>
<p>The syntax is:</p>
<pre>
blur_samples [ MIN_SAMPLES, ] MAX_SAMPLES
</pre>
<p>The <code>confidence</code> and <code>
variance</code> keywords are followed by float values to control the adaptive function. The <code>confidence</code> value is used to determine when the samples seem to be <em>close enough</em> to the correct color. The <code>variance</code> value specifies an acceptable tolerance on the variance of the samples taken so far. In other words, the process of shooting sample rays is terminated when the estimated color value is very likely (as controlled by the confidence probability) near the real color value.</p>
<p>Since the <code>confidence</code> is a probability its values can range from 0 to less than 1 (the default is 0.9, i. e. 90%). The value for the <code>variance</code> should be in the range of the smallest displayable color difference (the default is 1/128). If 1 is used POV-Ray will issue a warning and then use the default instead.</p>
<p>Rendering with the default settings can result in quite grainy images. This can be improved by using a lower <code>variance</code>. A value of 1/10000 gives a fairly good result (with default confidence and blur_samples set to something like 100) without being unacceptably slow.</p>
<p>Larger <code>confidence</code> values will lead to more samples, slower traces and better images. The same holds for smaller <code>variance</code> thresholds.</p>
<p>Focal blur can also support a user-defined <code>bokeh</code> using the following syntax:</p>
<pre>
camera {
// ... focal blur camera definition
bokeh {
pigment { ... }
}
}
</pre>
<p>If <code>bokeh</code> is specified, focal blur will use a custom sampling sequence based on the specified pigment's brightness in the range <0,0,0> to <1,1,0> i.e. the unit square in the XY plane.</p>
</div>
<a name="r3_4_2_4"></a>
<div class="content-level-h4" contains="Camera Ray Perturbation" id="r3_4_2_4">
<h4>3.4.2.4 Camera Ray Perturbation</h4>
<p>The optional <code><a href="r3_4.html#r3_4_6_2">normal</a></code> may be used to assign a normal pattern to
the camera. For example:</p>
<pre>
camera{
location Here
look_at There
normal { bumps 0.5 }
}
</pre>
<p>All camera rays will be perturbed using this pattern. The image will be distorted as though you were looking through bumpy glass or seeing a reflection off of a bumpy surface. This lets you create special effects. See the animated scene <code>camera2.pov</code> for an example. See <a href="r3_4.html#r3_4_6_2">Normal</a> for information on normal patterns.</p>
</div>
<a name="r3_4_2_5"></a>
<div class="content-level-h4" contains="Camera Identifiers" id="r3_4_2_5">
<h4>3.4.2.5 Camera Identifiers</h4>
<p>Camera identifiers may be declared to make scene files more readable and
to parameterize scenes so that changing a single declaration changes many
values. You may declare several camera identifiers if you wish. This makes it
easy to quickly change cameras. An identifier is declared as follows.</p>
<pre>
CAMERA_DECLARATION:
#declare IDENTIFIER = CAMERA |
#local IDENTIFIER = CAMERA
</pre>
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40
characters long and <em>CAMERA</em> is any valid camera statement. See
<a href="r3_3.html#r3_3_2_2_2">#declare vs. #local</a> for information on identifier scope. Here is an example...</p>
<pre>
#declare Long_Lens =
camera {
location -z*100
look_at <0,0,0>
angle 3
}
#declare Short_Lens =
camera {
location -z*50
look_at <0,0,0>
angle 15
}
camera {
Long_Lens // edit this line to change lenses
translate <33,2,0>
}
</pre>
<p class="Note"><strong>Note:</strong> Only camera transformations can be added to an already declared camera. Camera behaviour changing keywords are not allowed, as they are needed in an earlier stage for resolving the keyword order dependencies.</p></div>
<a name="r3_4_3"></a>
<div class="content-level-h3" contains="Atmospheric Effects" id="r3_4_3">
<h3>3.4.3 Atmospheric Effects</h3>
<p>Atmospheric effects are a loosely-knit group of features that affect the background and/or the atmosphere enclosing the scene. POV-Ray includes the ability to render a number of atmospheric effects, such as fog, haze, mist, rainbows and skies.</p></div>
<a name="r3_4_3_1"></a>
<div class="content-level-h4" contains="Atmospheric Media" id="r3_4_3_1">
<h4>3.4.3.1 Atmospheric Media</h4>
<p>Atmospheric effects such as fog, dust, haze, or visible gas may be simulated by a <code>media</code> statement specified in the scene but not attached to any object. All areas not inside a non-hollow object in the entire scene. A very simple approach to add fog to a scene is explained in the section <a href="r3_4.html#r3_4_3_3">Fog</a> however this kind of fog does not interact with any light sources like <code><a href="r3_4.html#r3_4_8">media</a></code> does. It will not show light beams or other effects and is therefore not very realistic.</p>
<p>
The atmosphere media effect overcomes some of the fog's limitations by calculating the interaction between light and the particles in the atmosphere using volume sampling. Thus shafts of light beams will become visible and objects will cast shadows onto smoke or fog.</p>
<p class="Note"><strong>Note:</strong> POV-Ray cannot sample media along an infinitely long ray. The ray must be finite in order to be possible to sample. This means that sampling media is only possible for rays that hit an object, so no atmospheric media will show up against the <code>background</code> or <code>sky_sphere</code>. Another way of being able to sample media is using spotlights, because in this case the ray is not infinite, as it is sampled only inside the spotlight cone.</p>
<p>With <a href="r3_4.html#r3_4_4_1_2">spotlights</a> you will be able to create the best results because their cone of light will become visible. Pointlights can be used to create effects like street lights in fog. Lights can be made to not interact with the atmosphere by adding <code>media_interaction off</code> to the light source. They can be used to increase the overall light level of the scene to make it look more realistic.</p>
<p>
Complete details on <code>media</code> are given in the section <a href="r3_4.html#r3_4_8">Media</a>. Earlier versions of POV-Ray used an <code>atmosphere</code> statement for atmospheric effects but that system was incompatible with the old object <code>halo</code> system. So <code>atmosphere</code> has been eliminated and replaced with a simpler and more powerful media feature. The user now only has to learn one <code>media</code> system for either atmospheric or object use.</p>
<p>
If you only want media effects in a particular area, you should use object media rather than only relying upon the media pattern. In general it will be faster and more accurate because it only calculates inside the constraining object.</p>
<p class="Note"><strong>Note:</strong> The atmosphere feature will not work if the camera is inside a non-hollow object (see the section <a href="r3_4.html#r3_4_8_1_2">Empty and Solid Objects</a> for a detailed explanation).</p></div>
<a name="r3_4_3_2"></a>
<div class="content-level-h4" contains="Background" id="r3_4_3_2">
<h4>3.4.3.2 Background</h4>
<p>A background color can be specified if desired. Any ray that does not hit an object will be colored with this color. The default background is black. The syntax for <code>background</code> is:</p>
<pre>
BACKGROUND:
background {COLOR}
</pre>
<p class ="Note"><strong>Note:</strong> As of version 3.7 some changes have been made to the way alpha is handled when <code>+ua</code> is activated. </p>
<ul>
<li> In previous versions, specifying a background with the <code>background</code> keyword would by default supply a background with transmit set to 1.0 (i.e. fully transparent provided that <code>+ua</code> is being used). This is no longer the case. While the default background is transparent, any background specified in a scene file (unless 3.6 or earlier compatibility is being used) will now be opaque unless transmit is explicitly given. In other words, use <code>rgbft<></code> rather than <code>rgb<></code> in the background statement if you want the old behavior.</li>
<li> The way that objects are blended with the background has changed. Previously the color of the background was not taken into account when calculating effects of transmission through translucent objects when <code>+ua</code> is in effect (i.e. where the background could otherwise have been seen through the object). Now, however, the background color is taken into account, even if it is not otherwise visible. Blending is performed in the same way regardless of the presence of background transparency.</li>
</ul>
<p class="Note"><strong>Note:</strong> When using <code>Output_Alpha=on</code> or <code>+ua</code> with legacy scenes (the <code>#version</code> directive set to less than 3.7) the <code>background</code> will be suppressed, except in reflections.</p></div>
<a name="r3_4_3_3"></a>
<div class="content-level-h4" contains="Fog" id="r3_4_3_3">
<h4>3.4.3.3 Fog</h4>
<p>If it is not necessary for light beams to interact with atmospheric media,
then <code>fog</code> may be a faster way to simulate haze or fog. This
feature artificially adds color to every pixel based on the distance the ray
has traveled. The syntax for fog is:</p>
<pre>
FOG:
fog { [FOG_IDENTIFIER] [FOG_ITEMS...] }
FOG_ITEMS:
fog_type Fog_Type | distance Distance | COLOR |
turbulence <Turbulence> | turb_depth Turb_Depth |
omega Omega | lambda Lambda | octaves Octaves |
fog_offset Fog_Offset | fog_alt Fog_Alt |
up <Fog_Up> | TRANSFORMATION
</pre>
<p>Fog default values:</p>
<pre>
lambda : 2.0
fog_type : 1
fog_offset : 0.0
fog_alt : 0.0
octaves : 6
omega : 0.5
turbulence : <0,0,0>
turb_depth : 0.5
up : <0,1,0>
</pre>
<p>Currently there are two fog types, the default <code>fog_type 1</code> is
a constant fog and <code>fog_type 2</code> is ground fog. The constant fog
has a constant density everywhere while the ground fog has a constant density
for all heights below a given point on the up axis and thins out along this
axis.</p>
<p>
The color of a pixel with an intersection depth <em>d</em> is calculated
by</p>
<p>
<em> PIXEL_COLOR = exp(-d/D) * OBJECT_COLOR + (1-exp(-d/D)) *
FOG_COLOR</em></p>
<p>
where <em>D</em> is the specified value of the required fog <code>distance</code>
keyword. At depth 0 the final color is the object's color. If the
intersection depth equals the fog distance the final color consists of 64%
of the object's color and 36% of the fog's color.</p>
<p class="Note"><strong>Note:</strong> For this equation, a distance of zero is undefined. In
practice, povray will treat this value as "fog is off". To use an
extremely thick fog, use a small nonzero number such as 1e-6 or 1e-10.
</p>
<p>
For ground fog, the height below which the fog has constant density is
specified by the <code>fog_offset</code> keyword. The <code>fog_alt</code>
keyword is used to specify the rate by which the fog fades away. The default
values for both are 0.0 so be sure to specify them if ground fog is used. At
an altitude of <em><code> Fog_Offset+Fog_Alt</code></em> the fog has a
density of 25%. The density of the fog at height less than or equal to
<em>Fog_Offset</em> is 1.0 and for height larger than than <em>Fog_Offset</em>
is calculated by:</p>
<p>
<em> <code> 1/(1 + (y - Fog_Offset) / Fog_Alt) ^2</code></em></p>
<p>
The total density along a ray is calculated by integrating from the height
of the starting point to the height of the end point.</p>
<p>
The optional <code>up</code> vector specifies a direction pointing up,
generally the same as the camera's up vector. All calculations done
during the ground fog evaluation are done relative to this up vector, i. e.
the actual heights are calculated along this vector. The up vector can also
be modified using any of the known transformations described in
<a href="r3_3.html#r3_3_1_12">Transformations</a>. Though it may not be a good idea to scale the up
vector - the results are hardly predictable - it is quite useful to be able
to rotate it. You should also note that translations do not affect the up
direction (and thus do not affect the fog).</p>
<p>
The required fog color has three purposes. First it defines the color to be
used in blending the fog and the background. Second it is used to specify a
translucency threshold. By using a transmittance larger than zero one can
make sure that at least that amount of light will be seen through the fog.
With a transmittance of 0.3 you will see at least 30% of the background.
Third it can be used to make a filtering fog. With a filter value larger than
zero the amount of background light given by the filter value will be
multiplied with the fog color. A filter value of 0.7 will lead to a fog that
filters 70% of the background light and leaves 30% unfiltered.</p>
<p>
Fogs may be layered. That is, you can apply as many layers of fog as you like. Generally this is most effective if each layer is a ground fog of different color, altitude and with different turbulence values. To use multiple layers of fogs, just add all of them to the scene.</p>
<p>
You may optionally stir up the fog by adding turbulence. The <code>turbulence</code> keyword may be followed by a float or vector to specify an amount of turbulence to be used. The <code>omega</code>, <code>lambda</code> and <code> octaves</code> turbulence parameters may also be specified. See the section <a href="r3_4.html#r3_4_7_5_5_3">Turbulence Warp</a> for details on all of these turbulence parameters.</p>
<p>
Additionally the fog turbulence may be scaled along the direction of the viewing ray using the <code>turb_depth</code> amount. Typical values are from 0.0 to 1.0 or more. The default value is 0.5 but any float value may be used.</p>
<p class="Note"><strong>Note:</strong> The fog feature will not work if the camera is inside a
non-hollow object (see the section <a href="r3_4.html#r3_4_8_1_2">Empty and Solid Objects</a> for a detailed explanation).</p></div>
<a name="r3_4_3_4"></a>
<div class="content-level-h4" contains="Sky Sphere" id="r3_4_3_4">
<h4>3.4.3.4 Sky Sphere</h4>
<p>The sky sphere is used create a realistic sky background without the need of an additional sphere to simulate the sky. Its syntax is:</p>
<pre>
SKY_SPHERE:
sky_sphere { [SKY_SPHERE_IDENTIFIER] [SKY_SPHERE_ITEMS...] }
SKY_SPHERE_ITEM:
PIGMENT | TRANSFORMATION | [emission]
</pre>
<p class="Note"><strong>Note:</strong> When using <code>Output_Alpha=on</code> or <code>+ua</code> with legacy scenes (the <code>#version</code> directive set to less than 3.7) the <code>sky_sphere</code> will be suppressed, except in reflections.</p>
<p>The sky sphere can contain several pigment layers with the last pigment being at the top, i. e. it is evaluated last, and the first pigment being at the bottom, i. e. it is evaluated first. If the upper layers contain filtering and/or transmitting components lower layers will shine through. If not lower layers will be invisible.</p>
<p class="Note"><strong>Note:</strong> Version 3.7 changed the effect of filter in a layered-pigment <code>sky_sphere</code> to match the behavior of a corresponding layered-texture large regular sphere. The old behavior, though probably having been unintentional, is automatically re-activated for backward compatibility when a <code>#version</code> of less than 3.7 is specified. </p>
<p>The sky sphere is calculated by using the direction vector as the parameter for evaluating the pigment patterns. This leads to results independent from the view point, which fairly accurately models a real sky, where the distance to the sky is much larger than the distances between visible objects.</p>
<p>Optionally adding the <code>emission</code> keyword allows for brightness tuning of image-mapped sky sphere's. The default is rgb <1,1,1> with higher values increasing the brightness, and lower values correspondingly decrease it. Although primarily intended for easy tuning of light probe skies, the parameter also works with procedural sky pigments.</p>
<p>If you want to add a nice color blend to your background you can easily do this by using the following example.</p>
<pre>
sky_sphere {
pigment {
gradient y
color_map {
[ 0.5 color CornflowerBlue ]
[ 1.0 color MidnightBlue ]
}
scale 2
translate -1
}
emission rgb <0.8,0.8,1>
}
</pre>
<p>This gives a soft blend from <code>CornflowerBlue</code> at the horizon to <code>MidnightBlue</code> at the zenith. The scale and translate operations are used to map the direction vector values, which lie in the range from <-1, -1, -1> to <1, 1, 1>, onto the range from <0, 0, 0> to <1, 1, 1>. Thus a repetition of the color blend is avoided for parts of the sky below the horizon.</p>
<p>
In order to easily animate a sky sphere you can transform it using the usual transformations described in <a href="r3_3.html#r3_3_1_12">Transformations</a>. Though it may not be a good idea to translate or scale a sky sphere - the results are hardly predictable - it is quite useful to be able to rotate it. In an animation the color blendings of the sky can be made to follow the rising sun for example.</p>
<p class="Note"><strong>Note:</strong> Only one sky sphere can be used in any scene. It also will not work as you might expect if you use camera types like the <a href="r3_4.html#r3_4_2_2_2">orthographic</a> or <a href="r3_4.html#r3_4_2_2_8">cylindrical</a> camera. The orthographic camera uses parallel rays and thus you will only see a very small part of the sky sphere (you will get one color skies in most cases). Reflections in curved surface will work though, e. g. you will
clearly see the sky in a mirrored ball.</p></div>
<a name="r3_4_3_5"></a>
<div class="content-level-h4" contains="Rainbow" id="r3_4_3_5">
<h4>3.4.3.5 Rainbow</h4>
<p>Rainbows are implemented using fog-like, circular arcs. Their syntax
is:</p>
<pre>
RAINBOW:
rainbow { [RAINBOW_IDENTIFIER] [RAINBOW_ITEMS...] }
RAINBOW_ITEM:
direction <Dir> | angle Angle | width Width |
distance Distance | COLOR_MAP | jitter Jitter | up <Up> |
arc_angle Arc_Angle | falloff_angle Falloff_Angle
</pre>
<p>Rainbow default values:</p>
<pre>
arc_angle : 180.0
falloff_angle : 180.0
jitter : 0.0
up : y
</pre>
<p>The required <code>direction</code> vector determines the direction of the
(virtual) light that is responsible for the rainbow. Ideally this is an
infinitely far away light source like the sun that emits parallel light rays.
The position and size of the rainbow are specified by the required <code>angle</code>
and <code>width</code> keywords. To understand how they work you should
first know how the rainbow is calculated.</p>
<p>
For each ray the angle between the rainbow's direction vector and the
ray's direction vector is calculated. If this angle lies in the interval
from <em><code> Angle-Width/2</code></em> to <em><code>
Angle+Width/2</code></em> the rainbow is hit by the ray. The color is then
determined by using the angle as an index into the rainbow's color_map.
After the color has been determined it will be mixed with the background
color in the same way like it is done for fogs.</p>
<p>Thus the angle and width parameters determine the angles under which the
rainbow will be seen. The optional <code> jitter</code> keyword can be used
to add random noise to the index. This adds some irregularity to the rainbow
that makes it look more realistic.</p>
<p>The required <code>distance</code> keyword is the same like the one used
with fogs. Since the rainbow is a fog-like effect it is possible that the
rainbow is noticeable on objects. If this effect is not wanted it can be
avoided by using a large distance value. By default a sufficiently large
value is used to make sure that this effect does not occur.</p>
<p>The <code>color_map</code> statement is used to assign a color map that
will be mapped onto the rainbow. To be able to create realistic rainbows it
is important to know that the index into the color map increases with the
angle between the ray's and rainbow's direction vector. The index is
zero at the innermost ring and one at the outermost ring. The filter and
transmittance values of the colors in the color map have the same meaning as
the ones used with fogs (see the section <a href="r3_4.html#r3_4_3_3">Fog</a>).</p>
<p>The default rainbow is a 360 degree arc that looks like a circle. This is no
problem as long as you have a ground plane that hides the lower, non-visible
part of the rainbow. If this is not the case or if you do not want the
full arc to be visible you can use the optional keywords <code>up</code>,
<code> arc_angle</code> and <code>falloff_angle</code> to specify a smaller
arc.</p>
<p>The <code>arc_angle</code> keyword determines the size of the arc in degrees
(from 0 to 360 degrees). A value smaller than 360 degrees results in an arc
that abruptly vanishes. Since this does not look nice you can use the
<code>falloff_angle</code> keyword to specify a region in which the rainbow
will smoothly blend into the background making it vanish softly. The falloff
angle has to be smaller or equal to the arc angle.</p>
<p>The <code> up</code> keyword determines were the zero angle position is. By
changing this vector you can rotate the rainbow about its direction. You
should note that the arc goes from <em>-Arc_Angle/2</em> to <em>
+Arc_Angle/2</em>. The soft regions go from <em>-Arc_Angle/2</em> to <em>
-Falloff_Angle/2</em> and from <em>+Falloff_Angle/2</em> to <em>
+Arc_Angle/2</em>.</p>
<p>
The following example generates a 120 degrees rainbow arc that has a falloff
region of 30 degrees at both ends:</p>
<pre>
rainbow {
direction <0, 0, 1>
angle 42.5
width 5
distance 1000
jitter 0.01
color_map { Rainbow_Color_Map }
up <0, 1, 0>
arc_angle 120
falloff_angle 30
}
</pre>
<p>It is possible to use any number of rainbows and to combine them with
other atmospheric effects.</p></div>
<a name="r3_4_4"></a>
<div class="content-level-h3" contains="Lighting Types" id="r3_4_4">
<h3>3.4.4 Lighting Types</h3>
<p>POV-Ray supports several <em>lighting types</em>. The most basic being a highly configurable conventional <a href="r3_4.html#r3_4_4_1">light source</a>. Scenes <em>can</em> have more than one light source, and light sources can be <a href="r3_4.html#r3_4_4_2">grouped</a> together with other objects and/or light sources. POV-Ray also supports more sophisticated lighting models such as: <em>global illumination</em> or <a href="r3_4.html#r3_4_4_3">radiosity</a> and <a href="r3_4.html#r3_4_4_4">photon</a> mapping.</p></div>
<a name="r3_4_4_1"></a>
<div class="content-level-h4" contains="Light Source" id="r3_4_4_1">
<h4>3.4.4.1 Light Source</h4>
<p>The <code>light_source</code> is not really an object. Light sources have no visible shape of their own. They are just points or areas which emit light. They are categorized as objects so that they can be combined with regular objects using <code>union</code>.</p>
<p class="Note"><strong>Note:</strong> Due to a hard-coded limit the number of light sources should not exceed 127. Since the class of the variable that governs this limit is <em>not exclusive</em> to light sources, a value had to be chosen that provides the best balance between performance, memory use and flexibility. See the following <a href="http://news.povray.org/povray.beta-test/thread/web.4d18ce518224b54c231f2b0b0@news.povray.org/">news-group discussion</a> for more details and information about ways to overcome this limitation.</p>
<p>The syntax is as follows:</p>
<pre>
LIGHT_SOURCE:
light_source {
<Location>, COLOR
[LIGHT_MODIFIERS...]
}
LIGHT_MODIFIER:
LIGHT_TYPE | SPOTLIGHT_ITEM | AREA_LIGHT_ITEMS |
GENERAL_LIGHT_MODIFIERS
LIGHT_TYPE:
spotlight | shadowless | cylinder | parallel
SPOTLIGHT_ITEM:
radius Radius | falloff Falloff | tightness Tightness |
point_at <Spot>
PARALLEL_ITEM:
point_at <Spot>
AREA_LIGHT_ITEM:
area_light <Axis_1>, <Axis_2>, Size_1, Size_2 |
adaptive Adaptive | area_illumination [Bool] |
jitter | circular | orient
GENERAL_LIGHT_MODIFIERS:
looks_like { OBJECT } |
TRANSFORMATION fade_distance Fade_Distance |
fade_power Fade_Power | media_attenuation [Bool] |
media_interaction [Bool] | projected_through
</pre>
<p>Light source default values:</p>
<pre>
LIGHT_TYPE : pointlight
falloff : 70
media_interaction : on
media_attenuation : off
point_at : <0,0,0>
radius : 70
tightness : 10
</pre>
<p>The different types of light sources and the optional modifiers are
described in the following sections.</p>
<p>
The first two items are common to all light sources. The <em><code><Location></code></em>
vector gives the location of the light. The <em>COLOR</em> gives the color
of the light. Only the red, green, and blue components are significant. Any
transmit or filter values are ignored. </p>
<p class="Note"><strong>Note:</strong> You vary the intensity of the light as well as the color using this parameter. A color such as
<code>rgb <0.5,0.5,0.5></code> gives a white light that is half the normal intensity.</p>
<p> All of the keywords or items in the syntax
specification above may appear in any order. Some keywords only have effect
if specified with other keywords. The keywords are grouped into functional
categories to make it clear which keywords work together. The
<em>GENERAL_LIGHT_MODIFIERS</em> work with all types of lights and all
options. </p>
<p class="Note"><strong>Note:</strong> <em>TRANSFORMATIONS</em> such as <code><a href="r3_3.html#r3_3_1_12">translate</a></code>, <code><a href="r3_3.html#r3_3_1_12">rotate</a></code> etc. may be applied but no other <em>OBJECT_MODIFIERS</em> may be used.</p>
<p>
There are three mutually exclusive light types. If no <em>LIGHT_TYPE</em> is
specified it is a point light. The other choices are <code>spotlight</code>
and <code>cylinder</code>.</p>
</div>
<a name="r3_4_4_1_1"></a>
<div class="content-level-h5" contains="Point Lights" id="r3_4_4_1_1">
<h5>3.4.4.1.1 Point Lights</h5>
<p>The simplest kind of light is a point light. A point light source sends
light of the specified color uniformly in all directions. The default light
type is a point source. The <em><code><Location></code></em> and <em>
COLOR</em> is all that is required. For example:</p>
<pre>
light_source {
<1000,1000,-1000>, rgb <1,0.75,0> //an orange light
}
</pre>
</div>
<a name="r3_4_4_1_2"></a>
<div class="content-level-h5" contains="Spotlights" id="r3_4_4_1_2">
<h5>3.4.4.1.2 Spotlights</h5>
<p>Normally light radiates outward equally in all directions from the source.
However the <code>spotlight</code> keyword can be used to create a cone of
light that is bright in the center and falls of to darkness in a soft fringe
effect at the edge.</p>
<p>
Although the cone of light fades to soft edges, objects illuminated by
spotlights still cast hard shadows. The syntax is:</p>
<pre>
SPOTLIGHT_SOURCE:
light_source {
<Location>, COLOR spotlight
[LIGHT_MODIFIERS...]
}
LIGHT_MODIFIER:
SPOTLIGHT_ITEM | AREA_LIGHT_ITEMS | GENERAL_LIGHT_MODIFIERS
SPOTLIGHT_ITEM:
radius Radius | falloff Falloff | tightness Tightness |
point_at <Spot>
</pre>
<p>
Default values:
</p>
<pre>
radius: 30 degrees
falloff: 45 degrees
tightness: 0
</pre>
<p>The <code>point_at</code> keyword tells the spotlight to point at a
particular 3D coordinate. A line from the location of the spotlight to the
<code>point_at</code> coordinate forms the center line of the cone of light.
The following illustration will be helpful in understanding how these values
relate to each other.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/4/45/RefImgSpotgeom.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The geometry of a spotlight.</p>
</td>
</tr>
</table>
<p>The <code>falloff</code>, <code>radius</code>, and <code>tightness</code>
keywords control the way that light tapers off at the edges of the cone.
These four keywords apply only when the <code>spotlight</code> or <code>
cylinder</code> keywords are used.</p>
<p>
The <code>falloff</code> keyword specifies the overall size of the cone of
light. This is the point where the light falls off to zero intensity. The
float value you specify is the angle, in degrees, between the edge of the
cone and center line. The <code>radius</code> keyword specifies the size of
the <em>hot-spot</em> at the center of the cone of light. The
<em>hot-spot</em> is a brighter cone of light inside the spotlight cone
and has the same center line. The <code>radius</code> value specifies the
angle, in degrees, between the edge of this bright, inner cone and the center
line. The light inside the inner cone is of uniform intensity. The light
between the inner and outer cones tapers off to zero.</p>
<p>
For example, assuming a <code>tightness 0</code>, with <code>radius 10</code> and <code>falloff 20</code> the light
from the center line out to 10 degrees is full intensity. From 10 to 20
degrees from the center line the light falls off to zero intensity. At 20
degrees or greater there is no light.</p>
<p class="Note"><strong>Note:</strong> If the radius and falloff
values are close or equal the light intensity drops rapidly and the spotlight
has a sharp edge.</p>
<p>
The values for the <code>radius</code>, and <code>tightness</code> parameters are half the opening angles of the
corresponding cones, both angles have to be smaller than 90 degrees. The
light smoothly falls off between the radius and the falloff angle like shown
in the figures below (as long as the radius angle is not negative).</p>
<table class="matte" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/0/0b/RefImgFixfallo.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Intensity multiplier curve with a fixed falloff angle of 45 degrees.</p>
</td>
</tr>
</table>
<p> </p>
<table class="matte" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/c/c8/RefImgFixedrad.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Intensity multiplier curve with a fixed radius angle of 45 degrees.</p>
</td>
</tr>
</table>
<p>The <code>tightness</code> keyword is used to specify an <em>
additional</em> exponential softening of the edges. A value other than 0, will
affect light within the radius cone as well as light in the falloff cone.
The intensity of light at an angle from the center line is given by:
<em><code>intensity * cos(angle)tightness</code></em>.
The default value for tightness is 0. Lower
tightness values will make the spotlight brighter, making the spot wider and
the edges sharper. Higher values will dim the spotlight, making the spot
tighter and the edges softer. Values from 0 to 100 are acceptable.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/1/14/RefImgDiftight.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Intensity multiplier curve with fixed angle and falloff angles of 30 and 60 degrees respectively and different tightness values.</p>
</td>
</tr>
</table>
<p>You should note from the figures that the radius and falloff angles
interact with the tightness parameter. To give the tightness value full control
over the spotlight's appearance use radius 0 falloff 90. As you
can see from the figure below. In that case the falloff angle has no effect
and the lit area is only determined by the tightness parameter.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/e/e2/RefImgNegradli.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Intensity multiplier curve with a negative radius angle and different tightness values.</p>
</td>
</tr>
</table>
<p>Spotlights may be used any place that a normal light source is used. Like
any light sources, they are invisible. They may also be used in conjunction
with area lights.</p>
</div>
<a name="r3_4_4_1_3"></a>
<div class="content-level-h5" contains="Cylindrical Lights" id="r3_4_4_1_3">
<h5>3.4.4.1.3 Cylindrical Lights</h5>
<p>The <code>cylinder</code> keyword specifies a cylindrical light source
that is great for simulating laser beams. Cylindrical light sources work
pretty much like spotlights except that the light rays are constrained by a
cylinder and not a cone. The syntax is:</p>
<pre>
CYLINDER_LIGHT_SOURCE:
light_source {
<Location>, COLOR cylinder
[LIGHT_MODIFIERS...]
}
LIGHT_MODIFIER:
SPOTLIGHT_ITEM | AREA_LIGHT_ITEMS | GENERAL_LIGHT_MODIFIERS
SPOTLIGHT_ITEM:
radius Radius | falloff Falloff | tightness Tightness |
point_at <Spot>
</pre>
<p>
Default values:
</p>
<pre>
radius: 0.75 degrees
falloff: 1 degrees
tightness: 0
</pre>
<p>The <code>point_at</code>, <code>radius</code>, <code>falloff</code> and
<code>tightness</code> keywords control the same features as with the
spotlight. See <a href="r3_4.html#r3_4_4_1_2">Spotlights</a> for details.</p>
<p>You should keep in mind that the cylindrical light source is still a point
light source. The rays are emitted from one point and are only constraint by
a cylinder. The light rays are not parallel.</p>
</div>
<a name="r3_4_4_1_4"></a>
<div class="content-level-h5" contains="Parallel Lights" id="r3_4_4_1_4">
<h5>3.4.4.1.4 Parallel Lights</h5>
<pre>
syntax:
light_source {
LOCATION_VECTOR, COLOR
[LIGHT_SOURCE_ITEMS...]
parallel
point_at VECTOR
}
</pre>
<p>The <code>parallel</code> keyword can be used with any type of light source.</p>
<p class="Note"><strong>Note:</strong> For normal point lights, <code>point_at</code> must come after
<code>parallel</code>.</p>
<p>Parallel lights are useful for simulating very distant light sources, such as
sunlight. As the name suggests, it makes the light rays parallel.</p>
<p>Technically this is done by shooting rays from the closest point on a plane to the
object intersection point. The plane is determined by a perpendicular defined by the
light <code>location</code> and the <code>point_at</code> vector.</p>
<p>Two things must be considered when choosing the light location
(specifically, its distance):</p><ol>
<li>Any parts of an object <em>above</em> the light plane still get illuminated according to
the light direction, but they will not cast or receive shadows.</li>
<li><code>fade_distance</code> and <code>fade_power</code> use the light
<code>location</code> to determine distance for light attenuation, so the attenuation
still looks like that of a point source.
<br>Area light also uses the light location in its calculations.</li></ol>
</div>
<a name="r3_4_4_1_5"></a>
<div class="content-level-h5" contains="Area Lights" id="r3_4_4_1_5">
<h5>3.4.4.1.5 Area Lights</h5>
<p>Area light sources occupy a finite, one or two-dimensional area of space. They can cast soft shadows because an object can partially block their light. Point sources are either totally blocked or not blocked.</p>
<p>The <code>area_light</code> keyword in POV-Ray creates sources that are rectangular in shape, sort of like a flat panel light. Rather than performing the complex calculations that would be required to model a true area light, it is approximated as an array of point light sources spread out over the area occupied by the light. The array-effect applies to shadows only, however with the addition of the <code>area_illumination</code> keyword, full area light diffuse and specular illumination can be achieved. The object's illumination is still that of a point source. The intensity of each individual point light in the array is dimmed so that the total amount of light emitted by the light is equal to the light color specified in the declaration. The syntax is:</p>
<pre>
AREA_LIGHT_SOURCE:
light_source {
LOCATION_VECTOR, COLOR
area_light
AXIS_1_VECTOR, AXIS_2_VECTOR, Size_1, Size_2
[ adaptive Adaptive ] [ area_illumination on/off ]
[ jitter ] [ circular ] [ orient ]
[ [LIGHT_MODIFIERS...]
}
</pre>
<p>Any type of light source may be an area light. </p>
<p>The <code>area_light</code> keyword defines the location, the size and orientation of the area light as well as the number of lights in the light source array. The location vector is the centre of a rectangle defined by the two vectors <em><code><Axis_1></code></em> and <em><code><Axis_2></code></em>. These specify the lengths and directions of the edges of the light.</p>
<table class="centered" width="340x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="320px" src="images/a/a8/RefImgAreal.png">
</td>
</tr>
<tr>
<td>
<p class="caption">4x4 Area light, location and vectors.</p>
</td>
</tr>
</table>
<p>Since the area lights are rectangular in shape these vectors should be perpendicular to each other. The larger the size of the light the thicker the soft part of shadows will be. The integers Size_1 and Size_2 specify the number of rows and columns of point sources of the. The more lights you use the smoother the shadows, but render time will increase.</p>
<p class="Note"><strong>Note:</strong> It is possible to specify spotlight parameters along with the area light parameters to create area spotlights. Using area spotlights is a good way to speed up scenes that use area lights since you can confine the lengthy soft shadow calculations to only the parts of your scene that need them.</p>
<p>An interesting effect can be created using a linear light source. Rather than having a rectangular shape, a linear light stretches along a line sort of like a thin fluorescent tube. To create a linear light just create an area light with one of the array dimensions set to 1.</p>
<p class="Note"><strong>Note:</strong> In version 3.7 experimental support for full area light diffuse and specular illumination was added. </p>
<p>This feature is off by default, so area lights will work as previously expected, and can be turned on by specifying the <code>area_illumination</code> keyword, followed by the optional on/off keyword, in the light source definition. As with area lights, the Size_1 and Size_2 parameters determine the quality of the lighting, as well as the quality of the shadows.</p>
<p>The <code>jitter</code> keyword is optional. When used it causes the positions of the point lights in the array to be randomly jittered to eliminate any shadow banding that may occur. The jittering is completely random from render to render and should not be used when generating animations.</p>
<p>The <code>adaptive</code> keyword is used to enable adaptive sampling of the light source. By default POV-Ray calculates the amount of light that reaches a surface from an area light by shooting a test ray at every point light within the array. As you can imagine this is very slow. Adaptive sampling on the other hand attempts to approximate the same calculation by using a minimum number of test rays. The number specified after the keyword controls how much adaptive sampling is used. The higher the number the more accurate your shadows will be but the longer they will take to render. If you are not sure what value to use a good starting point is <code>adaptive 1</code>. The <code>adaptive</code> keyword only accepts integer values and cannot be set lower than 0.</p>
<p>When performing adaptive sampling POV-Ray starts by shooting a test ray at each of the four corners of the area light. If the amount of light received from all four corners is approximately the same then the area light is assumed to be either fully in view or fully blocked. The light intensity is then calculated as the average intensity of the light received from the four corners. However, if the light intensity from the four corners differs significantly then the area light is partially blocked. The area light is split into four quarters and each section is sampled as described above. This allows POV-Ray to rapidly approximate how much of the area light is in view
without having to shoot a test ray at every light in the array. Visually the sampling goes like shown below.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/1/18/RefImgArealigh.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Area light adaptive samples.</p>
</td>
</tr>
</table>
<p>While the adaptive sampling method is fast (relatively speaking) it can sometimes produce inaccurate shadows. The solution is to reduce the amount of adaptive sampling without completely turning it off. The number after the adaptive keyword adjusts the number of times that the area light will be split before the adaptive phase begins. For example if you use <code>adaptive 0</code> a minimum of 4 rays will be shot at the light. If you use <code>adaptive 1</code> a minimum of 9 rays will be shot (<code>adaptive
2</code> gives 25 rays, <code>adaptive 3</code> gives 81 rays, etc). Obviously the more shadow rays you shoot the slower the rendering will be so you should use the lowest value that gives acceptable results.</p>
<p>The number of rays never exceeds the values you specify for rows and columns of points. For example <code>area_light x,y,4,4</code> specifies a 4 by 4 array of lights. If you specify <code>adaptive 3</code> it would mean that you should start with a 9 by 9 array. In this case no adaptive sampling is done. The 4 by 4 array is used.</p>
<p>The <code>circular</code> keyword has been added to area lights in order to better create circular soft shadows. With ordinary area lights the pseudo-lights are arranged in a rectangular grid and thus project partly rectangular shadows around all objects, including circular objects. By including the <code>circular</code> tag in an area light, the light is stretched and squashed so that it looks like a circle: this way, circular or spherical light sources are better simulated.</p>
<p>A few things to remember:</p>
<ul>
<li>Circular area lights can be ellipses: the AXIS_1_VECTOR and AXIS_2_VECTOR
define the shape and orientation of the circle; if the vectors are not equal, the light
source is elliptical in shape.</li>
<li>Rectangular artefacts may still show up with very large area grids.</li>
<li>There is no point in using <code>circular</code> with linear area lights or area lights which have a 2x2 size.</li>
<li>The area of a circular light is roughly 78.5 per cent of a similar size rectangular area light. Increase your axis vectors accordingly if you wish to keep the light source area constant.</li>
</ul>
<p>The <code>orient</code> keyword has been added to area lights in order to better create soft shadows. Without this modifier, you have to take care when choosing the axis vectors of an area_light, since they define both its area and orientation. Area lights are two dimensional: shadows facing the area light receive light from a larger surface area than shadows at the sides of the area light.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/6/63/RefImgArea2.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Area light facing object.</p>
</td>
</tr>
</table>
<p>Actually, the area from which light is emitted at the sides of the area light is reduced to a single line, only casting soft shadows in one direction.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/6/65/RefImgArea1.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Area light not facing object.</p>
</td>
</tr>
</table>
<p>Between these two extremes the surface area emitting light progresses gradually. By including the <code>orient</code> modifier in an area light, the light is rotated so that for every shadow test, it always faces the point being tested. The initial orientation is no longer important, so you only have to consider the desired dimensions (area) of the light source when specifying the axis vectors. In effect, this makes the area light source appear 3-dimensional (e.g. an area_light with perpendicular axis vectors of the same size and dimensions using <code>circular</code> <em>and</em> <code>orient</code> simulates a spherical light source).</p>
<p>Orient has a few restrictions:</p>
<ol>
<li>It can be used with <em>circular</em> lights only.</li>
<li>The two axes of the area light must be of equal length.</li>
<li>The two axes of the area light should use an equal number of samples, and that number should be greater than one</li>
</ol>
<p>These three rules exist because without them, you can get unpredictable results from the orient feature.</p>
<p>If one of the first two rules is broken, POV-Ray will issue a warning and correct the problem. If the third rule is broken, you will only get the error message, and POV-Ray will not automatically correct the problem.</p>
</div>
<a name="r3_4_4_1_6"></a>
<div class="content-level-h5" contains="Shadowless Lights" id="r3_4_4_1_6">
<h5>3.4.4.1.6 Shadowless Lights</h5>
<p>Using the <code>shadowless</code> keyword you can stop a light source from
casting shadows. These lights are sometimes called <em>fill lights</em>.
They are another way to simulate ambient light however shadowless lights have
a definite source. The syntax is:</p>
<pre>
SHADOWLESS_LIGHT_SOURCE:
light_source {
<Location>, COLOR shadowless
[LIGHT_MODIFIERS...]
}
LIGHT_MODIFIER:
AREA_LIGHT_ITEMS | GENERAL_LIGHT_MODIFIERS
</pre>
<p><code>shadowless</code> may be used with all types of light sources.
The only restriction is that <code>shadowless</code> should be before or
after <em>all</em> spotlight or cylinder option keywords. Do not mix or you get
the message <em>Keyword 'the one following shadowless' cannot be used with
standard light source</em>. Also note that shadowless lights will not cause
highlights on the illuminated objects.</p>
</div>
<a name="r3_4_4_1_7"></a>
<div class="content-level-h5" contains="Looks_like" id="r3_4_4_1_7">
<h5>3.4.4.1.7 Looks_like</h5>
<p>Normally the light source itself has no visible shape. The light simply
radiates from an invisible point or area. You may give a light source any
shape by adding a <code>looks_like {</code><em> OBJECT</em> <code>}</code>
statement.</p>
<p>There is an implied <code>no_shadow</code> attached to the <code>
looks_like</code> object so that light is not blocked by the object. Without
the automatic <code>no_shadow</code> the light inside the object would not
escape. The object would, in effect, cast a shadow over everything.</p>
<p>If you want the attached object to block light then you should attach it
with a <code>union</code> and not a <code>looks_like</code> as follows:</p>
<pre>
union {
light_source { <100, 200, -300> color White }
object { My_Lamp_Shape }
}
</pre>
<p>Presumably parts of the lamp shade are transparent to let some light out.</p>
</div>
<a name="r3_4_4_1_8"></a>
<div class="content-level-h5" contains="Projected_Through" id="r3_4_4_1_8">
<h5>3.4.4.1.8 Projected_Through</h5>
<p>Syntax:</p>
<pre>
light_source {
LOCATION_VECTOR, COLOR
[LIGHT_SOURCE_ITEMS...]
projected_through { OBJECT }
}
</pre>
<p>Projected_through can be used with any type of light source. Any object can be
used, provided it has been declared before.
<br>Projecting a light through an object can be thought of as the opposite of
shadowing: only the light rays that hit the projected_through object
will contribute to the scene.
<br>This also works with area_lights, producing spots of light with soft edges.
<br>Any objects between the light and the projected through object will not cast
shadows for this light. Also any surface within the projected through object
will not cast shadows.
<br>Any textures or interiors on the object will be stripped and the object will not
show up in the scene.</p>
</div>
<a name="r3_4_4_1_9"></a>
<div class="content-level-h5" contains="Light Fading" id="r3_4_4_1_9">
<h5>3.4.4.1.9 Light Fading</h5>
<p>By default POV-Ray does not diminish light from any light source as it
travels through space. In order to get a more realistic effect <code>
fade_distance</code> and <code>fade_power</code> keywords followed by float
values can be used to model the distance based falloff in light
intensity.</p>
<p>The <code>fade_distance</code> is used to specify the distance at which the full light intensity arrives, i.e.: the intensity which was given by the <code>color</code> attribute. The actual attenuation is described by the <code>fade_power</code> keyword, which determines the falloff rate. For example linear or quadratic falloff can be used by setting the <code>fade_power</code> to 1 or 2 respectively.</p>
<p>The complete formula to calculate the factor by which the light is attenuated is:</p>
<table class="centered" width="415px" cellpadding="0" cellspacing="10">
<tr>
<td>
<!--<img src="ref_tex/lattenua.tex" alt="">---><img class="center" width="395px" src="images/6/69/RefImgLattenua.png">
</td>
</tr>
<tr>
<td>
<p class="caption">The attenuation of light fading formula</p>
</td>
</tr>
</table>
<p>Where <em><code>d</code></em> is the distance the light has traveled.</p>
<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/4/4d/RefImgLfadefx.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Light fading functions for different fading powers</p>
</td>
</tr>
</table>
<p>With any given value for <code>fade_distance</code>, either larger <em>OR</em> smaller than one, the light intensity at distances smaller than that given value actually increases. The internal calculation used to determine the <em>attenuation</em> factor is set up in a way so that one could set the fade distance and know that for any given fade distance, the light value would equal the set intensity. Lastly, only light coming directly from light sources is attenuated, and that reflected or refracted light is not attenuated by distance.</p>
<p>However, further investigation does reveal certain short comings with this method, as it doesn't follow a very good inverse-squared relationship over the fade distance and somewhat beyond. In other words, the function does break down to be very close to inverse squared as the distance from the given value for <code>fade_distance</code> gets significantly larger.</p>
<p>To that end consider the following:</p>
<p>A value for the light source intensity can be easily calculated when you take into account the distance from the light source to the scene center, or the object to be illuminated, and you set a relatively small value for <code>fade_distance</code> e.g.: the size of the light itself, relative to the scene dimensions.</p>
<p>The following example, that takes the inverse of the above formula that was used to calculate the factor by which the light is attenuated.</p>
<pre>
// setup the function
#declare Intensity_Factor = function (LD,FD,FP) {pow(1+(LD/FD),FP)/2};
// the translated position of the light source
#declare Light_Position = <0,0,-2400>;
// determine the light distance
#declare Light_Distance = vlength(Light_Position-<0,0,0>);
// scaled size of the light source
#declare Fade_Distance = 4.5;
// linear (1) or quadratic (2) falloff
#declare Fade_Power = 2;
</pre>
<p class="Note"><strong>Note:</strong> The above example calculates <em>Light_Distance</em> to the scene center, but you could have just as easily used the location of an object.</p>
<p>Now all you have to do is setup the light source. The <code>#debug</code> statements make it easy to see whats going on while tuning the light source.</p>
<pre>
#debug concat ("\nFade Distance: ", str(Fade_Distance,2,4))
#debug concat ("\nLight Distance: ", str(Light_Distance,5,4)," \n")
#debug concat ("Intensity Factor: ", str(Intensity_Factor (Light_Distance, Fade_Distance, Fade_Power),6,4)
#debug concat ("\n\n")
light_source {
0, rgb <0.9,0.9,1> * Intensity_Factor (Light_Distance, Fade_Distance, Fade_Power)
fade_distance Fade_Distance
fade_power Fade_Power
translate Light_Position
}
</pre>
<p>At first glance this may seem counter-intuitive but it works out well given the small value used for <em>Fade_Distance</em>. You should be aware that this method is meant to give a light strength value of <em>ONE</em> at the point of interest <em>ONLY</em>. In other words, the point represented by the calculated value <em>Light_Distance</em> in the above example. Naturally objects closer to the light source will get a stronger illumination, while objects further away will receive less.</p>
</div>
<a name="r3_4_4_1_10"></a>
<div class="content-level-h5" contains="Atmospheric Media Interaction" id="r3_4_4_1_10">
<h5>3.4.4.1.10 Atmospheric Media Interaction</h5>
<p>By default light sources will interact with an atmosphere added to the
scene. This behavior can be switched off by using <code>media_interaction off</code>
inside the light source statement. </p>
<p class="Note"><strong>Note:</strong> In POV-Ray 3.0 this feature was turned off
and on with the <code>atmosphere</code> keyword.</p>
</div>
<a name="r3_4_4_1_11"></a>
<div class="content-level-h5" contains="Atmospheric Attenuation" id="r3_4_4_1_11">
<h5>3.4.4.1.11 Atmospheric Attenuation</h5>
<p>Normally light coming from light sources is not influenced by fog or
atmospheric media. This can be changed by turning the <code>media_attenuation on</code>
for a given light source on. All light coming from this light source will now
be diminished as it travels through the fog or media. This results in an
distance-based, exponential intensity falloff ruled by the used fog or media.
If there is no fog or media no change will be seen.</p>
<p class="Note"><strong>Note:</strong> In POV-Ray 3.0 this
feature was turned off and on with the <code>atmospheric_attenuation</code> keyword.</p>
</div>
<a name="r3_4_4_2"></a>
<div class="content-level-h4" contains="Light Group" id="r3_4_4_2">
<h4>3.4.4.2 Light Group</h4>
<p>Light groups make it possible to create a <code>union</code> of light sources and objects, where the objects in the group are illuminated by the lights in the group or, if so desired, by the global light sources as well. The light sources in the group can <em>only</em> illuminate the objects that are in the group, this also applies to <code>scattering</code> media, and it <em>must</em> be included in the light group as well. Keep in mind that if the scattering media also has an <code>absorption</code> component, it <em>will</em> be affected by light sources that are <em>not</em> in the light group definition.</p>
<p>Light groups are for example useful when creating scenes in which some objects turn out to be too dark but the average light is exactly how it should be, as the light sources in the group do not contribute to the global lighting.</p>
<p>Syntax :</p>
<pre>
light_group {
LIGHT_GROUP LIGHT |
LIGHT_GROUP OBJECT |
LIGHT_GROUP
[LIGHT_GROUP MODIFIER]
}
LIGHT_GROUP LIGHT:
light_source | light_source IDENTIFIER
LIGHT_GROUP OBJECT:
OBJECT | OBJECT IDENTIFIER
LIGHT_GROUP MODIFIER:
global_lights BOOL | TRANSFORMATION
</pre>
<ul>
<li>To illuminate objects in the group with the light from global light sources, add <code>global_lights on</code> to the light group definition.</li>
<li>Light groups may be nested. In this case light groups inherit the light sources of the light group in which they are contained.</li>
<li>Light groups can be seen as a <code>union</code> of an object with a <code>light_source</code> and can be used with CSG.</li>
</ul>
<p>Some examples of a simple light group:</p>
<pre>
#declare RedLight =
light_source {
<-500,500,-500>
rgb <1,0,0>
}
light_group {
light_source {RedLight}
sphere {0,1 pigment {rgb 1}}
global_lights off
}
</pre>
<p>A nested light group:</p>
<pre>
#declare L1 =
light_group {
light_source {<10,10,0>, rgb <1,0,0>}
light_source {<0,0,-100>, rgb <0,0,1>}
sphere {0,1 pigment {rgb 1}}
}
light_group {
light_source {<0,100,0>, rgb 0.5}
light_group {L1}
}
</pre>
<p>Light groups with CSG:</p>
<pre>
difference {
light_group {
sphere {0,1 pigment {rgb 1}}
light_source {<-100,0,-100> rgb <1,0,0>}
global_lights off
}
light_group {
sphere {<0,1,0>,1 pigment {rgb 1}}
light_source {<100,100,0> rgb <0,0,1>}
global_lights off
}
rotate <-45,0,0>
}
</pre>
<p>In the last example the result will be a sphere illuminated red, where the part that is differenced away is illuminated blue. The end result is comparable to the difference between two spheres with a different pigment.</p></div>
<a name="r3_4_4_3"></a>
<div class="content-level-h4" contains="Radiosity" id="r3_4_4_3">
<h4>3.4.4.3 Radiosity</h4>
</div>
<a name="r3_4_4_3_1"></a>
<div class="content-level-h5" contains="Radiosity Basics" id="r3_4_4_3_1">
<h5>3.4.4.3.1 Radiosity Basics</h5>
<p>Radiosity is an extra calculation that more realistically computes the diffuse inter-reflection of light. This diffuse inter-reflection can be seen if you place a white chair in a room full of blue carpet, blue walls and blue curtains. The chair will pick up a blue tint from light reflecting off of other parts of the room. Also notice that the shadowed areas of your surroundings are not totally dark even if no light source shines directly on the surface. Diffuse light reflecting off of other objects fills in the shadows. Typically ray-tracing uses a trick called <em> ambient</em> light to simulate such effects but it is not very accurate.</p>
<p>Radiosity calculations are only made when a <code>radiosity{}</code> block is used inside the <code>global_settings{}</code> block.</p>
<p>The following sections describes how radiosity works, how to control it with various global settings and tips on trading quality vs. speed.</p>
</div>
<a name="r3_4_4_3_2"></a>
<div class="content-level-h5" contains="How Radiosity Works" id="r3_4_4_3_2">
<h5>3.4.4.3.2 How Radiosity Works</h5>
<p>The problem of ray-tracing is to figure out what the light level is at each point that you can see in a scene. Traditionally, in ray tracing, this is broken into the sum of these components:</p>
<dl>
<dt>Diffuse</dt><dd>the effect that makes the side of things facing the light brighter;</dd>
<dt>Specular</dt><dd>the effect that makes shiny things have dings or sparkles on them;</dd>
<dt>Reflection</dt><dd>the effect that mirrors give; and</dd>
<dt>Ambient</dt><dd>the general all-over light level that any scene has, which keeps things in shadow from being pure black.</dd>
</dl>
<p>POV-Ray's radiosity system, based on a method by Greg Ward, provides a way to replace the last term - the constant ambient light value - with a light level which is based on what surfaces are nearby and how bright in turn they are.</p>
<p>The first thing you might notice about this definition is that it is circular: the brightness and color of everything is dependent on everything else and vice versa. This is true in real life but in the world of ray-tracing, we can make an approximation. The approximation that is used is: the objects you are looking at have their <code>ambient</code> values calculated for you by
checking the other objects nearby. When those objects are checked during this process, however, their <code>diffuse</code> term is used. The brightness of radiosity in POV-Ray is based on two things:</p>
<ol>
<li>the amount of light gathered</li>
<li>the diffuse property of the surface finish</li>
</ol>
<p class="Note"><strong>Note:</strong> The following is an <em>important</em> behavior change!</p>
<p>Previously an object could have both radiosity and an ambient term. This is no longer the case, as when radiosity is used an objects ambient term is effectively set to zero. See the <code><a href="r3_4.html#r3_4_6_3_2">emission</a></code> keyword that has been added to the <code>finish</code> block if the intent is to model a glowing object.</p>
<p>How does POV-Ray calculate the ambient term for each point? By sending out more rays, in many different directions, and averaging the results. A typical point might use 200 or more rays to calculate its ambient light level correctly.</p>
<p>Now this sounds like it would make the ray-tracer 200 times slower. This is true, except that the software takes advantage of the fact that ambient light levels change quite slowly (remember, shadows are calculated separately, so sharp shadow edges are not a problem). Therefore, these extra rays are sent out only <em>once in a while</em> (about 1 time in 50), then these calculated
values are saved and reused for nearby pixels in the image when possible.</p>
<p>This process of saving and reusing values is what causes the need for a variety of tuning parameters, so you can get the scene to look just the way you want.</p>
</div>
<a name="r3_4_4_3_3"></a>
<div class="content-level-h5" contains="Adjusting Radiosity" id="r3_4_4_3_3">
<h5>3.4.4.3.3 Adjusting Radiosity</h5>
<p>As described earlier, radiosity is turned on by using the <code>radiosity{}</code> block in <code>global_setting</code>.
Radiosity has many parameters that are specified as follows:</p>
<pre>
global_settings { radiosity { [RADIOSITY_ITEMS...] } }
RADIOSITY_ITEMS:
adc_bailout Float | always_sample Bool | brightness Float |
count Integer [,Integer] | error_bound Float | gray_threshold Float |
low_error_factor Float | max_sample Float | media Bool |
maximum_reuse Float | minimum_reuse Float | nearest_count Integer [,Integer] |
normal Bool | pretrace_start Float |
pretrace_end Float | recursion_limit Integer | subsurface Bool
</pre>
<p>Each item is optional and may appear in any order. If an item is specified more than once the last setting overrides previous values. Details on each item is given in the following sections.</p>
<p class="Note"><strong>Note:</strong> Considerable changes have been made to the way radiosity works in POV-Ray 3.7
compared to previous versions. Old scenes will not render with exactly the same results. It is <em>not</em> possible to use the <code>#version</code> directive to get backward compatibility for radiosity.</p>
</div>
<a name="r3_4_4_3_3_1"></a>
<div class="content-level-h6" contains="adc_bailout" id="r3_4_4_3_3_1">
<h6>3.4.4.3.3.1 adc_bailout</h6>
<p>You can specify an adc_bailout for radiosity rays. Usually the default of 0.01 will give good results, but for scenes with bright emissive objects it should be set to <code>adc_bailout = 0.01 / brightest_emissive_object</code>.</p>
</div>
<a name="r3_4_4_3_3_2"></a>
<div class="content-level-h6" contains="always_sample" id="r3_4_4_3_3_2">
<h6>3.4.4.3.3.2 always_sample</h6>
<p>Since <code>always_sample off</code> is the default, POV-Ray will only use the data from the pretrace step and not gather any new samples during the final radiosity pass. This produces higher quality results, and quicker renders. It may also reduce the splotchy appearance of the radiosity samples, and can be very useful when reusing previously saved radiosity data. If you find the need to override the behavior, you can do so by specifying <code>always_sample on</code>.</p>
</div>
<a name="r3_4_4_3_3_3"></a>
<div class="content-level-h6" contains="brightness" id="r3_4_4_3_3_3">
<h6>3.4.4.3.3.3 brightness</h6>
<p>The <code>brightness</code> keyword specifies a float value that is the degree to which objects are brightened before being returned upwards to the rest of the system. Ideally brightness should be set to the default value of 1.0. If the overall brightness doesn't seem to fit, the diffuse color of objects and/or the overall brightness of light sources (including emission > 0 objects) should be adjusted.</p>
<p>As an example, a typical problem encountered in radiosity scenes is, when setting <code>pigment {rgb 1}</code> and <code>diffuse 1.0</code>, then tweaking the light source(s) and <code>ambient_light</code> setting to make the image look right. It just doesn't work properly in radiosity scenes, as it will give too strong inter-reflections. While you <em>can</em> compensate for this by reducing radiosity brightness, it's generally discouraged. In this case the surface properties should be fixed (e.g. diffuse set to something around 0.7, which is much more realistic).</p>
<p>An exception, calling for the adjustment of radiosity brightness, would be to compensate for a low <code>recursion_limit</code> setting (e.g <code>recursion_limit 1</code>). In such a case, increasing <code>brightness</code> will help maintain a realistic overall brightness.</p>
</div>
<a name="r3_4_4_3_3_4"></a>
<div class="content-level-h6" contains="count" id="r3_4_4_3_3_4">
<h6>3.4.4.3.3.4 count</h6>
<p>The integer number of rays that are sent out whenever a new radiosity value has to be calculated is given by <code>count</code>. The default value is 35, if the value exceeds 1600, POV-Ray will use a <em>Halton</em> sequence instead of the default built-in sequence. When this value is too low, the light level will tend to look a little bit blotchy, as if the surfaces you are looking at were slightly warped. If this is not important to your scene (as in the case that you have a bump map or if you have a strong texture) then by all means use a lower number.</p>
<p>By default, POV-Ray uses the same set of directions for each new radiosity value to calculate. In order to cover more directions in total without increasing the number of rays to trace, <code>count</code> accepts an optional second parameter which specifies the total number of directions from which to choose. POV-Ray will then draw directions from this pool in a round-robin fashion.</p>
</div>
<a name="r3_4_4_3_3_5"></a>
<div class="content-level-h6" contains="error_bound" id="r3_4_4_3_3_5">
<h6>3.4.4.3.3.5 error_bound</h6>
<p>The <code>error_bound</code> float value is one of the two main speed/quality tuning values (the other is of course the number of rays shot). In an ideal world, this would be the <em>only</em> value needed. It is intended to mean the fraction of error tolerated. For example, if it were set to 1 the algorithm would not calculate a new value until the error on the last one was estimated at as high as 100%. Ignoring the error introduced by rotation for the moment, on flat surfaces this is equal to the fraction of the reuse distance, which in turn is the distance to the closest item hit. If you have an old sample on the floor 10 inches from a wall, an error bound of 0.5 will get you a new sample at a distance of about 5 inches from the wall.</p>
<p>The default value of 1.8 is good for a smooth general lighting effect. Using lower values is more accurate, but it will strongly increase the danger of artifacts and therefore require higher <code>count</code>. You can use values even lower than 0.1 but both render time and memory use can become extremely high.</p>
</div>
<a name="r3_4_4_3_3_6"></a>
<div class="content-level-h6" contains="gray_threshold" id="r3_4_4_3_3_6">
<h6>3.4.4.3.3.6 gray_threshold</h6>
<p>Diffusely inter-reflected light is a function of the objects around the point in question. Since this is recursively defined to millions of levels of recursion, in any real life scene, every point is illuminated at least in part by every other part of the scene. Since we cannot afford to compute this, if we only do one bounce, the calculated ambient light is very strongly affected by the colors of the objects near it. This is known as color bleed and it really happens but not as much as this calculation method would have you believe. The <code>gray_threshold</code> float value grays it down a little, to make your scene more believable. A value of .6 means to calculate the ambient value as 60% of the equivalent gray value calculated, plus 40% of the actual value calculated. At 0%, this feature does nothing. At 100%, you always get white/gray ambient light, with no hue.</p>
<p class="Note"><strong>Note:</strong> This does not change the lightness/darkness, only the strength of hue/grayness (in HLS
terms, it changes S only). The default value is 0.0</p>
</div>
<a name="r3_4_4_3_3_7"></a>
<div class="content-level-h6" contains="low_error_factor" id="r3_4_4_3_3_7">
<h6>3.4.4.3.3.7 low_error_factor</h6>
<p>If you calculate just enough samples, but no more, you will get an image which has slightly blotchy lighting. What you want is just a few extra interspersed, so that the blending will be nice and smooth. The solution to this is the mosaic preview, controlled by
<a href="r3_4.html#r3_4_4_3_3_12">pretrace</a>, it goes over the image one or more times beforehand, calculating radiosity values. To ensure that you get a few extra, the radiosity algorithm lowers the error bound during the pre-final passes, then sets it back just before the final pass. The <code>low_error_factor</code> is a float tuning value which sets the amount that the error bound is dropped during the preliminary image passes. If your low error factor is 0.8 and your error bound is set to 0.4 it will really use an error bound of 0.32 during the first passes and 0.4 on the final pass. The default value is 0.5.</p>
</div>
<a name="r3_4_4_3_3_8"></a>
<div class="content-level-h6" contains="max_sample" id="r3_4_4_3_3_8">
<h6>3.4.4.3.3.8 max_sample</h6>
<p>Sometimes there can be splotchy patches that are caused by objects that are very bright. This can be sometimes avoided by using the <code>max_sample</code> keyword. <code>max_sample</code> takes a float parameter which specifies the brightest that any gathered sample is allowed to be. Any samples brighter than this will have their brightness decreased (without affecting color). Note however that this mechanism will somewhat darken the overall brightness in an unrealistic way. Specifying a non-positive value for <code>max_sample</code> will allow any brightness of samples (which is the default).</p>
</div>
<a name="r3_4_4_3_3_9"></a>
<div class="content-level-h6" contains="maximum_reuse" id="r3_4_4_3_3_9">
<h6>3.4.4.3.3.9 maximum_reuse</h6>
<p>The <code>maximum_reuse</code> parameter works in conjunction with, and is similar to that of <code>minimum_reuse</code>, the only difference being that it is an upper bound rather than a lower one. The default value is 0.200.</p>
<p class="Note"><strong>Note:</strong> If you choose to adjust either the <code>minimum_reuse</code> or <code>maximum_reuse</code> settings they are subject to the criteria listed below:</p>
<ul>
<li>If <code>minimum_reuse > maximum_reuse/2</code> with only one value is specified, a warning is issued and the unspecified value is adjusted.</li>
<li>If <code>minimum_reuse > maximum_reuse/2</code> with both values specified, a warning is issued and neither value is modified.</li>
<li>If <code>minimum_reuse >= maximum_reuse</code>, an error is generated.</li>
</ul>
</div>
<a name="r3_4_4_3_3_10"></a>
<div class="content-level-h6" contains="minimum_reuse" id="r3_4_4_3_3_10">
<h6>3.4.4.3.3.10 minimum_reuse</h6>
<p>The minimum effective radius ratio is set by <code>minimum_reuse</code> float value. This is the fraction of the screen width which sets the minimum radius of reuse for each sample point (actually, it is the fraction of the distance from the eye but the two are roughly equal for normal camera angles). For example, if the value is 0.02, the radius of maximum reuse for every sample is set to whatever ground distance corresponds to 2% of the width of the screen. Imagine you sent a ray off to the horizon and it hits the ground at a distance of 100 miles from your eye point. The reuse distance for that sample will be set to 2 miles. At a resolution of 300*400 this will correspond to (very roughly) 8 pixels. The theory is that you do not want to calculate values for every pixel into every crevice everywhere in the scene, it will take too long. This sets a minimum bound for the reuse. If this value is too low, (which it should be in theory) rendering gets slow, and inside corners can get a little grainy. If it is set too high, you do not get the natural darkening of illumination near inside edges, since it reuses. At values higher than 2% you start getting more just plain errors, like reusing the illumination of the open table underneath the apple. Remember that this is a unit less ratio. The default value is 0.015.</p>
</div>
<a name="r3_4_4_3_3_11"></a>
<div class="content-level-h6" contains="nearest_count" id="r3_4_4_3_3_11">
<h6>3.4.4.3.3.11 nearest_count</h6>
<p>The <code>nearest_count</code> integer value is the minimum number of old radiosity values blended together to create a new interpolated value. There is no upper limit on the number of samples blended, all available samples are blended that match the <code>error_bound</code> and <code>maximum_reuse</code> settings. When an optional second parameter (adaptive radiosity pretrace) is specified after the <code>nearest_count</code> keyword, pretrace will stop re-iterating over areas where, on average, that many average-quality samples are already present per ray. (The actual number of samples required to satisfy the <code>nearest_count</code> settings is influenced by sample quality, with high-quality samples reducing the effective number of samples required, down to 1/4 of the parameter value in extreme cases, and low-quality samples increasing the number.) With a setting lower than 4, things can get pretty patchy, this can be useful for debugging. Conversely, the <code>nearest_count</code> upper limit setting is 20, since values greater than 20 are not very useful in practice, and that is currently the size of the array allocated. The default value is 5.</p>
</div>
<a name="r3_4_4_3_3_12"></a>
<div class="content-level-h6" contains="pretrace_start and pretrace_end" id="r3_4_4_3_3_12">
<h6>3.4.4.3.3.12 pretrace_start and pretrace_end</h6>
<p>To control the radiosity pre-trace gathering step, use the keywords <code>pretrace_start</code> and <code>pretrace_end</code>. Each of these is followed by a decimal value between 0.0 and 1.0 which specifies the size of the blocks in the mosaic preview as a percentage of the image size. The defaults are 0.08 for <code>pretrace_start</code> and 0.04 for <code>pretrace_end</code>.</p>
</div>
<a name="r3_4_4_3_3_13"></a>
<div class="content-level-h6" contains="recursion_limit" id="r3_4_4_3_3_13">
<h6>3.4.4.3.3.13 recursion_limit</h6>
<p>The <code>recursion_limit</code> is an integer value which determines how many recursion levels are used to calculate the diffuse inter-reflection. The default value is 2, the upper limit is 20. In practice, values greater than 3 are seldom useful.</p>
</div>
<a name="r3_4_4_3_4"></a>
<div class="content-level-h5" contains="Configuring Radiosity" id="r3_4_4_3_4">
<h5>3.4.4.3.4 Configuring Radiosity</h5>
<p>The following parameters deal with configuring radiosity and how it interacts with other features. See also these additional command line <a href="r3_2.html#r3_2_8_8">options</a> for more control.</p>
</div>
<a name="r3_4_4_3_4_1"></a>
<div class="content-level-h6" contains="Importance" id="r3_4_4_3_4_1">
<h6>3.4.4.3.4.1 Importance</h6>
<p>If you have some comparatively small yet bright objects in your scene, radiosity will tend to produce bright splotchy artifacts unless you use a pretty high number of rays, which in turn will tremendously increase rendering time. To somewhat mitigate this issue, full ray computations are performed only for a certain portion of sample rays, depending on the ''importance'' of the first object each ray encounters. Importance can be assigned on a per-object basis using the following syntax:
</p>
<pre>
sphere { ... radiosity { importance IMPORTANCE } }
</pre>
<p>Where IMPORTANCE is a value in the range of <em>greater than 0.0 to less than or equal to 1.0</em> specifying the percentage of rays to actually compute on average. A particular ray will only be fully computed if it is within the first COUNT*IMPORTANCE rays of the sampling sequence; due to the low-discrepancy sub-random nature of the sequence, this is mostly equivalent to a per-ray weighted random choice, while maintaining a low-discrepancy uniform distribution on a per-object basis. Rays actually computed are weighted to compensate for those not computed.</p>
<p>Objects derived from previously defined objects will default to the <em>inherited</em> importance. CSG components without an explicit importance value set will default to their parent object's importance. Other objects will normally default to <code>importance 1.0</code>, however this can be changed in a <code>default{}</code> block:</p>
<pre>
default { radiosity { importance DEFAULT_IMPORTANCE } }
</pre>
</div>
<a name="r3_4_4_3_4_2"></a>
<div class="content-level-h6" contains="Media and Radiosity" id="r3_4_4_3_4_2">
<h6>3.4.4.3.4.2 Media and Radiosity</h6>
<p>Radiosity estimation can be affected by media. To enable this feature, add <code>media on</code> to the <code>radiosity{}</code> block. The default is <code>off</code></p>
</div>
<a name="r3_4_4_3_4_3"></a>
<div class="content-level-h6" contains="No Radiosity" id="r3_4_4_3_4_3">
<h6>3.4.4.3.4.3 No Radiosity</h6>
<p>Specifying <code>no_radiosity</code> in an object block makes that object invisible to radiosity rays, in the same way as <code>no_image</code>, <code>no_reflection</code> and <code>no_shadow</code> make an object invisible to primary, reflected and shadow test rays, respectively.</p>
</div>
<a name="r3_4_4_3_4_4"></a>
<div class="content-level-h6" contains="Normal and Radiosity" id="r3_4_4_3_4_4">
<h6>3.4.4.3.4.4 Normal and Radiosity</h6>
<p> Radiosity estimation can be affected by normals. To enable this feature, add <code>normal on</code> to the <code>radiosity{}</code> block. The default is <code>off</code></p>
</div>
<a name="r3_4_4_3_4_5"></a>
<div class="content-level-h6" contains="Save and Load Radiosity Data" id="r3_4_4_3_4_5">
<h6>3.4.4.3.4.5 Save and Load Radiosity Data</h6>
<p>In general, it is not a good idea to save and load radiosity data if scene objects are moving. Even after the data is loaded, more samples may be taken during the final rendering phase, particularly if you've specified <code>always_sample on</code>.</p>
<p class="Note"><strong>Note:</strong> The method to load and save radiosity data has been changed to a command line option. See section <a href="r3_2.html#r3_2_8_8_2">radiosity load and save</a> for more details.</p>
</div>
<a name="r3_4_4_3_4_6"></a>
<div class="content-level-h6" contains="Subsurface and Radiosity" id="r3_4_4_3_4_6">
<h6>3.4.4.3.4.6 Subsurface and Radiosity</h6>
<p>To specify whether radiosity sampling should <em>honor</em> subsurface light transport, you should place the following in the global settings <code>radiosity</code> block:</p>
<pre>
global_settings {
radiosity { subsurface BOOL }
}
</pre>
<p>If this setting is <code>off</code>, the default, radiosity based diffuse illumination is computed as if the surrounding objects had subsurface light transport turned off. Setting this to <code>on</code> may improve realism especially in the presence of materials with high translucency, but at some cost in rendering time.</p>
<p>See the section <a href="r3_4.html#r3_4_6_3_3_4">Subsurface Light Transport</a> for more information about the role of <code>subsurface</code> in the global settings block.</p>
</div>
<a name="r3_4_4_3_5"></a>
<div class="content-level-h5" contains="Tips on Radiosity" id="r3_4_4_3_5">
<h5>3.4.4.3.5 Tips on Radiosity</h5>
<p>Have a look at the <a href="t2_3.html#t2_3_8">Radiosity Tutorial</a> to get a feel for what the visual result of changing radiosity parameters is.</p>
<p>If you want to see where your values are being calculated set radiosity <code>count</code> down to about 20, set radiosity <code>nearest_count</code> to 1 and set <code>gray_threshold</code> to 0. This will make everything maximally patchy, so you will be able to see the borders between patches. There will have been a radiosity calculation at the center of most patches. As a bonus, this is quick to run. You can then change the <code> error_bound</code> up and down to see how it changes things. Likewise
modify <code>minimum_reuse</code>.</p>
<p>One way to get extra smooth results: crank up the sample count (we have gone as high as 1300) and drop the <code>low_error_factor</code> to something small like 0.6. Bump up the <code> nearest_count</code> to 7 or 8. This will get better values, and more of them, then interpolate among more of them on the last pass. This is not for people with a lack of patience since it is like a squared function. If your blotchiness is only in certain corners or near certain objects try tuning the error bound instead. Never drop it by more than a little at a time, since the run time will get very long.</p>
<p>Sometimes extra samples are taken during the final rendering pass, if you've specified <code>always_sample on</code>. These newer samples can cause discontinuities in the radiosity in some scenes. To decrease these artifacts, use a <code>pretrace_end</code> of 0.04 (or even 0.02 if you are really patient and picky). This will cause the majority of the samples to be taken during the preview passes, and decrease the artifacts created during the final rendering pass. Be sure to force POV-Ray to only use the data from the pretrace step and not gather any new samples during the final radiosity pass, by removing <code>always_sample on</code> from within the <code>global_settings</code> radiosity block.</p>
<p>If your scene uses ambient objects (especially small ambient objects) as light sources, you should probably use a higher count (100-150 and higher). For such scenes, an error_bound of 1.0 is usually good. A higher value causes too much error, but lower causes very slow rendering. It is important to adjust adc_bailout.</p></div>
<a name="r3_4_4_4"></a>
<div class="content-level-h4" contains="Photons" id="r3_4_4_4">
<h4>3.4.4.4 Photons</h4>
<p>With <code>photons</code> it is possible to render true reflective and refractive caustics. The photon map was first introduced by Henrik Wann Jensen (see <a href="t2_5.html#t2_5_9">Suggested Reading</a>).</p>
<p>Photon mapping is a technique which uses a forward ray-tracing
pre-processing step to render refractive and reflective caustics realistically.
This means that mirrors can reflect light rays and lenses can focus light.</p>
<p>Photon mapping works by shooting packets of light (photons) from light
sources into the scene. The photons are directed towards specific objects. When
a photon hits an object after passing through (or bouncing off of) the target
object, the ray intersection is stored in memory. This data is later used to
estimate the amount of light contributed by reflective and refractive caustics.</p>
</div>
<a name="r3_4_4_4_1"></a>
<div class="content-level-h5" contains="Examples" id="r3_4_4_4_1">
<h5>3.4.4.4.1 Examples</h5>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<p>This image shows refractive caustics from a sphere and a cylinder. Both use an index of refraction of <code>1.2</code>. Also visible is a small amount of reflective caustics from the metal sphere, and also from the clear cylinder and sphere.</p>
</td>
<td>
<img class="right" width="320px" src="images/3/3d/RefImgPhotons1.png">
</td>
</tr>
<tr>
<td></td>
<td>
<p class="caption">Reflective caustics</p>
</td>
</tr>
</table>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="left" width="320px" src="images/6/6c/RefImgPhotons2.png">
</td>
<td>
<p>Here we have three lenses and three light sources. The middle lens has photon mapping turned off. You can also see some reflective caustics from the brass box (some light reflects and hits the blue box, other light bounces through the nearest lens and is focused in the lower left corner of the image).</p>
</td>
</tr>
<tr>
<td>
<p class="caption">Photons used for lenses and caustics</p>
</td>
<td></td>
</tr>
</table>
</div>
<a name="r3_4_4_4_2"></a>
<div class="content-level-h5" contains="Using Photon Mapping in Your Scene" id="r3_4_4_4_2">
<h5>3.4.4.4.2 Using Photon Mapping in Your Scene</h5>
<p>When designing a scene with photons, it helps to think of the scene objects
in two categories. Objects in the first category will show photon caustics
when hit by photons. Objects in the second category cause photon caustics
by reflecting or refracting photons. Some objects may be in both
categories, and some objects may be in neither category.</p>
<p>Category 1 - Objects that show photon caustics</p>
<p>By default, all objects are in the first category. Whenever a photon hits
an object, the photon is stored and will later be used to render caustics on
that object. This means that, by default, caustics from photons can appear
on any surface. To speed up rendering, you can take objects out of this
category. You do this with the line: <code>photons{collect off}</code>. If you use
this syntax, caustics from photons will not appear on the object. This will
save both memory and computational time during rendering.</p>
<p>Category 2 - Objects that cause photon caustics</p>
<p>By default, there are no objects in the second category. If you want your
object to cause caustics, you need to do two things. First, make your object into
a "target." You do this with the <code>target</code> keyword. This enables light
sources to shoot photons at your object. Second, you need to specify if
your object reflects photons, refracts photons, or both. This is done with
the <code>reflection on</code> and <code>refraction on</code> keywords. To allow an object to
reflect and refract photons, you would use the following lines of code
inside the object:
</p>
<pre>
photons{
target
reflection on
refraction on
}
</pre>
<p>Generally speaking, you do not want an object to be in both categories. Most
objects that cause photon caustics do not themselves have much color or
brightness. Usually they simply refract or reflect their surroundings. For
this reason, it is usually a waste of time to display photon caustics on
such surfaces. Even if computed, the effects from the caustics would be so
dim that they would go unnoticed.</p>
<p>Sometimes, you may also wish to add <code>photons{collect off}</code> to other clear or
reflective objects, even if they are not photon targets. Again, this is
done to prevent unnecessary computation of caustic lighting.</p>
<p>Finally, you may wish to enable photon reflection and refraction for a
surface, even if it is not a target. This allows indirect photons (photons
that have already hit a target and been reflected or refracted) to continue
their journey after hitting this object.</p>
</div>
<a name="r3_4_4_4_3"></a>
<div class="content-level-h5" contains="Photon Global Settings" id="r3_4_4_4_3">
<h5>3.4.4.4.3 Photon Global Settings</h5>
<pre>
global_photon_block:
photons {
spacing <photon_spacing> | count <photons_to_shoot>
[gather <min_gather>, <max_gather>]
[media <max_steps> [,<factor>]]
[jitter <jitter_amount>]
[max_trace_level <photon_trace_level>]
[adc_bailout <photon_adc_bailout>]
[save_file "filename" | load_file "filename"]
[autostop <autostop_fraction>]
[expand_thresholds <percent_increase>, <expand_min>]
[radius <gather_radius>, <multiplier>, <gather_radius_media>,<multiplier>]
}
</pre>
<p>All photons default values:</p>
<pre>
Global :
expand_min : 40
gather : 20, 100
jitter : 0.4
media : 0
Object :
collect : on
refraction : off
reflection : off
split_union : on
target : 1.0
Light_source:
area_light : off
refraction : off
reflection : off
</pre>
<p>To specify photon gathering and storage options you need to add a photons
block to the <code>global_settings</code> section of your scene.</p>
<p>For example:</p>
<pre>
global_settings {
photons {
count 20000
autostop 0
jitter .4
}
}
</pre>
<p>The number of photons generated can be set using either the spacing or count
keywords: </p>
<ul>
<li>If spacing is used, it specifies approximately the average distance
between photons on surfaces. If you cut the spacing in half, you will get four
times as many surface photons, and eight times as many media photons.</li>
<li>If count is used, POV-Ray will shoot the approximately number of photons
specified. The actual number of photons that result from this will almost
always be at least slightly different from the number specified. Still, if you
double the photons_to_shoot value, then twice as many photons will be shot. If
you cut the value in half, then half the number of photons will be shot.
<ul>
<li>It may be less, because POV shoots photons at a target object's
bounding box, which means that some photons will miss the target object.</li>
<li>On the other hand, may be more, because each time one object hits an
object that has both reflection and refraction, two photons are created
(one for reflection and one for refraction).</li>
<li>POV will attempt to compensate for these two factors, but it can only
estimate how many photons will actually be generated. Sometimes this
estimation is rather poor, but the feature is still usable.</li>
</ul></li>
</ul>
<p>The keyword <code>gather</code> allows you to specify how many photons are
gathered at each point during the regular rendering step. The first number
(default 20) is the minimum number to gather, while the second number (default
100) is the maximum number to gather. These are good values and you should only
use different ones if you know what you are doing.</p>
<p>The keyword <code>media</code> turns on media photons. The parameter
<code>max_steps</code> specifies the maximum number of photons to deposit
over an interval. The optional parameter factor specifies the difference in
media spacing compared to surface spacing. You can increase factor and
decrease max_steps if too many photons are being deposited in media.</p>
<p>The keyword <code>jitter</code> specifies the amount of jitter used in the
sampling of light rays in the pre-processing step. The default value is good and
usually does not need to be changed.</p>
<p>The keywords <code>max_trace_level</code> and <code>adc_bailout</code> allow
you to specify these attributes for the photon-tracing step. If you do not
specify these, the values for the primary ray-tracing step will be used.</p>
<p>The keywords <code>save_file</code> and <code>load_file</code> allow you to
save and load photon maps. If you load a photon map, no photons will be shot.
The photon map file contains all surface (caustic) and media
photons.</p>
<p><code>radius</code> is used for gathering photons. The larger the radius, the longer it
takes to gather photons. But if you use too small of a radius, you might
not get enough photons to get a good estimate. Therefore, choosing a good
radius is important. Normally POV-Ray looks through the photon map and uses some ad-hoc statistical analysis to determine a reasonable radius. Sometimes it does a good job, sometimes it does not. The radius keyword lets you override or adjust POV-Ray's guess.
</p>
<p><code>radius</code> parameters (all are optional):</p>
<ol>
<li>Manually set the gather radius for surface photons. If this is either
zero or if you leave it out, POV-Ray will analyze and guess.</li>
<li>Adjust the radius for surface photons by setting a multiplier. If POV-Ray, for example, is picking a radius that you think is too big (render is too slow), you can use <code>radius ,0.5</code> to lower the radius (multiply by 0.5) and speed up the render at the cost of quality.</li>
<li>Manually set the gather radius for media photons.</li>
<li>Adjust the radius for media photons by setting a multiplier.
</ol>
<p>The keywords <code><a href="r3_4.html#r3_4_4_4_9_1">autostop</a></code>
and <code><a href="r3_4.html#r3_4_4_4_9_2">expand_thresholds</a></code> will be explained later.</p>
</div>
<a name="r3_4_4_4_4"></a>
<div class="content-level-h5" contains="Shooting Photons at an Object" id="r3_4_4_4_4">
<h5>3.4.4.4.4 Shooting Photons at an Object</h5>
<pre>
object_photon_block:
photons {
[target [Float]]
[refraction on|off]
[reflection on|off]
[collect on|off]
[pass_through]
}
</pre>
<p>To shoot photons at an object, you need to tell POV that the object receives
photons. To do this, create a <code>photons { }</code> block within the object. For example:</p>
<pre>
object {
MyObject
photons {
target
refraction on
reflection on
collect off
}
}
</pre>
<p>In this example, the object both reflects and refracts photons. Either of
these options could be turned off (by specifying reflection off, for example).
By using this, you can have an object with a reflective finish which does not
reflect photons for speed and memory reasons.</p>
<p>The keyword <code>target</code> makes this object a target.</p>
<p>The density of the photons can be adjusted by specifying a spacing multiplier in the form of an optional value after the <code>target</code> keyword. If, for example, you specify a spacing multiplier of 0.5, then the spacing for photons hitting this object will be 1/2 of the distance of the spacing for other objects.</p>
<p class="Note"><strong>Note:</strong> This means four times as many surface photons, and
eight times as many media photons.</p>
<p>The keyword <code>collect off</code> causes the object to ignore photons.
Photons are neither deposited nor gathered on that object.</p>
<p>The keyword <code>pass_through</code> causes photons to pass through the
object <strong>unaffected</strong> on their way to a target object. Once a
photon hits the target object, it will ignore the <code>pass_through</code>
flag. This is basically a photon version of the <code>no_shadow</code>
keyword, with the exception that media within the object will still be
affected by the photons (unless that media specifies collect off). If you
use the <code>no_shadow</code> keyword, the object will be tagged as
<code>pass_through</code> automatically. You can then turn off
<code>pass_through</code> if necessary by simply using <code>photons {
pass_through off }</code>.</p>
<p class="Note"><strong>Note:</strong> Photons will not be shot at an object unless you
specify the <code>target</code> keyword. Simply turning refraction on will not
suffice.</p>
<p>When shooting photons at a CSG-union, it may sometimes be of advantage to use
<code><a href="r3_4.html#r3_4_5_4_2_1">split_union off</a></code> inside the union.
POV-Ray will be forced to shoot at the whole object, instead of splitting it up
and shooting photons at its compound parts.</p>
</div>
<a name="r3_4_4_4_5"></a>
<div class="content-level-h5" contains="Photons and Light Sources" id="r3_4_4_4_5">
<h5>3.4.4.4.5 Photons and Light Sources</h5>
<pre>
light_photon_block:
photons {
[refraction on | off]
[reflection on | off]
[area_light]
}
</pre>
<p>Example:</p>
<pre>
light_source {
MyLight
photons {
refraction on
reflection on
}
}
</pre>
<p>Sometimes, you want photons to be shot from one light source and not another. In that case, you can turn photons on for an object, but specify <code>photons {reflection off refraction off }</code> in the light source's definition. You can also turn off only reflection or only refraction for any light source.</p>
<p class="Note"><strong>Note:</strong> The photon shooting <em>performance</em> has been improved with the addition of multiple-thread support. To take advantage of this at the moment, your scene will need multiple light sources. </p>
</div>
<a name="r3_4_4_4_6"></a>
<div class="content-level-h5" contains="Photons and Media" id="r3_4_4_4_6">
<h5>3.4.4.4.6 Photons and Media</h5>
<pre>
global_settings {
photons {
count 10000
media 100
}
}
</pre>
<p>Photons also interact fully with media. This means that volumetric photons
are stored in scattering media. This is enabled by using the keyword media
within the photons block.</p>
<p>To store photons in media, POV deposits photons as it steps through the media
during the photon-tracing phase of the render. It will deposit these photons as
it traces caustic photons, so the number of media photons is dependent on the
number of caustic photons. As a light ray passes through a section of media, the
photons are deposited, separated by approximately the same distance that
separates surface photons.</p>
<p>You can specify a factor as a second optional parameter to the media keyword.
If, for example, factor is set to 2.0, then photons will be spaced twice as far
apart as they would otherwise have been spaced.</p>
<p>Sometimes, however, if a section of media is very large, using these settings
could create a large number of photons very fast and overload memory. Therefore,
following the media keyword, you must specify the maximum number of photons that
are deposited for each ray that travels through each section of media. A setting
of 100 should probably work in most cases.</p>
<p>You can put <code>collect off</code> into media to make that media ignore
photons. Photons will neither be deposited nor gathered in a media that is
ignoring them. Photons will also not be gathered nor deposited in non-scattering
media. However, if multiple medias exist in the same space, and at least
one does not ignore photons and is scattering, then photons will be deposited in
that interval and will be gathered for use with all media in that interval.</p>
</div>
<a name="r3_4_4_4_7"></a>
<div class="content-level-h5" contains="Photons FAQ" id="r3_4_4_4_7">
<h5>3.4.4.4.7 Photons FAQ</h5>
<p><em>I made an object with IOR 1.0 and the shadows look weird.</em></p>
<p>If the borders of your shadows look odd when using photon mapping, do not be
alarmed. This is an unfortunate side-effect of the method. If you increase the
density of photons (by decreasing spacing and gather radius) you will notice the
problem diminish. We suggest not using photons if your object does not cause
much refraction (such as with a window pane or other flat piece of glass or any
objects with an IOR very close to 1.0).</p>
<p><em>My scene takes forever to render.</em></p>
<p>When POV-Ray builds the photon maps, it continually displays in the status
bar the number of photons that have been shot. Is POV-Ray stuck in this step and
does it keep shooting lots and lots of photons?</p>
<p><em>yes</em></p>
<p>If you are shooting photons at an infinite object (like a plane), then you
should expect this. Either be patient or do not shoot photons at infinite
objects.</p>
<p>Are you shooting photons at a CSG difference? Sometimes POV-Ray does a bad
job creating bounding boxes for these objects. And since photons are shot at the
bounding box, you could get bad results. Try manually bounding the object. You
can also try the autostop feature (try <code>autostop 0</code>). See the docs
for more info on autostop.</p>
<p><em>no</em></p>
<p>Does your scene have lots of glass (or other clear objects)? Glass is slow
and you need to be patient.</p>
<p><em>My scene has polka dots but renders really quickly. Why?</em></p>
<p>You should increase the number of photons (or decrease the spacing).</p>
<p><em>The photons in my scene show up only as small, bright dots. How can I fix
this?</em></p>
<p>The automatic calculation of the gather radius is probably not working
correctly, most likely because there are many photons not visible in your scene
which are affecting the statistical analysis.</p>
<p>You can fix this by either reducing the number of photons that are in your
scene but not visible to the camera (which confuse the auto-computation), or by
specifying the initial gather radius manually by using the keyword radius. If
you must manually specify a gather radius, it is usually best to also use
spacing instead of count, and then set radius and spacing to a 5:1
(radius:spacing) ratio.</p>
<p><em>Adding photons slowed down my scene a lot, and I see polka dots.</em></p>
<p>This is usually caused by having both high- and low-density photons in the
same scene. The low density ones cause polka dots, while the high density ones
slow down the scene. It is usually best if the all photons are on the same order
of magnitude for spacing and brightness. Be careful if you are shooting photons
objects close to and far from a light source. There is an optional parameter to
the target keyword which allows you to adjust the spacing of photons at the
target object. You may need to adjust this factor for objects very close to or
surrounding the light source.</p>
<p><em>I added photons, but I do not see any caustics.</em></p>
<p>When POV-Ray builds the photon maps, it continually displays in the status
bar the number of photons that have been shot. Did it show any photons being
shot?</p>
<p><em>no</em></p>
<p>Try avoiding <code>autostop</code>, or you might want to bound your object
manually.</p>
<p>Try increasing the number of photons (or decreasing the spacing).</p>
<p><em>yes</em></p>
<p><em>Were any photons stored (the number after <code>total</code> in the
rendering message as POV-Ray shoots photons)?</em></p>
<p><em>no</em></p>
<p>It is possible that the photons are not hitting the target object (because
another object is between the light source and the other object).</p>
<p><em>yes</em></p>
<p>The photons may be diverging more than you expect. They are probably there,
but you cannot see them since they are spread out too much</p>
<p><em>The base of my glass object is really bright.</em></p>
<p>Use <code>collect off</code> with that object.</p>
<p><em>Will area lights work with photon mapping?</em></p>
<p>Photons do work with area lights. However, normally photon mapping ignores
all area light options and treats all light sources as point lights. If you
would like photon mapping to use your area light options, you must specify the
"area_light" keyword <strong>within</strong> the <code>photons {
}</code> block in your light source's code. Doing this will not increase the
number of photons shot by the light source, but it might cause regular patterns
to show up in the rendered caustics (possibly splotchy).</p>
<p><em>What do the stats mean?</em></p>
<p>In the stats, <code>photons shot</code> means how many light rays were shot
from the light sources. <code>photons stored</code> means how many photons are
deposited on surfaces in the scene. If you turn on reflection and refraction,
you could get more photons stored than photons shot, since the each ray can get
split into two.</p>
</div>
<a name="r3_4_4_4_8"></a>
<div class="content-level-h5" contains="Photon Tips" id="r3_4_4_4_8">
<h5>3.4.4.4.8 Photon Tips</h5>
<ul>
<li>Use <code>collect off</code> in objects that photons do not hit. Just
put <code>photons { collect off }</code> in the object's definition.</li>
<li>Use <code>collect off</code> in glass objects.</li>
<li>Use <code>autostop</code> unless it causes problems.</li>
<li>A big tip is to make sure that all of the final densities of photons are
of the same general magnitude. You do not want spots with really high
density photons and another area with really low density photons. You will
always have some variation (which is a good thing), but having really big
differences in photon density is what causes some scenes to take many hours
to render.</li>
</ul>
</div>
<a name="r3_4_4_4_9"></a>
<div class="content-level-h5" contains="Advanced Techniques" id="r3_4_4_4_9">
<h5>3.4.4.4.9 Advanced Techniques</h5>
</div>
<a name="r3_4_4_4_9_1"></a>
<div class="content-level-h6" contains="Autostop" id="r3_4_4_4_9_1">
<h6>3.4.4.4.9.1 Autostop</h6>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<p>To understand the <code>autostop</code> option, you need to understand the way photons are shot from light sources. Photons are shot in a spiral pattern with uniform angular density. Imagine a sphere with a spiral starting at one of the poles and spiraling out in ever-increasing circles to the equator. Two angles are involved here. The first, phi, is the how far progress has been made in the current circle of the spiral. The second, theta, is how far we are from the pole to the equator. Now, imagine this sphere centered at the light source with the pole where the spiral starts pointed towards the center of the object receiving photons. Now, photons are shot out of the light in this spiral pattern.</p>
</td>
<td>
<img class="right" width="320px" src="images/2/28/RefImgShootph.png">
</td>
</tr>
<tr>
<td></td>
<td>
<p class="caption">Example of the photon autostop option</p>
</td>
</tr>
</table>
<p>Normally, POV does not stop shooting photons until the target object's
entire bounding box has been thoroughly covered. Sometimes, however, an object
is much smaller than its bounding box. At these times, we want to stop shooting
if we do a complete circle in the spiral without hitting the object.
Unfortunately, some objects (such as copper rings), have holes in the middle.
Since we start shooting at the middle of the object, the photons just go through
the hole in the middle, thus fooling the system into thinking that
it is done. To avoid this, the <code>autostop</code> keyword lets you specify
how far the system must go before this auto-stopping feature kicks in. The value
specified is a fraction of the object's bounding box. Valid values are 0.0
through 1.0 (0% through 100%). POV will continue to shoot photons until the
spiral has exceeded this value or the bounding box is completely covered. If a
complete circle of photons fails to hit the target object after the spiral has
passed the autostop threshold, POV will then stop shooting photons.</p>
<p>The <code>autostop</code> feature will also not kick in until at least one
photon has hit the object. This allows you to use <code>autostop 0</code> even
with objects that have holes in the middle.</p>
<p class="Note"><strong>Note:</strong> If the light source is within the object's
bounding box, the photons are shot in all directions from the light source.</p>
</div>
<a name="r3_4_4_4_9_2"></a>
<div class="content-level-h6" contains="Adaptive Search Radius" id="r3_4_4_4_9_2">
<h6>3.4.4.4.9.2 Adaptive Search Radius</h6>
<p>Unless photons are interacting with media, POV-Ray uses an adaptive search
radius while gathering photons. If the minimum number of photons is not found
in the original search radius, the radius is expanded and searched again. Using
this adaptive search radius can both decrease the amount of time it takes to
render the image, and sharpen the borders in the caustic patterns.</p>
<p>Sometimes this adaptive search technique can create unwanted artifacts at
borders. To remove these artifacts, a few thresholds are used, which can be
specified by <code>expand_thresholds</code>. For example, if expanding the
radius increases the estimated density of photons by too much (threshold is
percent_increase, default is 20%, or 0.2), the expanded search is discarded and
the old search is used instead. However, if too few photons are gathered in the
expanded search (<code>expand_min</code>, default is 40), the new search will be
used always, even if it means more than a 20% increase in photon density.</p>
</div>
<a name="r3_4_4_4_9_3"></a>
<div class="content-level-h6" contains="Photons and Dispersion" id="r3_4_4_4_9_3">
<h6>3.4.4.4.9.3 Photons and Dispersion</h6>
<p>When dispersion is specified for interior of a transparent object, photons
will make use of that and show "colored" caustics.</p>
</div>
<a name="r3_4_4_4_9_4"></a>
<div class="content-level-h6" contains="Saving and Loading Photon Maps" id="r3_4_4_4_9_4">
<h6>3.4.4.4.9.4 Saving and Loading Photon Maps</h6>
<p>It is possible to save and load photon maps to speed up rendering. The photon
map itself is view-independent, so if you want to animate a scene that contains
photons and you know the photon map will not change during the animation, you
can save it on the first frame and then load it for all subsequent frames.</p>
<p>To save the photon map, put the line</p>
<pre>
save_file "myfile.ph"
</pre>
<p>into the <code>photons { }</code> block inside the <code>global_settings</code> section.</p>
<p>Loading the photon map is the same, but with <code>load_file</code> instead
of <code>save_file</code>. You cannot both load and save a photon map in the POV
file. If you load the photon map, it will load all of the photons. No photons will be shot if the map is loaded
from a file. All other options (such as gather radius) must still be specified
in the POV scene file and are not loaded with the photon map.</p>
<p>When can you safely re-use a saved photon map?</p>
<ul>
<li>Moving the camera is <em>always</em> safe.</li>
<li>Moving lights that do not cast photons is <em>always</em> safe.</li>
<li>Moving objects that do not have photons shot at them, that do not receive photons, and would not receive photons in the new location is <em>always</em> safe.</li>
<li>Moving an object that receives photons to a new location where it does not receive photons is <em>sometimes</em> safe.</li>
<li>Moving an object to a location where it receives photons is <em>not</em> safe</li>
<li>Moving an object that has photons shot at it is <em>not</em> safe</li>
<li>Moving a light that casts photons is <em>not</em> safe.</li>
<li>Changing the texture of an object that receives photons is safe.</li>
<li>Changing the texture of an object that has photons shot at it produces
results that are not realistic, but can be useful sometimes.</li>
</ul>
<p>
In general, changes to the scene geometry require photons to be re-shot.
Changing the camera parameters or changing the image resolution does
not.</p></div>
<a name="r3_4_5"></a>
<div class="content-level-h3" contains="Object" id="r3_4_5">
<h3>3.4.5 Object</h3>
<p>Objects are the building blocks of your scene. There are a lot of different types of objects supported by POV-Ray. In the following sections, we describe <a href="r3_4.html#r3_4_5_1">Finite Solid Primitives</a>, <a href="r3_4.html#r3_4_5_2">Finite Patch Primitives</a> and <a href="r3_4.html#r3_4_5_3">Infinite Solid Primitives</a>. These primitive shapes may be combined into complex shapes using <a href="r3_4.html#r3_4_5_4">Constructive Solid Geometry</a> (also known as CSG).</p>
<p>
The basic syntax of an object is a keyword describing its type, some floats,
vectors or other parameters which further define its location and/or shape
and some optional object modifiers such as texture, interior_texture, pigment, normal, finish,
interior, bounding, clipping or transformations. Specifically the syntax
is:</p>
<pre>
OBJECT:
FINITE_SOLID_OBJECT | FINITE_PATCH_OBJECT |
INFINITE_SOLID_OBJECT | CSG_OBJECT | LIGHT_SOURCE |
object { OBJECT_IDENTIFIER [OBJECT_MODIFIERS...] }
FINITE_SOLID_OBJECT:
BLOB | BOX | CONE | CYLINDER | HEIGHT_FIELD | ISOSURFACE | JULIA_FRACTAL |
LATHE | OVUS | PARAMETRIC | PRISM | SPHERE | SPHERE_SWEEP | SUPERELLIPSOID |
SOR | TEXT | TORUS
FINITE_PATCH_OBJECT:
BICUBIC_PATCH | DISC | MESH | MESH2 | POLYGON | TRIANGLE |
SMOOTH_TRIANGLE
INFINITE_SOLID_OBJECT:
PLANE | POLY | CUBIC | QUARTIC | QUADRIC
CSG_OBJECT:
UNION | INTERSECTION | DIFFERENCE | MERGE
</pre>
<p>Object identifiers may be declared to make scene files more readable and
to parameterize scenes so that changing a single declaration changes many
values. An identifier is declared as follows.</p>
<pre>
OBJECT_DECLARATION:
#declare IDENTIFIER = OBJECT |
#local IDENTIFIER = OBJECT
</pre>
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40
characters long and <em>OBJECT</em> is any valid object. To invoke
an object identifier, you wrap it in an <code>object{...}</code> statement.
You use the <code>object</code> statement regardless of what type of object
it originally was. Although early versions of POV-Ray required this <code>
object</code> wrapper all of the time, now it is only used with <em>
OBJECT_IDENTIFIERS</em>.</p>
<p>
Object modifiers are covered in detail later. However here is a brief
overview.</p>
<p>
The texture describes the surface properties of the object. Complete details
are in <a href="r3_4.html#r3_4_6">textures</a>. Textures are combinations of pigments, normals,
and finishes. In the section <a href="r3_4.html#r3_4_6_1">pigment</a> you will learn how to
specify the color or pattern of colors inherent in the material. In <a href="r3_4.html#r3_4_6_2">normal</a>, we describe a method of simulating various patterns of bumps, dents, ripples
or waves by modifying the surface normal vector. The section on <a href="r3_4.html#r3_4_6_3">finish</a> describes the reflective properties of the surface. The <a href="r3_4.html#r3_4_8_1">Interior</a> is a feature introduced in POV-Ray 3.1. It contains information
about the interior of the object which was formerly contained in the finish
and halo parts of a texture. Interior items are no longer part of the
texture. Instead, they attach directly to the objects. The halo feature has
been discontinued and replaced with a new feature called <a href="r3_4.html#r3_4_8">Media</a> which replaces both halo and atmosphere.</p>
<p>
Bounding shapes are finite, invisible shapes which wrap around complex, slow
rendering shapes in order to speed up rendering time. Clipping shapes are
used to cut away parts of shapes to expose a hollow interior. Transformations
tell the ray-tracer how to move, size or rotate the shape and/or the texture
in the scene.</p></div>
<a name="r3_4_5_1"></a>
<div class="content-level-h4" contains="Finite Solid Primitives" id="r3_4_5_1">
<h4>3.4.5.1 Finite Solid Primitives</h4>
<p>There are seventeen different solid finite primitive shapes: <a href="r3_4.html#r3_4_5_1_1">blob</a>, <a href="r3_4.html#r3_4_5_1_2">box</a>,
<a href="r3_4.html#r3_4_5_1_3">cone</a>, <a href="r3_4.html#r3_4_5_1_4">cylinder</a>, <a href="r3_4.html#r3_4_5_1_5">height field</a>, <a href="r3_4.html#r3_4_5_1_6">isosurface</a>, <a href="r3_4.html#r3_4_5_1_7">Julia fractal</a>, <a href="r3_4.html#r3_4_5_1_8">lathe</a>, <a href="r3_4.html#r3_4_5_1_9">ovus</a>, <a href="r3_4.html#r3_4_5_1_10">parametric</a>, <a href="r3_4.html#r3_4_5_1_11">prism</a>, <a href="r3_4.html#r3_4_5_1_12">sphere</a>, <a href="r3_4.html#r3_4_5_1_13">sphere_sweep</a>, <a href="r3_4.html#r3_4_5_1_14">superellipsoid</a>, <a href="r3_4.html#r3_4_5_1_15">surface of revolution</a>, <a href="r3_4.html#r3_4_5_1_16">text</a> and <a href="r3_4.html#r3_4_5_1_17">torus</a>. These have a
well-defined <em>inside</em> and can be used in CSG: see <a href="r3_4.html#r3_4_5_4">Constructive Solid Geometry</a>. They are finite and respond to automatic bounding. You may specify an interior for these objects.</p></div>
<a name="r3_4_5_1_1"></a>
<div class="content-level-h5" contains="Blob" id="r3_4_5_1_1">
<h5>3.4.5.1.1 Blob</h5>
<p>Blobs are an interesting and flexible object type. Mathematically they are
iso-surfaces of scalar fields, i.e. their surface is defined by the strength
of the field in each point. If this strength is equal to a threshold value
you are on the surface otherwise you are not.</p>
<p>
Picture each blob component as an object floating in space. This object is
<em> filled</em> with a field that has its maximum at the center of the
object and drops off to zero at the object's surface. The field strength
of all those components are added together to form the field of the blob. Now
POV-Ray looks for points where this field has a given value, the threshold
value. All these points form the surface of the blob object. Points with a
greater field value than the threshold value are considered to be inside
while points with a smaller field value are outside.</p>
<p>
There's another, simpler way of looking at blobs. They can be seen as a
union of flexible components that attract or repel each other to form a
blobby organic looking shape. The components' surfaces actually stretch
out smoothly and connect as if they were made of honey or something similar.
</p>
<p>
The syntax for <code>blob</code> is defined as follows:</p>
<pre>
BLOB:
blob { BLOB_ITEM... [BLOB_MODIFIERS...]}
BLOB_ITEM:
sphere{<Center>, Radius,
[ strength ] Strength[COMPONENT_MODIFIER...] } |
cylinder{<End1>, <End2>, Radius,
[ strength ] Strength [COMPONENT_MODIFIER...] } |
component Strength, Radius, <Center> |
threshold Amount
COMPONENT_MODIFIER:
TEXTURE | PIGMENT | NORMAL | FINISH | TRANSFORMATION
BLOB_MODIFIER:
hierarchy [Boolean] | sturm [Boolean] | OBJECT_MODIFIER
</pre>
<p>Blob default values:</p>
<pre>
hierarchy : on
sturm : off
threshold : 1.0
</pre>
<p>The <code>threshold</code> keyword is followed by a float value which
determines the total field strength value that POV-Ray is looking for. The
default value if none is specified is <code>threshold 1.0</code>. By
following the ray out into space and looking at how each blob component
affects the ray, POV-Ray will find the points in space where the field
strength is equal to the threshold value. The following list shows some
things you should know about the threshold value.</p>
<ol>
<li>The threshold value must be positive.</li>
<li>A component disappears if the threshold value is greater than its strength.</li>
<li>As the threshold value gets larger, the surface you see gets closer to the centers of the components.</li>
<li>As the threshold value gets smaller, the surface you see gets closer to the surface of the components.</li>
</ol>
<p>Cylindrical components are specified by a <code>cylinder</code> statement.
The center of the end-caps of the cylinder is defined by the vectors <em>
<code><End1></code></em> and <em><code> <End2></code></em>. Next
is the float value of the <em>Radius</em> followed by the float <em>
Strength</em>. These vectors and floats are required and should be separated
by commas. The keyword <code> strength</code> may optionally precede the
strength value. The cylinder has hemispherical caps at each end.</p>
<p>Spherical components are specified by a <code>sphere</code> statement. The
location is defined by the vector <em> <code><Center></code></em>. Next
is the float value of the <em> Radius</em> followed by the float <em>
Strength</em>. These vector and float values are required and should be
separated by commas. The keyword <code> strength</code> may optionally
precede the strength value.</p>
<p>
You usually will apply a single texture to the entire blob object, and you
typically use transformations to change its size, location, and orientation.
However both the <code>cylinder</code> and <code>sphere</code> statements may
have individual texture, pigment, normal, finish, and transformations applied
to them. You may not apply separate <code>interior</code> statements to the
components but you may specify one for the entire blob. </p>
<p class="Note"><strong>Note:</strong> By unevenly scaling a spherical component you can create ellipsoidal components. The
tutorial section on <a href="t2_3.html#t2_3_3_1">Blob Object</a> illustrates individually textured blob components and many other blob examples.</p>
<p>The <code>component</code> keyword is an obsolete method for specifying a
spherical component and is only used for compatibility with earlier POV-Ray
versions. It may not have textures or transformations individually applied to
it.</p>
<p>The <code>strength</code> parameter of either type of blob component is a
float value specifying the field strength at the center of the object. The
strength may be positive or negative. A positive value will make that
component attract other components while a negative value will make it repel
other components. Components in different, separate blob shapes do not affect
each other.</p>
<p>You should keep the following things in mind.</p>
<ol>
<li>The strength value may be positive or negative. Zero is a bad value,
as the net result is that no field was added -- you might just as well have
not used this component.</li>
<li>If strength is positive, then POV-Ray will add the component's field
to the space around the center of the component. If this adds enough field
strength to be greater than the threshold value you will see a surface.</li>
<li>If the strength value is negative, then POV-Ray will subtract the component's
field from the space around the center of the component. This will only
do something if there happen to be positive components nearby. The surface
around any nearby positive components will be dented
away from the center of the negative component.</li>
</ol>
<p>After all components and the optional <code>threshold</code> value have
been specified you may specify zero or more blob modifiers. A blob modifier
is any regular object modifier or the <code>hierarchy</code> or <code>
sturm</code> keywords.</p>
<p>The components of each blob object are internally bounded by a spherical
bounding hierarchy to speed up blob intersection tests and other operations.
Using the optional keyword <code>hierarchy</code> followed by an optional
boolean float value will turn it off or on. By default it is on.</p>
<p>The calculations for blobs must be very accurate. If this shape renders
improperly you may add the keyword <code>sturm</code> followed by an
optional boolean float value to turn off or on POV-Ray's
slower-yet-more-accurate Sturmian root solver. By default it is off.</p>
<p>An example of a three component blob is:</p>
<pre>
BLOB:
blob {
threshold 0.6
sphere { <.75, 0, 0>, 1, 1 }
sphere { <-.375, .64952, 0>, 1, 1 }
sphere { <-.375, -.64952, 0>, 1, 1 }
scale 2
}
</pre>
<p>If you have a single blob component then the surface you see will just
look like the object used, i.e. a sphere or a cylinder, with the surface
being somewhere inside the surface specified for the component. The exact
surface location can be determined from the blob equation listed below (you
will probably never need to know this, blobs are more for visual appeal than
for exact modeling).</p>
<p>For the more mathematically minded, here's the formula used internally
by POV-Ray to create blobs. You do not need to understand this to use
blobs. The density of the blob field of a single component is:</p>
<table class="centered" width="405x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="385px" src="images/6/69/RefImgBlobdens.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Blob Density</p>
</td>
</tr>
</table>
<p>where <em>distance</em> is the distance of a given point from the
spherical blob's center or cylinder blob's axis. This formula has the
nice property that it is exactly equal to the strength parameter at the
center of the component and drops off to exactly 0 at a distance from the
center of the component that is equal to the radius value. The density
formula for more than one blob component is just the sum of the individual
component densities.</p></div>
<a name="r3_4_5_1_2"></a>
<div class="content-level-h5" contains="Box" id="r3_4_5_1_2">
<h5>3.4.5.1.2 Box</h5>
<p>A simple box can be defined by listing two corners of the box using the
following syntax for a <code>box</code> statement:</p>
<pre>
BOX:
box {
<Corner_1>, <Corner_2>
[OBJECT_MODIFIERS...]
}
</pre>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/9/98/RefImgBoxgeom.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The geometry of a box.</p>
</td>
</tr>
</table>
<p>Where <em><code><Corner_1></code></em> and <em><code>
<Corner_2></code></em> are vectors defining the x, y, z coordinates of
the opposite corners of the box.</p>
<p class="Note"><strong>Note:</strong> All boxes are defined with their faces parallel to the coordinate axes. They may later be rotated to any orientation using the <code>rotate</code> keyword.</p>
<p>
Boxes are calculated efficiently and make good bounding shapes (if manually
bounding seems to be necessary).</p></div>
<a name="r3_4_5_1_3"></a>
<div class="content-level-h5" contains="Cone" id="r3_4_5_1_3">
<h5>3.4.5.1.3 Cone</h5>
<p>The <code>cone</code> statement creates a finite length cone or a <em>
frustum</em> (a cone with the point cut off). The syntax is:</p>
<pre>
CONE:
cone {
<Base_Point>, Base_Radius, <Cap_Point>, Cap_Radius
[ open ][OBJECT_MODIFIERS...]
}
</pre>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/9/93/RefImgConegeom.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The geometry of a cone.</p>
</td>
</tr>
</table>
<p>Where <em><code><Base_Point></code></em> and <em><code><
Cap_Point></code></em> are vectors defining the x, y, z coordinates of the
center of the cone's base and cap and <em><code> Base_Radius</code></em>
and <em><code>Cap_Radius</code></em> are float values for the corresponding
radii.</p>
<p>Normally the ends of a cone are closed by flat discs that are parallel to
each other and perpendicular to the length of the cone. Adding the optional
keyword <code>open</code> after <em><code>Cap_Radius</code></em> will remove
the end caps and results in a tapered hollow tube like a megaphone or
funnel.</p></div>
<a name="r3_4_5_1_4"></a>
<div class="content-level-h5" contains="Cylinder" id="r3_4_5_1_4">
<h5>3.4.5.1.4 Cylinder</h5>
<p>The <code>cylinder</code> statement creates a finite length cylinder with
parallel end caps The syntax is:</p>
<pre>
CYLINDER:
cylinder {
<Base_Point>, <Cap_Point>, Radius
[ open ][OBJECT_MODIFIERS...]
}
</pre>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/1/18/RefImgCylgeom.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The geometry of a cylinder.</p>
</td>
</tr>
</table>
<p>Where <em><code><Base_Point></code></em> and <em><code>
<Cap_Point></code></em> are vectors defining the x, y, z coordinates of
the cylinder's base and cap and <em><code>Radius</code></em> is a float
value for the radius.</p>
<p>
Normally the ends of a cylinder are closed by flat discs that are parallel
to each other and perpendicular to the length of the cylinder. Adding the
optional keyword <code>open</code> after the radius will remove the end caps
and results in a hollow tube.</p></div>
<a name="r3_4_5_1_5"></a>
<div class="content-level-h5" contains="Height Field" id="r3_4_5_1_5">
<h5>3.4.5.1.5 Height Field</h5>
<p>Height fields are fast, efficient objects that are generally used to
create mountains or other raised surfaces out of hundreds of triangles in a
mesh. The <code>height_field</code> statement syntax is:</p>
<pre>
HEIGHT_FIELD:
height_field {
[HF_TYPE] "filename" [gamma GAMMA] [premultiplied BOOL] | [HF_FUNCTION]
[HF_MODIFIER...]
[OBJECT_MODIFIER...]
}
HF_TYPE:
exr | gif | hdr | iff | jpeg | pgm | png | pot | ppm | sys | tga | tiff
HF_FUNCTION:
function FieldResolution_X, FieldResolution_Y { UserDefined_Function }
HF_MODIFIER:
smooth & water_level Level
OBJECT_MODIFIER:
hierarchy [Boolean]
</pre>
<p>Height_field default values:</p>
<pre>
hierarchy : on
smooth : off
water_level : 0.0
</pre>
<p>A height field is essentially a one unit wide by one unit long square with
a mountainous surface on top. The height of the mountain at each point is
taken from the color number or palette index of the pixels in a graphic image
file. The maximum height is one, which corresponds to the maximum possible
color or palette index value in the image file.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/0/0c/RefImgUnhfield.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The size and orientation of an unscaled height field.</p>
</td>
</tr>
</table>
<p>The mesh of triangles corresponds directly to the pixels in the image
file. Each square formed by four neighboring pixels is divided into two
triangles. An image with a resolution of <em><code>N*M</code></em> pixels has
<em><code>(N-1)*(M-1)</code></em> squares that are divided into <em> <code>
2*(N-1)*(M-1)</code></em> triangles.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/3/3c/RefImgPixhfld.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Relationship of pixels and triangles in a height field.</p>
</td>
</tr>
</table>
<p>The resolution of the height field is influenced by two factors: the
resolution of the image and the resolution of the color/index values. The
size of the image determines the resolution in the x- and z-direction. A
larger image uses more triangles and looks smoother. The resolution of the
color/index value determines the resolution along the y-axis. A height field
made from an 8-bit image can have 256 different height levels while one made
from a 16-bit image can have up to 65536 different height levels. Thus the
second height field will look much smoother in the y-direction if the height
field is created appropriately.</p>
<p>
The size/resolution of the image does not affect the size of the height
field. The unscaled height field size will always be 1 by 1 by 1. Higher
resolution image files will create smaller triangles, not larger height
fields.</p>
<p>The image file type used to create a height field is specified by one of the keywords <a href="r3_4.html#r3_4_5_1_5">listed</a> above. Specifying the file type is optional. If it is not defined the same file type will be assumed as the one that is set as the output file type. This is useful when the source for the <code>height_field</code> is also generated with POV-Ray.</p>
<p>The GIF, PNG, PGM, TIFF and possibly SYS format files are the only
ones that can be created using a standard paint program. Though there are
paint programs for creating TGA image files they will not be of much use for
creating the special 16 bit TGA files used by POV-Ray (see below and
<a href="r3_4.html#r3_4_1_4">HF_Gray_16</a> for more details).</p>
<p>
In an image file that uses a color palette, like GIF, the color number is the
palette index at a given pixel. Use a paint program to look at the palette of
a GIF image. The first color is palette index zero, the second is index one,
the third is index two and so on. The last palette entry is index 255.
Portions of the image that use low palette entries will result in lower parts
of the height field. Portions of the image that use higher palette entries
will result in higher parts of the height field.</p>
<p>
Height fields created from GIF files can only have 256 different height
levels because the maximum number of colors in a GIF file is 256.</p>
<p>
The color of the palette entry does not affect the height of the pixel.
Color entry 0 could be red, blue, black or orange but the height of any pixel
that uses color entry 0 will always be 0. Color entry 255 could be indigo,
hot pink, white or sky blue but the height of any pixel that uses color entry
255 will always be 1.</p>
<p>
You can create height field GIF images with a paint program or a fractal program like <em>Fractint</em>.</p>
<p>
A POT file is essentially a GIF file with a 16 bit palette. The maximum
number of colors in a POT file is 65536. This means a POT height field can
have up to 65536 possible height values. This makes it possible to have much
smoother height fields.</p>
<p class="Note"><strong>Note:</strong> The maximum height of the field is still 1
even though more intermediate values are possible.</p>
<p> At the time of this writing the only program that created POT files was a freeware MS-Dos/Windows program called <em>Fractint</em>. POT files generated with this fractal program create fantastic landscapes.</p>
<p>
The TGA and PPM file formats may be used as a storage device for 16 bit
numbers rather than an image file. These formats use the red and green bytes
of each pixel to store the high and low bytes of a height value. These files
are as smooth as POT files but they must be generated with special
custom-made programs. Several programs can create TGA heightfields in the
format POV uses, such as <em>Gforge</em> and <em>Terrain Maker</em>.</p>
<p>
PNG format heightfields are usually stored in the form of a grayscale image
with black corresponding to lower and white to higher parts of the height
field. Because PNG files can store up to 16 bits in grayscale images they
will be as smooth as TGA and PPM images. Since they are grayscale images you
will be able to view them with a regular image viewer. <em>Gforge</em>
can create 16-bit heightfields in PNG format. Color PNG images will be used
in the same way as TGA and PPM images.</p>
<p>
SYS format is a platform specific file format. See your platform specific
documentation for details.</p>
<p>
In addition to all the usual object modifiers, there are three additional
height field modifiers available.</p>
<p>The optional <code>water_level</code> parameter may be added after the file
name. It consists of the keyword <code>water_level</code> followed by a
float value telling the program to ignore parts of the height field below
that value. The default value is zero and legal values are between zero and
one. For example <code>water_level 0.5</code> tells POV-Ray to only render
the top half of the height field. The other half is <em>below the water</em>
and could not be seen anyway. Using <code>water_level</code> renders
faster than cutting off the lower part using CSG or clipping. This term comes
from the popular use of height fields to render landscapes. A height field
would be used to create islands and another shape would be used to simulate
water around the islands. A large portion of the height field would be
obscured by the water so the <code>water_level</code> parameter was
introduced to allow the ray-tracer to ignore the unseen parts of the height
field. <code>water_level</code> is also used to cut away unwanted lower
values in a height field. For example if you have an image of a fractal on a
solid colored background, where the background color is palette entry 0, you
can remove the background in the height field by specifying, <code>
water_level 0.001</code>.</p>
<p>Normally height fields have a rough, jagged look because they are made of
lots of flat triangles. Adding the keyword <code>smooth</code> causes
POV-Ray to modify the surface normal vectors of the triangles in such a way
that the lighting and shading of the triangles will give a smooth look. This
may allow you to use a lower resolution file for your height field than would
otherwise be needed. However, smooth triangles will take longer to render.
The default value is off.</p>
<p>In order to speed up the intersection tests a one-level bounding hierarchy
is available. By default it is always used but it can be switched off using
<code>hierarchy off</code> to improve the rendering speed for small height
fields (i.e. low resolution images). You may optionally use a boolean value
such as <code>hierarchy on</code> or <code>hierarchy off</code>.</p>
<p>While POV-Ray will normally interpret the height field input file as a container of linear data irregardless of file type, this can be overridden for any individual height field input file by specifying <code>gamma</code> GAMMA immediately after the file name. For example:</p>
<pre>
height field {
jpeg "foobar.jpg" gamma 1.8
}
</pre>
<p>This will cause POV-Ray to perform gamma adjustment or -decoding on the input file data before building the height field. Alternatively to a numerical value, <code>srgb</code> may be specified to denote that the file format is pre-corrected or encoded using the ''sRGB transfer function'' instead of a power-law gamma function. See the section <a href="t2_3.html#t2_3_4">Gamma Handling</a> for more information.</p>
<p>The height field object also allows for substituting a <a href="r3_4.html#r3_4_7_1_12">user defined function</a> instead of specifying an image. That function can either be in it's literal form, or it can be a call to a function that you have predeclared. The user supplied parameters <code>FieldResolution_X</code> and <code>FieldResolution_Y</code> are integer values that affect the resolution of the color/index values, <em>not</em> size of the unscaled height field.</p></div>
<a name="r3_4_5_1_6"></a>
<div class="content-level-h5" contains="Isosurface" id="r3_4_5_1_6">
<h5>3.4.5.1.6 Isosurface</h5>
<p>Details about many of the things that can be done with the isosurface object are
discussed in the isosurface tutorial section. Below you will only find the syntax basics:</p>
<pre>
isosurface {
function { FUNCTION_ITEMS }
[contained_by { SPHERE | BOX }]
[threshold FLOAT_VALUE]
[accuracy FLOAT_VALUE]
[max_gradient FLOAT_VALUE]
[evaluate P0, P1, P2]
[open]
[max_trace INTEGER] | [all_intersections]
[OBJECT_MODIFIERS...]
}
</pre>
<p>Isosurface default values:</p>
<pre>
contained_by : box{-1,1}
threshold : 0.0
accuracy : 0.001
max_gradient : 1.1
</pre>
<p><code>function { ... }</code> This must be specified and be the first item of the
<code>isosurface</code> statement. Here you place all the mathematical functions that
will describe the surface.</p>
<p><code>contained_by { ... }</code> The <code>contained_by</code> <em>object</em> limits the
area where POV-Ray samples for the surface of the function. This container can either be a
sphere or a box, both of which use the standard POV-Ray syntax. If not specified a
<code>box {<-1,-1,-1>, <1,1,1>}</code> will be used as default.</p>
<pre>
contained_by { sphere { CENTER, RADIUS } }
contained_by { box { CORNER1, CORNER2 } }
</pre>
<p><code>threshold</code> This specifies how much strength, or substance to give the
<code>isosurface</code>. The surface appears where the <code>function</code> value
equals the <code>threshold</code> value. The default threshold is 0.</p>
<pre>function = threshold</pre>
<p><code>accuracy</code> The isosurface finding method is a recursive subdivision method.
This subdivision goes on until the length of the interval where POV-Ray finds a surface
point is less than the specified <code>accuracy</code>. The default value is 0.001.
<br>Smaller values produces more accurate surfaces, but it takes longer to render.</p>
<p><code>max_gradient</code> POV-Ray can find the first intersecting point between a ray and
the <code>isosurface</code> of any continuous function if the maximum gradient of the function
is known. Therefore you can specify a <code>max_gradient</code> for the function.
The default value is 1.1. When the <code>max_gradient</code> used to find the
intersecting point is too high, the render slows down considerably. When it is too
low, artifacts or holes may appear on the isosurface. When it is way too low, the surface
does not show at all. While rendering the isosurface POV-Ray records the found gradient values
and prints a warning if these values are higher or much lower than the specified
<code>max_gradient</code>:</p>
<pre>
Warning: The maximum gradient found was 5.257, but max_gradient of
the isosurface was set to 5.000. The isosurface may contain holes!
Adjust max_gradient to get a proper rendering of the isosurface.
</pre>
<pre>
Warning: The maximum gradient found was 5.257, but max_gradient of
the isosurface was set to 7.000. Adjust max_gradient to
get a faster rendering of the isosurface.
</pre>
<p>For best performance you should specify a value close to the real maximum gradient.</p>
<p><code>evaluate</code> POV-Ray can also dynamically adapt the used max_gradient.
To activate this technique you have to specify the <code>evaluate</code> keyword
followed by three parameters:</p>
<ul>
<li> P0: the minimum max_gradient in the estimation process,</li>
<li> P1: an over-estimating factor. This means that the max_gradient is
multiplied by the P1 parameter.</li>
<li> P2: an attenuation parameter (1 or less)</li>
</ul>
<p>In this case POV-Ray starts with the <code>max_gradient</code> value <code>P0</code>
and dynamically changes it during the render using <code>P1</code> and <code>P2</code>.
In the evaluation process, the P1 and P2 parameters are used in
quadratic functions. This means that over-estimation increases more
rapidly with higher values and attenuation more rapidly with lower
values. Also with dynamic <code>max_gradient</code>, there can be artifacts and holes.</p>
<p>If you are unsure what values to use, start a render without <code>evaluate</code> to get
a value for <code>max_gradient</code>. Now you can use it with <code>evaluate</code> like this:</p>
<ul>
<li>P0 : found max_gradient * min_factor<br>
<em>min_factor</em> being a float between 0 and 1 to reduce the
<code>max_gradient</code> to a <em>minimum max_gradient</em>. The ideal value for P0
would be the average of the found max_gradients, but we do not
have access to that information.<br>
A good starting point is 0.6 for the min_factor</li>
<li>P1 : sqrt(found max_gradient/(found max_gradient * min_factor))<br>
<em>min_factor</em> being the same as used in P0
this will give an over-estimation factor of more than 1, based
on your minimum max_gradient and the found max_gradient.</li>
<li>P2 : 1 or less<br>
0.7 is a good starting point.</li>
</ul>
<p>
When there are artifacts / holes in the isosurface, increase the min_factor and / or P2 a bit.
Example: when the first run gives a found max_gradient of 356, start with</p>
<pre>
#declare Min_factor= 0.6;
isosurface {
...
evaluate 356*Min_factor, sqrt(356/(356*Min_factor)), 0.7
//evaluate 213.6, 1.29, 0.7
...
}
</pre>
<p>
This method is only an approximation of what happens internally, but it
gives faster rendering speeds with the majority of isosurfaces.</p>
<p><code>open</code> When the isosurface is not fully contained within the contained_by object,
there will be a cross section. Where this happens, you will see the surface of the container.
With the <code>open</code> keyword, these cross section surfaces are removed. The inside of the isosurface
becomes visible.</p>
<p class="Note"><strong>Note:</strong> Using <code>open</code> slows down the render speed, and it is not recommended to use it with CSG operations.</p>
<p><code>max_trace</code> Isosurfaces can be used in CSG shapes since they are solid finite objects
- if not finite by themselves, they are through the cross section with the container.
<br>By default POV-Ray searches only for the first surface which the ray intersects. But when using an
<code>isosurface</code> in CSG operations, the other surfaces must also be found. Therefore,
the keyword <code>max_trace</code> must be added to the <code>isosurface</code> statement.
It must be followed by an integer value. To check for all surfaces, use the keyword <code>all_intersections</code> instead.
<br>With <code>all_intersections</code> POV-Ray keeps looking until all surfaces are found.
With a <code>max_trace</code> it only checks until that number is reached.</p></div>
<a name="r3_4_5_1_7"></a>
<div class="content-level-h5" contains="Julia Fractal" id="r3_4_5_1_7">
<h5>3.4.5.1.7 Julia Fractal</h5>
<p>A <em>julia fractal</em> object is a 3-D <em>slice</em> of a 4-D object
created by generalizing the process used to create the classic Julia sets.
You can make a wide variety of strange objects using the <code>
julia_fractal</code> statement including some that look like bizarre blobs of
twisted taffy. The <code>julia_fractal</code> syntax is:</p>
<pre>
JULIA_FRACTAL:
julia_fractal {
<4D_Julia_Parameter>
[JF_ITEM...] [OBJECT_MODIFIER...]
}
JF_ITEM:
ALGEBRA_TYPE | FUNCTION_TYPE | max_iteration Count |
precision Amt | slice <4D_Normal>, Distance
ALGEBRA_TYPE:
quaternion | hypercomplex
FUNCTION_TYPE:
QUATERNATION:
sqr | cube
HYPERCOMPLEX:
sqr | cube | exp | reciprocal | sin | asin | sinh |
asinh | cos | acos | cosh | acosh | tan | atan |tanh |
atanh | ln | pwr( X_Val, Y_Val )
</pre>
<p>Julia Fractal default values:</p>
<pre>
ALGEBRA_TYPE : quaternion
FUNCTION_TYPE : sqr
max_iteration : 20
precision : 20
slice, DISTANCE : <0,0,0,1>, 0.0
</pre>
<p>The required 4-D vector <em><code><4D_Julia_Parameter></code></em>
is the classic Julia parameter <em><code>p</code></em> in the iterated
formula <em><code>f(h) + p</code></em>. The julia fractal object is
calculated by using an algorithm that determines whether an arbitrary point
<em><code>h(0)</code></em> in 4-D space is inside or outside the object. The
algorithm requires generating the sequence of vectors <em><code>h(0), h(1),
...</code></em> by iterating the formula <em><code>h(n+1) = f(h(n)) + p (n =
0, 1, ..., max_iteration-1)</code></em> where <em><code> p</code></em> is the
fixed 4-D vector parameter of the julia fractal and <em><code>f()</code></em>
is one of the functions <code>sqr</code>, <code> cube</code>, ... specified
by the presence of the corresponding keyword. The point <em><code>
h(0)</code></em> that begins the sequence is considered inside the julia
fractal object if none of the vectors in the sequence escapes a hypersphere
of radius 4 about the origin before the iteration number reaches the integer
<code>max_iteration</code> value. As you increase <code>max_iteration</code>,
some points escape that did not previously escape, forming the julia fractal.
Depending on the <em><code> <4D_Julia_Parameter></code></em>, the julia
fractal object is not necessarily connected; it may be scattered fractal
dust. Using a low <code> max_iteration</code> can fuse together the dust to
make a solid object. A high <code>max_iteration</code> is more accurate but
slows rendering. Even though it is not accurate, the solid shapes you get
with a low <code>max_iteration</code> value can be quite interesting. If
none is specified, the default is <code>max_iteration 20</code>.</p>
<p>Since the mathematical object described by this algorithm is four-dimensional
and POV-Ray renders three dimensional objects, there must be a way to reduce
the number of dimensions of the object from four dimensions to three. This is
accomplished by intersecting the 4-D fractal with a 3-D plane defined by the <code>slice</code> modifier and then projecting the
intersection to 3-D space. The keyword is followed by 4-D vector and a float
separated by a comma. The slice plane is the 3-D space that is perpendicular
to <em><code> <4D_Normal></code></em> and is <em><code>
Distance</code></em> units from the origin. Zero length <em><code>
<4D_Normal></code></em> vectors or a <em><code>
<4D_Normal></code></em> vector with a zero fourth component are
illegal. If none is specified, the default is <code> slice
<0,0,0,1>,0</code>.</p>
<p>
You can get a good feel for the four dimensional nature of a julia fractal by
using POV-Ray's animation feature to vary a slice's <em><code>
Distance</code></em> parameter. You can make the julia fractal appear from
nothing, grow, then shrink to nothing as <em><code>
Distance</code></em> changes, much as the cross section of a 3-D object
changes as it passes through a plane.</p>
<p>The <code> precision</code> parameter is a tolerance used in the
determination of whether points are inside or outside the fractal object.
Larger values give more accurate results but slower rendering. Use as low a
value as you can without visibly degrading the fractal object's
appearance but note values less than 1.0 are clipped at 1.0. The default if
none is specified is <code>precision 20</code>.</p>
<p>The presence of the keywords <code> quaternion</code> or <code>
hypercomplex</code> determine which 4-D algebra is used to calculate the
fractal. The default is <code>quaternion</code>. Both are 4-D generalizations
of the complex numbers but neither satisfies all the field properties (all
the properties of real and complex numbers that many of us slept through in
high school). Quaternions have non-commutative multiplication and
hypercomplex numbers can fail to have a multiplicative inverse for some
non-zero elements (it has been proved that you cannot successfully generalize
complex numbers to four dimensions with all the field properties intact, so
something has to break). Both of these algebras were discovered in the 19th
century. Of the two, the quaternions are much better known, but one can argue
that hypercomplex numbers are more useful for our purposes, since complex
valued functions such as sin, cos, etc. can be generalized to work for
hypercomplex numbers in a uniform way.</p>
<p>
For the mathematically curious, the algebraic properties of these two
algebras can be derived from the multiplication properties of the unit basis
vectors 1 = <1,0,0,0>, i=< 0,1,0,0>, j=<0,0,1,0> and k=<
0,0,0,1>. In both algebras 1 x = x 1 = x for any x (1 is the
multiplicative identity). The basis vectors 1 and i behave exactly like the
familiar complex numbers 1 and i in both algebras.</p>
<table SUMMARY="Quaternion basis vector multiplication rules" width="75%">
<tr>
<td width="33%"><code>ij = k</code></td>
<td width="33%"><code>jk = i</code></td>
<td width="33%"><code>ki = j</code></td>
</tr>
<tr>
<td><code>ji = -k</code></td>
<td><code>kj = -i</code></td>
<td><code>ik = -j</code></td>
</tr>
<tr>
<td><code>ii = jj = kk = -1</code></td>
<td><code>ijk = -1</code></td>
<td> </td>
</tr>
</table>
<table SUMMARY="Hypercomplex basis vector multiplication rules" width="75%">
<tr>
<td width="33%"><code>ij = k</code></td>
<td width="33%"><code>jk = -i</code></td>
<td width="33%"><code>ki = -j</code></td>
</tr>
<tr>
<td><code>ji = k</code></td>
<td><code>kj = -i</code></td>
<td><code>ik = -j</code></td>
</tr>
<tr>
<td><code>ii = jj = kk = -1</code></td>
<td><code>ijk = 1</code></td>
<td> </td>
</tr>
</table>
<p>A distance estimation calculation is used with the quaternion calculations
to speed them up. The proof that this distance estimation formula works does
not generalize from two to four dimensions but the formula seems to work well
anyway, the absence of proof notwithstanding!</p>
<p>The presence of one of the function keywords <code>sqr</code>, <code>
cube</code>, etc. determines which function is used for <em><code>
f(h)</code></em> in the iteration formula <em> <code>h(n+1) = f(h(n)) +
p</code></em>. The default is <code>sqr.</code> Most of the function keywords
work only if the <code>hypercomplex</code> keyword is present. Only <code>
sqr</code> and <code>cube</code> work with <code> quaternion</code>. The
functions are all familiar complex functions generalized to four dimensions.
Function Keyword Maps 4-D value h to:</p>
<table SUMMARY="Function Keyword Maps 4-D value of h" width="75%">
<tr>
<td width="30%"><code>sqr</code></td>
<td width="70%">h*h</td>
</tr>
<tr>
<td><code>cube</code></td>
<td>h*h*h</td>
</tr>
<tr>
<td><code>exp</code></td>
<td>e raised to the power h</td>
</tr>
<tr>
<td><code>reciprocal</code></td>
<td>1/h</td>
</tr>
<tr>
<td><code>sin</code></td>
<td>sine of h</td>
</tr>
<tr>
<td><code>asin</code></td>
<td>arcsine of h</td>
</tr>
<tr>
<td><code>sinh</code></td>
<td>hyperbolic sine of h</td>
</tr>
<tr>
<td><code>asinh</code></td>
<td>inverse hyperbolic sine of h</td>
</tr>
<tr>
<td><code>cos</code></td>
<td>cosine of h</td>
</tr>
<tr>
<td><code>acos</code></td>
<td>arccosine of h</td>
</tr>
<tr>
<td><code>cosh</code></td>
<td>hyperbolic cos of h</td>
</tr>
<tr>
<td><code>acosh</code></td>
<td>inverse hyperbolic cosine of h</td>
</tr>
<tr>
<td><code>tan</code></td>
<td>tangent of h</td>
</tr>
<tr>
<td><code>atan</code></td>
<td>arctangent of h</td>
</tr>
<tr>
<td><code>tanh</code></td>
<td>hyperbolic tangent of h</td>
</tr>
<tr>
<td><code>atanh</code></td>
<td>inverse hyperbolic tangent of h</td>
</tr>
<tr>
<td><code>ln</code></td>
<td>natural logarithm of h</td>
</tr>
<tr>
<td><code>pwr(x,y)</code></td>
<td>h raised to the complex power x+iy</td>
</tr>
</table>
<p>A simple example of a julia fractal object is:</p>
<pre>
julia_fractal {
<-0.083,0.0,-0.83,-0.025>
quaternion
sqr
max_iteration 8
precision 15
}
</pre>
<p>The first renderings of julia fractals using quaternions were done by Alan
Norton and later by John Hart in the '80's. This POV-Ray
implementation follows <em>Fractint</em> in pushing beyond what is known
in the literature by using hypercomplex numbers and by generalizing the
iterating formula to use a variety of transcendental functions instead of
just the classic Mandelbrot <em>z2 + c</em> formula. With an extra two
dimensions and eighteen functions to work with, intrepid explorers should be
able to locate some new fractal beasts in hyperspace, so have at it!</p></div>
<a name="r3_4_5_1_8"></a>
<div class="content-level-h5" contains="Lathe" id="r3_4_5_1_8">
<h5>3.4.5.1.8 Lathe</h5>
<p>The <code>lathe</code> is an object generated from rotating a
two-dimensional curve about an axis. This curve is defined by a set of points
which are connected by linear, quadratic, cubic or bezier spline curves. The
syntax is:</p>
<pre>
LATHE:
lathe {
[SPLINE_TYPE] Number_Of_Points, <Point_1>
<Point_2>... <Point_n>
[LATHE_MODIFIER...]
}
SPLINE_TYPE:
linear_spline | quadratic_spline | cubic_spline | bezier_spline
LATHE_MODIFIER:
sturm | OBJECT_MODIFIER
</pre>
<p>Lathe default values:</p>
<pre>
SPLINE_TYPE : linear_spline
sturm : off
</pre>
<p>The first item is a keyword specifying the type of spline. The default if
none is specified is <code>linear_spline</code>. The required integer value
<em><code>Number_Of_Points</code></em> specifies how many two-dimensional
points are used to define the curve. The points follow and are specified by
2-D vectors. The curve is not automatically closed, i.e. the first and last
points are not automatically connected. You will have to do this yourself
if you want a closed curve. The curve thus defined is rotated about the
y-axis to form the lathe object, centered at the origin.</p>
<p>
The following examples creates a simple lathe object that looks like a thick
cylinder, i.e. a cylinder with a thick wall:</p>
<pre>
lathe {
linear_spline
5,
<2, 0>, <3, 0>, <3, 5>, <2, 5>, <2, 0>
pigment {Red}
}
</pre>
<p>The cylinder has an inner radius of 2 and an outer radius of 3, giving a
wall width of 1. It's height is 5 and it's located at the origin
pointing up, i.e. the rotation axis is the y-axis.</p>
<p class="Note"><strong>Note:</strong> The first and last point are equal to get a closed curve.</p>
<p>
The splines that are used by the lathe and prism objects are a little bit
difficult to understand. The basic concept of splines is to draw a curve
through a given set of points in a determined way. The default <code>
linear_spline</code> is the simplest spline because it's nothing more
than connecting consecutive points with a line. This means the curve
that is drawn between two points only depends on those two points. No
additional information is taken into account. The other splines are different
in that they do take other points into account when connecting two points.
This creates a smooth curve and, in the case of the cubic spline, produces
smoother transitions at each point.</p>
<p>The <code>quadratic_spline</code> keyword creates splines that are made of
quadratic curves. Each of them connects two consecutive points. Since those
two points (call them second and third point) are not sufficient to describe
a quadratic curve, the predecessor of the second point is taken into account
when the curve is drawn. Mathematically, the relationship (their relative locations on
the 2-D plane) between the first and second point determines the slope of the
curve at the second point. The slope of the curve at the third point is out
of control. Thus quadratic splines look much smoother than linear splines but
the transitions at each point are generally not smooth because the slopes on
both sides of the point are different.</p>
<p>The <code>cubic_spline</code> keyword creates splines which overcome the
transition problem of quadratic splines because they also take a fourth
point into account when drawing the curve between the second and third point.
The slope at the fourth point is under control now and allows a smooth
transition at each point. Thus cubic splines produce the most flexible and
smooth curves.</p>
<p>The <code>bezier_spline</code> is an alternate kind of cubic spline. Points
1 and 4 specify the end points of a segment and points 2 and 3 are control
points which specify the slope at the endpoints. Points 2 and 3 do not
actually lie on the spline. They adjust the slope of the spline. If you draw
an imaginary line between point 1 and 2, it represents the slope at point 1.
It is a line tangent to the curve at point 1. The greater the distance
between 1 and 2, the flatter the curve. With a short tangent the spline can
bend more. The same holds true for control point 3 and endpoint 4. If you
want the spline to be smooth between segments, points 3 and 4 on one segment
and points 1 and 2 on the next segment must form a straight line and point 4
of one segment must be the same as point 1 on the next segment.</p>
<p>
You should note that the number of spline segments, i. e. curves between two
points, depends on the spline type used. For linear splines you get n-1
segments connecting the points P[i], i=1,...,n. A quadratic spline gives you
n-2 segments because the last point is only used for determining the slope, as
explained above (thus you will need at least three points to define a
quadratic spline). The same holds for cubic splines where you get n-3
segments with the first and last point used only for slope calculations (thus
needing at least four points). The bezier spline requires 4 points per
segment, creating n/4 segments.</p>
<p>
If you want to get a closed quadratic and cubic spline with smooth
transitions at the end points you have to make sure that in the cubic case
P[n-1] = P[2] (to get a closed curve), P[n] = P[3] and P[n-2] = P[1] (to
smooth the transition). In the quadratic case P[n-1] = P[1] (to close the
curve) and P[n] = P[2].</p>
<p>The <code>sturm</code> keyword can be used to specify that the slower, but
more accurate, Sturmian root solver should be used. Use it, if the shape does not render properly. Since a quadratic polynomial has to be solved for the linear spline lathe, the Sturmian root solver is not needed.</p></div>
<a name="r3_4_5_1_9"></a>
<div class="content-level-h5" contains="Ovus" id="r3_4_5_1_9">
<h5>3.4.5.1.9 Ovus</h5>
<p>An <code>ovus</code> is a shape that looks like an egg. The syntax of the <code>ovus</code> object is:</p>
<pre>
OVUS:
ovus {
Bottom_radius, Top_radius
[OBJECT_MODIFIERS...]
}
</pre>
<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
<td width="290px">
<p>Where <em><code>Bottom_radius</code></em> is a float value giving the radius of the bottom sphere and <em><code>Top_radius</code></em> is a float specifying the radius of the top sphere. The top sphere and the bottom sphere are connected together with a suitably truncated citrus (lemon), that is automatically computed so as to provide the needed continuity to the shape.</p>
</td>
<td><img class="left" width="125px" src="images/1/12/RefImgOvus2D.png"></td>
<td>
<ul>
<li>The center of the top sphere lies on the top of the bottom sphere.</li>
<li>The bottom sphere of the <code>ovus</code> is centered at the origin.</li>
<li>The top sphere of the <code>ovus</code> lies on the y-axis.</li>
</ul>
</td>
</tr>
<tr>
<td></td>
<td><p class="caption">An ovus 2D section</p></td>
<td></td>
</tr>
</table>
<table class="centered" width="640px" cellpadding="0" cellspacing="10">
<tr>
<td><img class="centered" width="620px" src="images/7/72/RefImgOvus3D.png"></td>
</tr>
<tr>
<td><p class="caption">The ovus and it's constituent 3D shapes</p></td>
</tr>
</table>
<p>Whenever the top radius is bigger than twice the bottom radius, the <code>ovus</code> degenerates into a <code>sphere</code> with an offset center. There are a lot of variations in the shape of the <code>ovus</code>.</p>
<p class="Note"><strong>Note:</strong> According to the ratio of the radius, the pointy part is the smallest radius, but is <em>not</em> always on top!</p>
<table class="centered" width="690px" cellpadding="0" cellspacing="10">
<tr>
<td><img class="centered" width="670px" src="images/4/46/RefImgDemoOvus.jpg"></td>
</tr>
<tr>
<td><p class="caption">Evolution of ratio from 0 to 1.95 in 0.15 steps.</p></td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> See the following <em>MathWorld</em> references for more information about the math behind how the <code>ovus</code> object is constructed.</p>
<ul>
<li><a href="http://mathworld.wolfram.com/Torus.html">Torus</a></li>
<li><a href="http://mathworld.wolfram.com/Lemon.html">Lemon</a></li>
<li><a href="http://mathworld.wolfram.com/SpindleTorus.html">SpindleTorus</a></li>
</ul></div>
<a name="r3_4_5_1_10"></a>
<div class="content-level-h5" contains="Parametric" id="r3_4_5_1_10">
<h5>3.4.5.1.10 Parametric</h5>
<p>Where the isosurface object uses implicit surface functions, F(x,y,z)=0, the parametric object
is a set of equations for a surface expressed in the form of the parameters that locate points on
the surface, x(u,v), y(u,v), z(u,v). Each pair of values for u and v gives a single point <code><x,y,z></code>
in 3d space.</p>
<p>The parametric object is not a solid object it is <em>hollow</em>, like a thin shell.</p>
<p>Syntax:</p>
<pre>
parametric {
function { FUNCTION_ITEMS },
function { FUNCTION_ITEMS },
function { FUNCTION_ITEMS }
<u1,v1>, <u2,v2>
[contained_by { SPHERE | BOX }]
[max_gradient FLOAT_VALUE]
[accuracy FLOAT_VALUE]
[precompute DEPTH, VarList]
}
</pre>
<p>Parametric default values:</p>
<pre>
accuracy : 0.001
</pre>
<p>The first function calculates the <code>x</code> value of the surface, the second <code>y</code> and
the third the <code>z</code> value. Allowed is any function that results in a float.</p>
<p><code><u1,v1>,<u2,v2></code> boundaries of the <code>(u,v)</code> space, in which
the surface has to be calculated</p>
<p><code>contained_by { ... }</code> The contained_by 'object' limits the area where POV-Ray
samples for the surface of the function. This container can either be a sphere or a box, both
of which use the standard POV-Ray syntax. If not specified a <code>box {<-1,-1,-1>, <1,1,1>}</code>
will be used as default.</p>
<p><code>max_gradient</code>,
It is not really the maximum gradient. It's the maximum magnitude of
all six partial derivatives over the specified ranges of u and v.
That is, if you take <code>dx/du</code>, <code>dx/dv</code>, <code>dy/du</code>,
<code>dy/dv</code>, <code>dz/du</code>, and <code>dz/dv</code>
and calculate them over the entire range, the <code>max_gradient</code> is the
maximum of the absolute values of all of those values.
</p>
<p><code>accuracy</code> The default value is 0.001. Smaller values produces more accurate surfaces,
but take longer to render.</p>
<p><code>precompute</code> can speedup rendering of parametric surfaces. It simply divides parametric
surfaces into small ones (2^depth) and precomputes ranges of the variables(x,y,z) which you specify
after depth. The maximum depth is 20. High values of depth can produce arrays that use a lot of memory,
take longer to parse and render faster. If you declare a parametric surface with the precompute keyword
and then use it twice, all arrays are in memory only once.</p>
<p>Example, a unit sphere:</p>
<pre>
parametric {
function { sin(u)*cos(v) }
function { sin(u)*sin(v) }
function { cos(u) }
<0,0>, <2*pi,pi>
contained_by { sphere{0, 1.1} }
max_gradient ??
accuracy 0.0001
precompute 10 x,y,z
pigment {rgb 1}
}
</pre></div>
<a name="r3_4_5_1_11"></a>
<div class="content-level-h5" contains="Prism" id="r3_4_5_1_11">
<h5>3.4.5.1.11 Prism</h5>
<p>The <code>prism</code> is an object generated by specifying one or more two-dimensional, closed curves in the x-z plane and sweeping them along y axis. These curves are defined by a set of points which are connected by linear, quadratic, cubic or bezier splines. The syntax for the prism is:</p>
<pre>
PRISM:
prism {
[PRISM_ITEMS...] Height_1, Height_2, Number_Of_Points,
<Point_1>, <Point_2>, ... <Point_n>
[ open ] [PRISM_MODIFIERS...]
}
PRISM_ITEM:
linear_spline | quadratic_spline | cubic_spline |
bezier_spline | linear_sweep | conic_sweep
PRISM_MODIFIER:
sturm | OBJECT_MODIFIER
</pre>
<p>Prism default values:</p>
<pre>
SPLINE_TYPE : linear_spline
SWEEP_TYPE : linear_sweep
sturm : off
</pre>
<p>The first items specify the spline type and sweep type. The defaults if
none is specified is <code>linear_spline</code> and <code>
linear_sweep</code>. This is followed by two float values <em><code>
Height_1</code></em> and <em> <code>Height_2</code></em> which are the y
coordinates of the top and bottom of the prism. This is followed by a float
value specifying the number of 2-D points you will use to define the prism.
(This includes all control points needed for quadratic, cubic and bezier
splines). This is followed by the specified number of 2-D vectors which
define the shape in the x-z plane.</p>
<p>
The interpretation of the points depends on the spline type. The prism
object allows you to use any number of sub-prisms inside one prism statement
(they are of the same spline and sweep type). Wherever an even number of
sub-prisms overlaps a hole appears.</p>
<p class="Note"><strong>Note:</strong> You need not have multiple sub-prisms and they need not overlap as these examples do.</p>
<p>
In the <code>linear_spline</code> the first point specified is the start of
the first sub-prism. The following points are connected by straight lines. If
you specify a value identical to the first point, this closes the sub-prism
and next point starts a new one. When you specify the value of that
sub-prism's start, then it is closed. Each of the sub-prisms has to be
closed by repeating the first point of a sub-prism at the end of the
sub-prism's point sequence. In this example, there are two rectangular
sub-prisms nested inside each other to create a frame.</p>
<pre>
prism {
linear_spline
0, 1, 10,
<0,0>, <6,0>, <6,8>, <0,8>, <0,0>, //outer rim
<1,1>, <5,1>, <5,7>, <1,7>, <1,1> //inner rim
}
</pre>
<p>The last sub-prism of a linear spline prism is automatically closed - just
like the last sub-polygon in the polygon statement - if the first and last
point of the sub-polygon's point sequence are not the same. This make it
very easy to convert between polygons and prisms. Quadratic, cubic and bezier
splines are never automatically closed.</p>
<p>
In the <code> quadratic_spline</code>, each sub-prism needs an additional
control point at the beginning of each sub-prisms' point sequence to
determine the slope at the start of the curve. The first point specified is
the control point which is not actually part of the spline. The second point
is the start of the spline. The sub-prism ends when this second point is
duplicated. The next point is the control point of the next sub-prism. The
point after that is the first point of the second sub-prism. Here is an
example:</p>
<pre>
prism {
quadratic_spline
0, 1, 12,
<1,-1>, <0,0>, <6,0>, //outer rim; <1,-1> is control point and
<6,8>, <0,8>, <0,0>, //<0,0> is first & last point
<2,0>, <1,1>, <5,1>, //inner rim; <2,0> is control point and
<5,7>, <1,7>, <1,1> //<1,1> is first & last point
}
</pre>
<p>In the <code>cubic_spline</code>, each sub-prism needs two additional
control points -- one at the beginning of each sub-prisms' point sequence
to determine the slope at the start of the curve and one at the end. The
first point specified is the control point which is not actually part of the
spline. The second point is the start of the spline. The sub-prism ends when
this second point is duplicated. The next point is the control point of the
end of the first sub-prism. Next is the beginning control point of the next
sub-prism. The point after that is the first point of the second
sub-prism.</p>
<p>
Here is an example:</p>
<pre>
prism {
cubic_spline
0, 1, 14,
<1,-1>, <0,0>, <6,0>, //outer rim; First control is <1,-1> and
<6,8>, <0,8>, <0,0>, //<0,0> is first & last point.
<-1,1>, //Last control of first spline is <-1,1>
<2,0>, <1,1>, <5,1>, //inner rim; First control is <2,0> and
<5,7>, <1,7>, <1,1>, //<1,1> is first & last point
<0,2> //Last control of first spline is <0,2>
}
</pre>
<p>The <code>bezier_spline</code> is an alternate kind of cubic spline.
Points 1 and 4 specify the end points of a segment and points 2 and 3 are
control points which specify the slope at the endpoints. Points 2 and 3 do
not actually lie on the spline. They adjust the slope of the spline. If you
draw an imaginary line between point 1 and 2, it represents the slope at
point 1. It is a line tangent to the curve at point 1. The greater the
distance between 1 and 2, the flatter the curve. With a short tangent the
spline can bend more. The same holds true for control point 3 and endpoint 4.
If you want the spline to be smooth between segments, point 3 and 4 on one
segment and point 1 and 2 on the next segment must form a straight line and
point 4 of one segment must be the same as point one on the next segment.</p>
<p>
By default linear sweeping is used to create the prism, i.e. the prism's
walls are perpendicular to the x-z-plane (the size of the curve does not
change during the sweep). You can also use <code>conic_sweep</code> that
leads to a prism with cone-like walls by scaling the curve down during the
sweep.</p>
<p>
Like cylinders the prism is normally closed. You can remove the caps on the
prism by using the <code>open</code> keyword. If you do so you should not
use it with CSG because the results may get wrong.</p>
<p>For an explanation of the spline concept read the description of the
<a href="r3_4.html#r3_4_5_1_8">Lathe</a> object. Also see the tutorials on
<a href="t2_3.html#t2_3_1_1">Lathe</a> and <a href="t2_3.html#t2_3_1_3">Prism</a> objects.</p>
<p>The <code> sturm</code> keyword specifies the slower but more accurate
Sturmian root solver which may be used with the cubic or bezier spline prisms
if the shape does not render properly. The linear and quadratic spline prisms
do not need the Sturmian root solver.</p></div>
<a name="r3_4_5_1_12"></a>
<div class="content-level-h5" contains="Sphere" id="r3_4_5_1_12">
<h5>3.4.5.1.12 Sphere</h5>
<p>The syntax of the <code>sphere</code> object is:</p>
<pre>
SPHERE:
sphere {
<Center>, Radius
[OBJECT_MODIFIERS...]
}
</pre>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/b/b2/RefImgSphgeom.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The geometry of a sphere.</p>
</td>
</tr>
</table>
<p>Where <em><code><Center></code></em> is a vector specifying the x,
y, z coordinates of the center of the sphere and <em><code>
Radius</code></em> is a float value specifying the radius. Spheres may be
scaled unevenly giving an ellipsoid shape.</p>
<p>
Because spheres are highly optimized they make good bounding shapes (if
manual bounding seems to be necessary).</p></div>
<a name="r3_4_5_1_13"></a>
<div class="content-level-h5" contains="Sphere Sweep" id="r3_4_5_1_13">
<h5>3.4.5.1.13 Sphere Sweep</h5>
<p>The syntax of the <code>sphere_sweep</code> object is:</p>
<pre>
SPHERE_SWEEP:
sphere_sweep {
linear_spline | b_spline | cubic_spline
NUM_OF_SPHERES,
CENTER, RADIUS,
CENTER, RADIUS,
...
CENTER, RADIUS
[tolerance DEPTH_TOLERANCE]
[OBJECT_MODIFIERS]
}
</pre>
<p>Sphere_sweep default values:</p>
<pre>
tolerance : 1.0e-6 (0.000001)
</pre>
<p>A Sphere Sweep is the envelope of a moving sphere with varying radius, or, in other words, the
space a sphere occupies during its movement along a spline.
<br>Sphere Sweeps are modeled by specifying a list of single spheres which are then interpolated.
<br>Three kinds of interpolation are supported:</p><ul>
<li><code>linear_spline</code> : Interpolating the input data with a linear function, which means
that the single spheres are connected by straight tubes.</li>
<li><code>b_spline</code> : Approximating the input data using a cubic b-spline function, which
results in a curved object.</li>
<li><code>cubic_spline</code> : Approximating the input data using a cubic spline,
which results in a curved object.</li></ul>
<p>The sphere list (center and radius of each sphere) can take as many spheres as you like to describe
the object, but you will need at least two spheres for a <code>linear_spline</code>, and four spheres
for <code>b_spline</code> or <code>cubic_spline</code>.</p>
<p>Optional: The depth tolerance that should be used for the intersection calculations. This is done by
adding the <code>tolerance</code> keyword and the desired value: the default distance is
1.0e-6 (0.000001) and should do for most sphere sweep objects.
<br>You should change this when you see dark spots on the surface of the object. These are probably
caused by an effect called <em>self-shading</em>. This means that the object casts shadows onto itself at some
points because of calculation errors. A ray tracing program usually defines the minimal distance a ray
must travel before it actually hits another (or the same) object to avoid this effect. If this distance is
chosen too small, self-shading may occur.
<br>If so, specify <code>tolerance 1.0e-4</code> or higher.</p>
<p class="Note"><strong>Note:</strong> If these dark spots remain after raising the tolerance, you might get rid of these spots by
using adaptive super-sampling (method 2) for anti-aliasing. Images look better with anti-aliasing anyway.</p>
<p class="Note"><strong>Note:</strong> The merge CSG operation is not recommended with Sphere Sweeps: there could be a small gap
between the merged objects!</p></div>
<a name="r3_4_5_1_14"></a>
<div class="content-level-h5" contains="Superquadric Ellipsoid" id="r3_4_5_1_14">
<h5>3.4.5.1.14 Superquadric Ellipsoid</h5>
<p>The <code>superellipsoid</code> object creates a shape known as a <em>
superquadric ellipsoid</em> object. It is an extension of the quadric
ellipsoid. It can be used to create boxes and cylinders with round edges and
other interesting shapes. Mathematically it is given by the equation:</p>
<table class="centered" width="465x" cellpadding="0" cellspacing="10">
<tr>
<td>
<!--<img src="ref_tex/sqemath.tex" alt="">---><img class="center" width="445px" src="images/5/5b/RefImgSqemath.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Superquadric Ellipsoid Formula</p>
</td>
</tr>
</table>
<p>The values of <em><code>e</code></em> and <em><code>n</code></em>, called
the <em>east-west</em> and <em>north-south</em> exponent, determine the shape
of the superquadric ellipsoid. Both have to be greater than zero. The sphere
is given by <em>e = 1</em> and <em>n = 1</em>.</p>
<p>
The syntax of the superquadric ellipsoid is:</p>
<pre>
SUPERELLIPSOID:
superellipsoid {
<Value_E, Value_N>
[OBJECT_MODIFIERS...]
}
</pre>
<p>The 2-D vector specifies the <em><code>e</code></em> and <em><code>
n</code></em> values in the equation above. The object sits at the origin and
occupies a space about the size of a <code>
box{<-1,-1,-1>,<1,1,1>}</code>.</p>
<p>
Two useful objects are the rounded box and the rounded cylinder. These are
declared in the following way.</p>
<pre>
#declare Rounded_Box = superellipsoid { <Round, Round> }
#declare Rounded_Cylinder = superellipsoid { <1, Round> }
</pre>
<p>The roundedness value <code>Round</code> determines the roundedness of the
edges and has to be greater than zero and smaller than one. The smaller you
choose the values, the smaller and sharper the edges will get.</p>
<p>
Very small values of <em><code>e</code></em> and <em><code>n</code></em>
might cause problems with the root solver (the Sturmian root solver cannot be
used).</p></div>
<a name="r3_4_5_1_15"></a>
<div class="content-level-h5" contains="Surface of Revolution" id="r3_4_5_1_15">
<h5>3.4.5.1.15 Surface of Revolution</h5>
<p>The <code>sor</code> object is a <em>surface of revolution</em> generated
by rotating the graph of a function about the y-axis. This function describes
the dependence of the radius from the position on the rotation axis. The
syntax is:</p>
<pre>
SOR:
sor {
Number_Of_Points, <Point_1>, <Point_2>, ... <Point_n>
[ open ] [SOR_MODIFIERS...]
}
SOR_MODIFIER:
sturm | OBJECT_MODIFIER
</pre>
<p>SOR default values:</p>
<pre>
sturm : off
</pre>
<p>The float value <em><code>Number_Of_Points</code></em> specifies the
number of 2-D vectors which follow. The points <em><code>
<Point_1></code></em> through <em><code><Point_n></code></em> are
two-dimensional vectors consisting of the radius and the corresponding
height, i.e. the position on the rotation axis. These points are smoothly
connected (the curve is passing through the specified points) and rotated
about the y-axis to form the SOR object. The first and last points are only
used to determine the slopes of the function at the start and end point. They
do not actually lie on the curve. The function used for the SOR object is
similar to the splines used for the lathe object. The difference is that the
SOR object is less flexible because it underlies the restrictions of any
mathematical function, i.e. to any given point y on the rotation axis belongs
at most one function value, i.e. one radius value. You cannot rotate
closed curves with the SOR object. Also, make sure that the curve does not cross zero (y-axis)
as this can result in 'less than perfect' bounding cylinders. POV-Ray will very likely fail to
render large chunks of the part of the spline contained in such an interval.</p>
<p>
The optional keyword <code>open</code> allows you to remove the caps on the
SOR object. If you do this you should not use it with CSG because
the results may be wrong.</p>
<p>
The SOR object is useful for creating bottles, vases, and things like that.
A simple vase could look like this:</p>
<pre>
#declare Vase = sor {
7,
<0.000000, 0.000000>
<0.118143, 0.000000>
<0.620253, 0.540084>
<0.210970, 0.827004>
<0.194093, 0.962025>
<0.286920, 1.000000>
<0.468354, 1.033755>
open
}
</pre>
<p>One might ask why there is any need for a SOR object if there is already a
lathe object which is much more flexible. The reason is quite simple. The
intersection test with a SOR object involves solving a cubic polynomial while
the test with a lathe object requires to solve a 6th order polynomial (you
need a cubic spline for the same smoothness). Since most SOR and lathe
objects will have several segments this will make a great difference in
speed. The roots of the 3rd order polynomial will also be more accurate and
easier to find.</p>
<p>The <code>sturm</code> keyword may be added to specify the slower but more
accurate Sturmian root solver. It may be used with the surface of revolution
object if the shape does not render properly.</p>
<p>
The following explanations are for the mathematically interested reader who
wants to know how the surface of revolution is calculated. Though it is not
necessary to read on it might help in understanding the SOR object.</p>
<p>
The function that is rotated about the y-axis to get the final SOR object is
given by</p>
<table class="centered" width="380x" cellpadding="0" cellspacing="10">
<tr>
<td>
<!--<img src="ref_tex/sormath.tex" alt="">---><img class="center" width="360px" src="images/a/af/RefImgSormath.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Surface of Revolution Formula</p>
</td>
</tr>
</table>
<p>with radius <em><code>r</code></em> and height <em><code>h</code></em>.
Since this is a cubic function in h it has enough flexibility to allow smooth
curves.</p>
<p>
The curve itself is defined by a set of n points P(i), i=0...n-1, which are
interpolated using one function for every segment of the curve. A segment j,
j=1...n-3, goes from point P(j) to point P(j+1) and uses points P(j-1) and
P(j+2) to determine the slopes at the endpoints. If there are n points we
will have n-3 segments. This means that we need at least four points to get a
proper curve. The coefficients A(j), B(j), C(j) and D(j) are calculated for
every segment using the equation</p>
<table class="centered" width="470x" cellpadding="0" cellspacing="10">
<tr>
<td>
<!--<img src="ref_tex/curvmath.tex" alt="">---><img class="center" width="450px" src="images/a/af/RefImgCurvmath.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Curve Math</p>
</td>
</tr>
</table>
<p>where r(j) is the radius and h(j) is the height of point P(j).</p>
<p>
The figure below shows the configuration of the points P(i), the location of
segment j, and the curve that is defined by this segment.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/e/e7/RefImgSegmpts.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Points on a surface of revolution.</p>
</td>
</tr>
</table></div>
<a name="r3_4_5_1_16"></a>
<div class="content-level-h5" contains="Text" id="r3_4_5_1_16">
<h5>3.4.5.1.16 Text</h5>
<p>A <code>text</code> object creates 3-D text as an extruded block letter. Currently only TrueType fonts (ttf) and TrueType Collections (ttc) are supported but the syntax allows for other font types to be added in the future. If TrueType Collections are used, the first font found in the collection will be used. The syntax is:</p>
<pre>
TEXT_OBECT:
text {
ttf "fontname.ttf/ttc" "String_of_Text"
Thickness, <Offset>
[OBJECT_MODIFIERS...]
}
</pre>
<p>Where <code>fontname.ttf</code> or <code>fontname.ttc</code> is the name of the TrueType font file. It is a quoted string literal or string expression. The string expression which follows is the actual text of the string object. It too may be a quoted string literal or string expression. See section <a href="r3_3.html#r3_3_1_9">Strings</a> for more on string expressions.</p>
<p>In version 3.7 several fonts are now <em>built-in</em>. It should be noted that this is only a preliminary solution so the benchmark program will run without installing POV-Ray. Future versions may lack this mechanism, so in scene files (other than the built-in benchmark) you should continue to reference the external font files as before. Consequently, the following <em>alternate</em> syntax is available:</p>
<pre>
TEXT_OBECT:
text {
internal Font_Number "String_of_Text"
Thickness, <Offset>
[OBJECT_MODIFIERS] }
}
</pre>
<p>Where <code><em>Font_Number</em></code> is one of the <em>integer</em> values from the list below:</p>
<ol start=0>
<li>povlogo.ttf</li>
<li>timrom.ttf</li>
<li>cyrvetic.ttf</li>
<li>crystal.ttf</li>
</ol>
<p class="Note"><strong>Note:</strong> An out of range <code><em>Font_Number</em></code> value will default to 0.</p>
<p>The text will start with the origin at the lower left, front of the first character and will extend in the +x-direction. The baseline of the text follows the x-axis and descender drop into the -y-direction. The front of the character sits in the x-y-plane and the text is extruded in the +z-direction. The front-to-back thickness is specified by the required value <em><code>
Thickness</code></em>.</p>
<p>Characters are generally sized so that 1 unit of vertical spacing is correct. The characters are about 0.5 to 0.75 units tall.</p>
<p>The horizontal spacing is handled by POV-Ray internally including any kerning information stored in the font. The required vector <em><code><Offset></code></em> defines any extra translation between each character. Normally you should specify a zero for this value. Specifying <code>0.1*x</code> would put additional 0.1 units of space between each character. Here is an example:</p>
<pre>
text {
ttf "timrom.ttf" "POV-Ray" 1, 0
pigment { Red }
}
</pre>
<p>Only printable characters are allowed in text objects. Characters such as return, line feed, tabs, backspace etc. are not supported.</p>
<p>For easy access to your fonts, set the <a href="r3_2.html#r3_2_5_4">Library_Path</a> to the directory that contains your font collection.</p></div>
<a name="r3_4_5_1_17"></a>
<div class="content-level-h5" contains="Torus" id="r3_4_5_1_17">
<h5>3.4.5.1.17 Torus</h5>
<p>A <code>torus</code> is a 4th order quartic polynomial shape that looks
like a donut or inner tube. Because this shape is so useful and quartics are
difficult to define, POV-Ray lets you take a short-cut and define a torus
by:</p>
<pre>
TORUS:
torus {
Major, Minor
[TORUS_MODIFIER...]
}
TORUS_MODIFIER:
sturm | OBJECT_MODIFIER
</pre>
<p>Torus default values:</p>
<pre>
sturm : off
</pre>
<p>where <em><code>Major</code></em> is a float value giving the major radius
and <em><code>Minor</code></em> is a float specifying the minor radius. The
major radius extends from the center of the hole to the mid-line of the rim
while the minor radius is the radius of the cross-section of the rim. The
torus is centered at the origin and lies in the x-z-plane with the y-axis
sticking through the hole.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/2/29/RefImgMimxrtor.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Major and minor radius of a torus.</p>
</td>
</tr>
</table>
<p>The torus is internally bounded by two cylinders and two rings forming a
thick cylinder. With this bounding cylinder the performance of the torus
intersection test is vastly increased. The test for a valid torus
intersection, i.e. solving a 4th order polynomial, is only performed if the
bounding cylinder is hit. Thus a lot of slow root solving calculations are
avoided.</p>
<p>Calculations for all higher order polynomials must be very accurate. If the
torus renders improperly you may add the keyword <code>sturm</code> to use
POV-Ray's slower-yet-more-accurate Sturmian root solver.</p></div>
<a name="r3_4_5_2"></a>
<div class="content-level-h4" contains="Finite Patch Primitives" id="r3_4_5_2">
<h4>3.4.5.2 Finite Patch Primitives</h4>
<p>There are six totally thin, finite objects which have no well-defined inside. They are <a href="r3_4.html#r3_4_5_2_1">bicubic patch</a>, <a href="r3_4.html#r3_4_5_2_2">disc</a>, <a href="r3_4.html#r3_4_5_2_7">smooth triangle</a>, <a href="r3_4.html#r3_4_5_2_6">triangle</a>, <a href="r3_4.html#r3_4_5_2_5">polygon</a>, <a href="r3_4.html#r3_4_5_2_3">mesh</a>, and <a href="r3_4.html#r3_4_5_2_4">mesh2</a>. They may be combined in CSG union, but cannot be used inside a <code>clipped_by</code> statement.</p>
<p class="Note"><strong>Note:</strong> Patch objects <em>may</em> give unexpected results when used in differences and intersections.</p>
<p>These conditions apply:</p>
<ol>
<li>Solids may be differenced from bicubic patches with the expected results.</li>
<li>Differencing a bicubic patch from a solid <em>may</em> give unexpected results.</li>
<ul>
<li>Especially if the inverse keyword is used!</li>
</ul>
<li>Intersecting a solid and a bicubic patch will give the expected results.</li>
<ul>
<li>The parts of the patch that intersect the solid object will be visible.</li>
</ul>
<li>Merging a solid and a bicubic patch will remove the parts of the bicubic patch that intersect the solid.</li>
</ol>
<p>Because these types are finite POV-Ray can use automatic bounding on them to speed up rendering time. As with all shapes they can be translated, rotated and scaled.</p></div>
<a name="r3_4_5_2_1"></a>
<div class="content-level-h5" contains="Bicubic Patch" id="r3_4_5_2_1">
<h5>3.4.5.2.1 Bicubic Patch</h5>
<p>A <code>bicubic_patch</code> is a 3D curved surface created from a mesh of
triangles. POV-Ray supports a type of bicubic patch called a <em>Bezier
patch</em>. A bicubic patch is defined as follows:</p>
<pre>
BICUBIC_PATCH:
bicubic_patch {
PATCH_ITEMS...
<Point_1>,<Point_2>,<Point_3>,<Point_4>,
<Point_5>,<Point_6>,<Point_7>,<Point_8>,
<Point_9>,<Point_10>,<Point_11>,<Point_12>,
<Point_13>,<Point_14>,<Point_15>,<Point_16>
[OBJECT_MODIFIERS...]
}
PATCH_ITEMS:
type Patch_Type | u_steps Num_U_Steps | v_steps Num_V_Steps |
flatness Flatness
</pre>
<p>Bicubic patch default values:</p>
<pre>
flatness : 0.0
u_steps : 0
v_steps : 0
</pre>
<p>The keyword <code>type</code> is followed by a float <em><code>
Patch_Type</code></em> which currently must be either 0 or 1. For type 0 only
the control points are retained within POV-Ray. This means that a minimal
amount of memory is needed but POV-Ray will need to perform many extra
calculations when trying to render the patch. Type 1 preprocesses the patch
into many subpatches. This results in a significant speedup in rendering at
the cost of memory.</p>
<p>The four parameters <code>type</code>, <code>flatness</code>, <code>
u_steps</code> and <code>v_steps</code> may appear in any order. Only
<code>type</code> is required. They are followed by 16 vectors (4 rows
of 4) that define the x, y, z coordinates of the 16 control points which
define the patch. The patch touches the four corner points <em><code>
<Point_1></code></em>, <em><code><Point_4></code></em>, <em>
<code><Point_13></code></em> and <em> <code>
<Point_16></code></em> while the other 12 points pull and stretch the
patch into shape. The Bezier surface is enclosed by the convex hull formed by
the 16 control points, this is known as the <em>convex hull property</em>.</p>
<p>The keywords <code>u_steps</code> and <code>v_steps</code> are each followed
by integer values which tell how many rows and columns of triangles are the
minimum to use to create the surface, both default to 0. The maximum number of individual pieces
of the patch that are tested by POV-Ray can be calculated from the following:
<em>pieces = 2^u_steps * 2^v_steps</em>.</p>
<p>This means that you really should keep <code>u_steps</code> and <code>
v_steps</code> under 4. Most patches look just fine with <code>u_steps
3</code> and <code>v_steps 3</code>, which translates to 64 sub-patches (128
smooth triangles).</p>
<p>As POV-Ray processes the Bezier patch it makes a test of the current piece
of the patch to see if it is flat enough to just pretend it is a rectangle.
The statement that controls this test is specified with the <code>
flatness</code> keyword followed by a float. Typical flatness values range
from 0 to 1 (the lower the slower). The default if none is specified is
0.0.</p>
<p>If the value for flatness is 0 POV-Ray will always subdivide the patch to
the extend specified by <code>u_steps</code> and <code>v_steps</code>. If
flatness is greater than 0 then every time the patch is split, POV-Ray will
check to see if there is any need to split further.</p>
<p>There are both advantages and disadvantages to using a non-zero flatness.
The advantages include:</p>
<p>- If the patch is not very curved, then this will be detected and
POV-Ray will not waste a lot of time looking at the wrong pieces.</p>
<p>- If the patch is only highly curved in a couple of places, POV-Ray will keep
subdividing there and concentrate its efforts on the hard part.</p>
<p>The biggest disadvantage is that if POV-Ray stops subdividing at a
particular level on one part of the patch and at a different level on an
adjacent part of the patch there is the potential for cracking. This is
typically visible as spots within the patch where you can see through. How
bad this appears depends very highly on the angle at which you are viewing
the patch.</p>
<p>
Like triangles, the bicubic patch is not meant to be generated by hand. These
shapes should be created by a special utility. You may be able to acquire
utilities to generate these shapes from the same source from which you
obtained POV-Ray. Here is an example:</p>
<pre>
bicubic_patch {
type 0
flatness 0.01
u_steps 4
v_steps 4
<0, 0, 2>, <1, 0, 0>, <2, 0, 0>, <3, 0,-2>,
<0, 1 0>, <1, 1, 0>, <2, 1, 0>, <3, 1, 0>,
<0, 2, 0>, <1, 2, 0>, <2, 2, 0>, <3, 2, 0>,
<0, 3, 2>, <1, 3, 0>, <2, 3, 0>, <3, 3, -2>
}
</pre>
<p>The triangles in a POV-Ray <code>bicubic_patch</code> are automatically
smoothed using normal interpolation but it is up to the user (or the
user's utility program) to create control points which smoothly stitch
together groups of patches.</p></div>
<a name="r3_4_5_2_2"></a>
<div class="content-level-h5" contains="Disc" id="r3_4_5_2_2">
<h5>3.4.5.2.2 Disc</h5>
<p>Another flat, finite object available with POV-Ray is the <code>
disc</code>. The disc is infinitely thin, it has no thickness. If you want a
disc with true thickness you should use a very short cylinder. A disc shape
may be defined by:</p>
<pre>
DISC:
disc {
<Center>, <Normal>, Radius [, Hole_Radius]
[OBJECT_MODIFIERS...]
}
</pre>
<p>Disc default values:</p>
<pre>
HOLE RADIUS : 0.0
</pre>
<p>The vector <em><code><Center></code></em> defines the x, y, z
coordinates of the center of the disc. The <em><code>
<Normal></code></em> vector describes its orientation by describing its
surface normal vector. This is followed by a float specifying the <em> <code>
Radius</code></em>. This may be optionally followed by another float
specifying the radius of a hole to be cut from the center of the disc.</p>
<p class="Note"><strong>Note:</strong> The inside of a disc is the inside of the plane that contains
the disc. Also note that it is not constrained by the radius of the disc.</p></div>
<a name="r3_4_5_2_3"></a>
<div class="content-level-h5" contains="Mesh" id="r3_4_5_2_3">
<h5>3.4.5.2.3 Mesh</h5>
<p>The <code>mesh</code> object can be used to efficiently store large
numbers of triangles. Its syntax is:</p>
<pre>
MESH:
mesh {
MESH_TRIANGLE...
[MESH_MODIFIER...]
}
MESH_TRIANGLE:
triangle {
<Corner_1>, <Corner_2>, <Corner_3>
[uv_vectors <uv_Corner_1>, <uv_Corner_2>, <uv_Corner_3>]
[MESH_TEXTURE]
} |
smooth_triangle {
<Corner_1>, <Normal_1>,
<Corner_2>, <Normal_2>,
<Corner_3>, <Normal_3>
[uv_vectors <uv_Corner_1>, <uv_Corner_2>, <uv_Corner_3>]
[MESH_TEXTURE]
}
MESH_TEXTURE:
texture { TEXTURE_IDENTIFIER }
texture_list {
TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER
}
MESH_MODIFIER:
inside_vector <direction> | hierarchy [ Boolean ] |
OBJECT_MODIFIER
</pre>
<p>Mesh default values:</p>
<pre>
hierarchy : on
</pre>
<p>Any number of <code>triangle</code> and/or <code>smooth_triangle</code>
statements can be used and each of those triangles can be individually
textured by assigning a texture identifier to it. The texture has to be
declared before the mesh is parsed. It is not possible to use texture
definitions inside the triangle or smooth triangle statements. This is a
restriction that is necessary for an efficient storage of the assigned
textures. See <a href="r3_4.html#r3_4_6_8">Triangle and Smooth Triangle</a> for more information on triangles.</p>
<p>The <code>mesh</code> object can support <code>uv_mapping</code>. For this, per triangle the keyword
<code>uv_vectors</code> has to be given, together with three 2D uv-vectors. Each vector specifies a location
in the xy-plane from which the texture has to be mapped to the matching points of the triangle.
Also see the section <a href="r3_4.html#r3_4_6_7">uv_mapping</a>.</p>
<p>The mesh's components are internally bounded by a bounding box hierarchy
to speed up intersection testing. The bounding hierarchy can be turned off
with the <code>hierarchy off</code> keyword. This should only be done if
memory is short or the mesh consists of only a few triangles. The default is
<code>hierarchy on</code>.</p>
<p>Copies of a mesh object refer to the same triangle data and thus consume
very little memory. You can easily trace a hundred copies of a 10000 triangle
mesh without running out of memory (assuming the first mesh fits into
memory). The mesh object has two advantages over a union of triangles: it
needs less memory and it is transformed faster. The memory requirements are
reduced by efficiently storing the triangles vertices and normals. The
parsing time for transformed meshes is reduced because only the mesh object
has to be transformed and not every single triangle as it is necessary for
unions.</p>
<p>The mesh object can currently only include triangle and smooth triangle
components. That restriction may change, allowing polygonal components, at
some point in the future.</p>
</div>
<a name="r3_4_5_2_3_1"></a>
<div class="content-level-h6" contains="Solid Mesh" id="r3_4_5_2_3_1">
<h6>3.4.5.2.3.1 Solid Mesh</h6>
<p>The triangle mesh objects <code>mesh</code> (and <code>mesh2</code>) can be used in CSG objects such as difference and intersect. Adding the <code>inside_vector</code> they do have a defined <em>inside</em>. This will only work for well-behaved meshes, which are completely closed volumes. If meshes have any holes in them, this might work, but the results are not guaranteed.</p>
<p>To determine if a point is inside a triangle mesh, POV-Ray shoots a ray from the point in some arbitrary direction. If this vector intersects an odd number of triangles, the point is inside the mesh. If it intersects an even number of triangles, the point is outside of the mesh. You can specify the direction of this vector. For example, to use <code>+z</code> as the direction, you would add the following line to the triangle mesh description (following all other mesh data, but before the object modifiers).</p>
<pre>
inside_vector <0, 0, 1>
</pre>
<p>This change does not have any effect on unions of triangles, these will still be always hollow.</p></div>
<a name="r3_4_5_2_4"></a>
<div class="content-level-h5" contains="Mesh2" id="r3_4_5_2_4">
<h5>3.4.5.2.4 Mesh2</h5>
<p>The new mesh syntax is designed for use in conversion from other file formats.</p>
<pre>
MESH2 :
mesh2{
VECTORS...
LISTS... |
INDICES... |
MESH_MODIFIERS
}
VECTORS :
vertex_vectors {
number_of_vertices,
<vertex1>, <vertex2>, ...
}|
normal_vectors {
number_of_normals,
<normal1>, <normal2>, ...
}|
uv_vectors {
number_of_uv_vectors,
<uv_vect1>, <uv_vect2>, ...
}
LISTS :
texture_list {
number_of_textures,
texture { Texture1 },
texture { Texture2 }, ...
}|
INDICES :
face_indices {
number_of_faces,
<index_a, index_b, index_c> [,texture_index [,
texture_index, texture_index]],
<index_d, index_e, index_f> [,texture_index [,
texture_index, texture_index]],
...
}|
normal_indices {
number_of_faces,
<index_a, index_b, index_c>,
<index_d, index_e, index_f>,
...
}|
uv_indices {
number_of_faces,
<index_a, index_b, index_c>,
<index_d, index_e, index_f>,
...
}
MESH_MODIFIER :
inside_vector <direction> | OBJECT_MODIFIERS
</pre>
<p>The <code>mesh2</code> object definition <em>MUST</em> be specified in the following order:</p>
<ul>
<li>VECTORS</li>
<li>LISTS</li>
<li>INDICES</li>
</ul>
<p>The <code>normal_vectors</code>, <code>uv_vectors</code>, and <code>texture_list</code> sections are optional.
If the number of normals equals the number of vertices then the normal_indices section is optional and the indexes from the <code>face_indices</code> section are used instead. Likewise for the <code>uv_indices</code> section.</p>
<p class="Note"><strong>Note:</strong> The <code>texture_list</code> section is optional <em>only</em> if <code>face_indices</code> doesn't contain any texture index values.</p>
<p>For example:</p>
<pre>
face_indices {
number_of_faces,
<index_a, index_b, index_c>,
<index_d, index_e, index_f>,
...
}
</pre>
<p class="Note"><strong>Note:</strong> The numbers of <code>uv_indices</code> must equal number of faces.</p>
<p>The indexes are <em>zero based</em>, so the first item in each list has an index of zero.</p>
</div>
<a name="r3_4_5_2_4_1"></a>
<div class="content-level-h6" contains="Smooth and Flat triangles in the same mesh" id="r3_4_5_2_4_1">
<h6>3.4.5.2.4.1 Smooth and Flat triangles in the same mesh</h6>
<p>You can specify both flat and smooth triangles in the same mesh. To do this, specify
the smooth triangles first in the <code>face_indices</code>
section, followed by the flat triangles. Then, specify normal indices (in the
<code>normal_indices</code> section) for only the
smooth triangles. Any remaining triangles that do not have normal indices associated with
them will be assumed to be flat triangles.</p>
</div>
<a name="r3_4_5_2_4_2"></a>
<div class="content-level-h6" contains="Mesh Triangle Textures" id="r3_4_5_2_4_2">
<h6>3.4.5.2.4.2 Mesh Triangle Textures</h6>
<p>To specify a texture for an individual mesh triangle, specify a single integer texture
index following the face-index vector for that triangle.</p>
<p>To specify three textures for vertex-texture interpolation, specify three integer
texture indices (separated by commas) following the face-index vector for that triangle.</p>
<p>Vertex-texture interpolation and textures for an individual triangle can be mixed in the same mesh.</p></div>
<a name="r3_4_5_2_5"></a>
<div class="content-level-h5" contains="Polygon" id="r3_4_5_2_5">
<h5>3.4.5.2.5 Polygon</h5>
<p>The <code>polygon</code> object is useful for creating rectangles, squares
and other planar shapes with more than three edges. Their syntax is:</p>
<pre>
POLYGON:
polygon {
Number_Of_Points, <Point_1> <Point_2>... <Point_n>
[OBJECT_MODIFIER...]
}
</pre>
<p>The float <em><code>Number_Of_Points</code></em> tells how many points are
used to define the polygon. The points <em><code><Point_1></code></em>
through <em><code><Point_n></code></em> describe the polygon or
polygons. A polygon can contain any number of sub-polygons, either
overlapping or not. In places where an even number of polygons overlaps a
hole appears. When you repeat the first point of a sub-polygon, it closes it
and starts a new sub-polygon's point sequence. This means that all points
of a sub-polygon are different.</p>
<p>
If the last sub-polygon is not closed a warning is issued and the program
automatically closes the polygon. This is useful because polygons imported
from other programs may not be closed, i.e. their first and last point are
not the same.</p>
<p>
All points of a polygon are three-dimensional vectors that have to lay on
the same plane. If this is not the case an error occurs. It is common to use
two-dimensional vectors to describe the polygon. POV-Ray assumes that the z
value is zero in this case.</p>
<p>
A square polygon that matches the default planar image map is simply:</p>
<pre>
polygon {
4,
<0, 0>, <0, 1>, <1, 1>, <1, 0>
texture {
finish { ambient 1 diffuse 0 }
pigment { image_map { gif "test.gif" } }
}
//scale and rotate as needed here
}
</pre>
<p>The sub-polygon feature can be used to generate complex shapes like the
letter "P", where a hole is cut into another polygon:</p>
<pre>
#declare P = polygon {
12,
<0, 0>, <0, 6>, <4, 6>, <4, 3>, <1, 3>, <1,0>, <0, 0>,
<1, 4>, <1, 5>, <3, 5>, <3, 4>, <1, 4>
}
</pre>
<p>The first sub-polygon (on the first line) describes the outer shape of the
letter "P". The second sub-polygon (on the second line) describes
the rectangular hole that is cut in the top of the letter "P". Both
rectangles are closed, i.e. their first and last points are the same.</p>
<p>
The feature of cutting holes into a polygon is based on the polygon
inside/outside test used. A point is considered to be inside a polygon if a
straight line drawn from this point in an arbitrary direction crosses an odd
number of edges, this is known as <em>Jordan's curve theorem</em>.</p>
<p>
Another very complex example showing one large triangle with three small
holes and three separate, small triangles is given below:</p>
<pre>
polygon {
28,
<0, 0> <1, 0> <0, 1> <0, 0> // large outer triangle
<.3, .7> <.4, .7> <.3, .8> <.3, .7> // small outer triangle #1
<.5, .5> <.6, .5> <.5, .6> <.5, .5> // small outer triangle #2
<.7, .3> <.8, .3> <.7, .4> <.7, .3> // small outer triangle #3
<.5, .2> <.6, .2> <.5, .3> <.5, .2> // inner triangle #1
<.2, .5> <.3, .5> <.2, .6> <.2, .5> // inner triangle #2
<.1, .1> <.2, .1> <.1, .2> <.1, .1> // inner triangle #3
}
</pre></div>
<a name="r3_4_5_2_6"></a>
<div class="content-level-h5" contains="Triangle" id="r3_4_5_2_6">
<h5>3.4.5.2.6 Triangle</h5>
<p>The <code>triangle</code> primitive is available in order to make more
complex objects than the built-in shapes will permit. Triangles are usually
not created by hand but are converted from other files or generated by
utilities. A triangle is defined by</p>
<pre>
TRIANGLE:
triangle {
<Corner_1>, <Corner_2>, <Corner_3>
[OBJECT_MODIFIER...]
}
</pre>
<p>where <em><code><Corner_n></code></em> is a vector defining the x,
y, z coordinates of each corner of the triangle.</p>
<p>
Because triangles are perfectly flat surfaces it would require extremely
large numbers of very small triangles to approximate a smooth, curved
surface. However much of our perception of smooth surfaces is dependent upon
the way light and shading is done. By artificially modifying the surface
normals we can simulate a smooth surface and hide the sharp-edged seams
between individual triangles.</p></div>
<a name="r3_4_5_2_7"></a>
<div class="content-level-h5" contains="Smooth Triangle" id="r3_4_5_2_7">
<h5>3.4.5.2.7 Smooth Triangle</h5>
<p>The <code>smooth_triangle</code> primitive is used for just such purposes.
The smooth triangles use a formula called Phong normal interpolation to
calculate the surface normal for any point on the triangle based on normal
vectors which you define for the three corners. This makes the triangle
appear to be a smooth curved surface. A smooth triangle is defined by</p>
<pre>
SMOOTH_TRIANGLE:
smooth_triangle {
<Corner_1>, <Normal_1>, <Corner_2>,
<Normal_2>, <Corner_3>, <Normal_3>
[OBJECT_MODIFIER...]
}
</pre>
<p>where the corners are defined as in regular triangles and <em><code>
<Normal_n></code></em> is a vector describing the direction of the
surface normal at each corner.</p>
<p>
These normal vectors are prohibitively difficult to compute by hand.
Therefore smooth triangles are almost always generated by utility programs.
To achieve smooth results, any triangles which share a common vertex should
have the same normal vector at that vertex. Generally the smoothed normal
should be the average of all the actual normals of the triangles which share
that point.</p>
<p>
The <code>mesh</code> object is a way to combine many <code>triangle</code>
and <code>smooth_triangle</code> objects together in a very efficient way.
See <a href="r3_4.html#r3_4_5_2_3">Mesh</a> for details.</p></div>
<a name="r3_4_5_3"></a>
<div class="content-level-h4" contains="Infinite Solid Primitives" id="r3_4_5_3">
<h4>3.4.5.3 Infinite Solid Primitives</h4>
<p>There are six polynomial primitive shapes that are possibly infinite and
do not respond to automatic bounding. They are <a href="r3_4.html#r3_4_5_3_1">plane</a>, <a href="r3_4.html#r3_4_5_3_3">cubic</a>, <a href="r3_4.html#r3_4_5_3_2">poly</a>, <a href="r3_4.html#r3_4_5_3_4">quartic</a>, <a href="r3_4.html#r3_4_5_3_5">polynomial</a>,
and <a href="r3_4.html#r3_4_5_3_6">quadric</a>. They do have a well defined inside and may be used in CSG and
inside a <code>clipped_by</code> statement. As with all shapes they can be
translated, rotated and scaled.</p></div>
<a name="r3_4_5_3_1"></a>
<div class="content-level-h5" contains="Plane" id="r3_4_5_3_1">
<h5>3.4.5.3.1 Plane</h5>
<p>The <code>plane</code> primitive is a simple way to define an infinite
flat surface. The plane is not a thin boundary or can be compared to a sheet
of paper. A plane is a solid object of infinite size that divides POV-space
in two parts, inside and outside the plane. The plane is specified as follows:</p>
<pre>
PLANE:
plane {
<Normal>, Distance
[OBJECT_MODIFIERS...]
}
</pre>
<p>The <em><code><Normal></code></em> vector defines the surface normal
of the plane. A surface normal is a vector which points up from the surface
at a 90 degree angle. This is followed by a float value that gives the
distance along the normal that the plane is from the origin (that is only
true if the normal vector has unit length; see below). For example:</p>
<pre>
plane { <0, 1, 0>, 4 }
</pre>
<p>This is a plane where straight up is defined in the positive y-direction.
The plane is 4 units in that direction away from the origin. Because most
planes are defined with surface normals in the direction of an axis you will
often see planes defined using the <code>x</code>, <code>y</code> or <code>
z</code> built-in vector identifiers. The example above could be specified
as:</p>
<pre>
plane { y, 4 }
</pre>
<p>The plane extends infinitely in the x- and z-directions. It effectively
divides the world into two pieces. By definition the normal vector points to
the outside of the plane while any points away from the vector are defined as
inside. This inside/outside distinction is important when using planes in CSG
and <code>clipped_by</code>. It is also important when using fog or
atmospheric media. If you place a camera on the "inside" half of
the world, then the fog or media will not appear. Such issues arise in any
solid object but it is more common with planes. Users typically know when
they have accidentally placed a camera inside a sphere or box but
"inside a plane" is an unusual concept. In general you can reverse the
inside/outside properties of an object by adding the object modifier <code>
inverse</code>. See <a href="r3_4.html#r3_4_5_5_5">Inverse</a> and <a href="r3_4.html#r3_4_8_1_2">Empty and Solid Objects</a> for details.</p>
<p>
A plane is called a <em>polynomial</em> shape because it is defined by a
first order polynomial equation. Given a plane:</p>
<pre>
plane { <A, B, C>, D }
</pre>
<p>it can be represented by the equation <em><code>A*x + B*y + C*z - D*sqrt(A^2 + B^2 + C^2) = 0</code></em>.</p>
<p>
Therefore our example <code>plane{y,4}</code> is actually the polynomial
equation y=4. You can think of this as a set of all x, y, z points where all
have y values equal to 4, regardless of the x or z values.</p>
<p>
This equation is a first order polynomial because each term contains only
single powers of x, y or z. A second order equation has terms like x^2, y^2,
z^2, xy, xz and yz. Another name for a 2nd order equation is a quadric
equation. Third order polys are called cubics. A 4th order equation is a
quartic. Such shapes are described in the sections below.</p></div>
<a name="r3_4_5_3_2"></a>
<div class="content-level-h5" contains="Poly" id="r3_4_5_3_2">
<h5>3.4.5.3.2 Poly</h5>
<p>Higher order polynomial surfaces may be defined by the use of a <code>
poly</code> shape. The syntax is</p>
<pre>
POLY:
poly {
Order, <A1, A2, A3,... An>
[POLY_MODIFIERS...]
}
POLY_MODIFIERS:
sturm | OBJECT_MODIFIER
</pre>
<p>Poly default values:</p>
<pre>
sturm : off
</pre>
<p>where <em><code>Order</code></em> is an integer number from 2 to 35
inclusively that specifies the order of the equation. <em><code>A1, A2, ...
An</code></em> are float values for the coefficients of the equation. There
are <em><code>n</code></em> such terms where <em><code>n = ((Order+1)*(Order+2)*(Order+3))/6.</code></em></p></div>
<a name="r3_4_5_3_3"></a>
<div class="content-level-h5" contains="Cubic" id="r3_4_5_3_3">
<h5>3.4.5.3.3 Cubic</h5>
<p>The <code>cubic</code> object
is an alternate way to specify 3rd order polys. Its syntax is:</p>
<pre>
CUBIC:
cubic {
<A1, A2, A3,... A20>
[POLY_MODIFIERS...]
}
</pre></div>
<a name="r3_4_5_3_4"></a>
<div class="content-level-h5" contains="Quartic" id="r3_4_5_3_4">
<h5>3.4.5.3.4 Quartic</h5>
<p>Also 4th order equations may be specified with the <code>quartic</code>
object. Its syntax is:</p>
<pre>
QUARTIC:
quartic {
<A1, A2, A3,... A35>
[POLY_MODIFIERS...]
}
</pre></div>
<a name="r3_4_5_3_5"></a>
<div class="content-level-h5" contains="Polynomial" id="r3_4_5_3_5">
<h5>3.4.5.3.5 Polynomial</h5>
<p>Poly, cubic and quartics are just like quadrics in that you do not have
to understand one to use one. The file <code>shapesq.inc</code> has
plenty of pre-defined quartics for you to play with.</p>
<p>For convenience an alternate syntax is available as <code>polynomial</code>. It doesn't care about the order of the coefficients, as long as you do not define them more than once, otherwise only the value of the last definition is kept. Additionally the default with all coefficients is 0, which can be especially useful typing shortcut.</p>
<p>See the <a href="t2_3.html#t2_3_3_4_3">tutorial</a> section for more examples of the simplified syntax.</p>
<pre>
POLYNOMIAL:
polynomial {
Order, [COEFFICIENTS...]
[POLY_MODIFIERS...]
}
COEFFICIENTS:
xyz(<x_power>,<y_power>,<z_power>):<value>[,]
POLY_MODIFIERS:
sturm | OBJECT_MODIFIER
</pre>
<p>Same as the torus above, but with the polynomial syntax:</p>
<pre>
// Torus having major radius sqrt(40), minor radius sqrt(12)
polynomial { 4,
xyz(4,0,0):1,
xyz(2,2,0):2,
xyz(2,0,2):2,
xyz(2,0,0):-104,
xyz(0,4,0):1,
xyz(0,2,2):2,
xyz(0,2,0):56,
xyz(0,0,4):1,
xyz(0,0,2):-104,
xyz(0,0,0):784
sturm
}
</pre>
<p>The following table shows which polynomial terms correspond to which x,y,z
factors for the orders 2 to 7. Remember <code>cubic</code> is actually a 3rd order polynomial and
<code>quartic</code> is 4th order.</p>
<table class="matte" SUMMARY="Cubic and quartic polynomial terms" width="700px">
<tr>
<!-- That this is only 99% is intentional! [trf] -->
<th width="5%"> </th>
<th width="5%">2<sup>nd</sup></th>
<th width="6%">3<sup>rd</sup></th>
<th width="7%">4<sup>th</sup></th>
<th width="8%">5<sup>th</sup></th>
<th width="9%">6<sup>th</sup></th>
<th width="10%">7<sup>th</sup></th>
<th width="6%"> </th>
<th width="8%">5<sup>th</sup></th>
<th width="9%">6<sup>th</sup></th>
<th width="10%">7<sup>th</sup></th>
<th width="6%"> </th>
<th width="5%">6<sup>th</sup></th>
<th width="5%">7<sup>th</sup></th>
</tr>
<tr>
<td>A<sub>1</sub></td>
<td>x<sup>2</sup></td>
<td>x<sup>3</sup></td>
<td>x<sup>4</sup></td>
<td>x<sup>5</sup></td>
<td>x<sup>6</sup></td>
<td>x<sup>7</sup></td>
<td>A<sub>41</sub></td>
<td>y<sup>3</sup></td>
<td>xy<sup>3</sup></td>
<td>x<sup>2</sup>y<sup>3</sup></td>
<td>A<sub>81</sub></td>
<td>z<sup>3</sup></td>
<td>xz<sup>3</sup></td>
</tr>
<tr>
<td>A<sub>2</sub></td>
<td>xy</td>
<td>x<sup>2</sup>y</td>
<td>x<sup>3</sup>y</td>
<td>x<sup>4</sup>y</td>
<td>x<sup>5</sup>y</td>
<td>x<sup>6</sup>y</td>
<td>A<sub>42</sub></td>
<td>y<sup>2</sup>z<sup>3</sup></td>
<td>xy<sup>2</sup>z<sup>3</sup></td>
<td>x<sup>2</sup>y<sup>2</sup>z<sup>3</sup></td>
<td>A<sub>82</sub></td>
<td>z<sup>2</sup></td>
<td>xz<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>3</sub></td>
<td>xz</td>
<td>x<sup>2</sup>z</td>
<td>x<sup>3</sup>z</td>
<td>x<sup>4</sup>z</td>
<td>x<sup>5</sup>z</td>
<td>x<sup>6</sup>z</td>
<td>A<sub>43</sub></td>
<td>y<sup>2</sup>z<sup>2</sup></td>
<td>xy<sup>2</sup>z<sup>2</sup></td>
<td>x<sup>2</sup>y<sup>2</sup>z<sup>2</sup></td>
<td>A<sub>83</sub></td>
<td>z</td>
<td>xz</td>
</tr>
<tr>
<td>A<sub>4</sub></td>
<td>x</td>
<td>x<sup>2</sup></td>
<td>x<sup>3</sup></td>
<td>x<sup>4</sup></td>
<td>x<sup>5</sup></td>
<td>x<sup>6</sup></td>
<td>A<sub>44</sub></td>
<td>y<sup>2</sup>z</td>
<td>xy<sup>2</sup>z</td>
<td>x<sup>2</sup>y<sup>2</sup>z</td>
<td>A<sub>84</sub></td>
<td>1</td>
<td>x</td>
</tr>
<tr>
<td>A<sub>5</sub></td>
<td>y<sup>2</sup></td>
<td>xy<sup>2</sup></td>
<td>x<sup>2</sup>y<sup>2</sup></td>
<td>x<sup>3</sup>y<sup>2</sup></td>
<td>x<sup>4</sup>y<sup>2</sup></td>
<td>x<sup>5</sup>y<sup>2</sup></td>
<td>A<sub>45</sub></td>
<td>y<sup>2</sup></td>
<td>xy<sup>2</sup></td>
<td>x<sup>2</sup>y<sup>2</sup></td>
<td>A<sub>85</sub></td>
<td> </td>
<td>y<sup>7</sup></td>
</tr>
<tr>
<td>A<sub>6</sub></td>
<td>yz</td>
<td>xyz</td>
<td>x<sup>2</sup>yz</td>
<td>x<sup>3</sup>yz</td>
<td>x<sup>4</sup>yz</td>
<td>x<sup>5</sup>yz</td>
<td>A<sub>46</sub></td>
<td>yz<sup>4</sup></td>
<td>xyz<sup>4</sup></td>
<td>x<sup>2</sup>yz<sup>4</sup></td>
<td>A<sub>86</sub></td>
<td> </td>
<td>y<sup>6</sup>z</td>
</tr>
<tr>
<td>A<sub>7</sub></td>
<td>y</td>
<td>xy</td>
<td>x<sup>2</sup>y</td>
<td>x<sup>3</sup>y</td>
<td>x<sup>4</sup>y</td>
<td>x<sup>5</sup>y</td>
<td>A<sub>47</sub></td>
<td>yz<sup>3</sup></td>
<td>xyz<sup>3</sup></td>
<td>x<sup>2</sup>yz<sup>3</sup></td>
<td>A<sub>87</sub></td>
<td> </td>
<td>y<sup>6</sup></td>
</tr>
<tr>
<td>A<sub>8</sub></td>
<td>z<sup>2</sup></td>
<td>xz<sup>2</sup></td>
<td>x<sup>2</sup>z<sup>2</sup></td>
<td>x<sup>3</sup>z<sup>2</sup></td>
<td>x<sup>4</sup>z<sup>2</sup></td>
<td>x<sup>5</sup>z<sup>2</sup></td>
<td>A<sub>48</sub></td>
<td>yz<sup>2</sup></td>
<td>xyz<sup>2</sup></td>
<td>x<sup>2</sup>yz<sup>2</sup></td>
<td>A<sub>88</sub></td>
<td> </td>
<td>y<sup>5</sup>z<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>9</sub></td>
<td>z</td>
<td>xz</td>
<td>x<sup>2</sup>z</td>
<td>x<sup>3</sup>z</td>
<td>x<sup>4</sup>z</td>
<td>x<sup>5</sup>z</td>
<td>A<sub>49</sub></td>
<td>yz</td>
<td>xyz</td>
<td>x<sup>2</sup>yz</td>
<td>A<sub>89</sub></td>
<td> </td>
<td>y<sup>5</sup>z</td>
</tr>
<tr>
<td>A<sub>10</sub></td>
<td>1</td>
<td>x</td>
<td>x<sup>2</sup></td>
<td>x<sup>3</sup></td>
<td>x<sup>4</sup></td>
<td>x<sup>5</sup></td>
<td>A<sub>50</sub></td>
<td>y</td>
<td>xy</td>
<td>x<sup>2</sup>y</td>
<td>A<sub>90</sub></td>
<td> </td>
<td>y<sup>5</sup></td>
</tr>
<tr>
<td>A<sub>11</sub></td>
<td> </td>
<td>y<sup>3</sup></td>
<td>xy<sup>3</sup></td>
<td>x<sup>2</sup>y<sup>3</sup></td>
<td>x<sup>3</sup>y<sup>3</sup></td>
<td>x<sup>4</sup>y<sup>3</sup></td>
<td>A<sub>51</sub></td>
<td>z<sup>5</sup></td>
<td>xz<sup>5</sup></td>
<td>x<sup>2</sup>z<sup>5</sup></td>
<td>A<sub>91</sub></td>
<td> </td>
<td>y<sup>4</sup>z<sup>3</sup></td>
</tr>
<tr>
<td>A<sub>12</sub></td>
<td> </td>
<td>y<sup>2</sup>z</td>
<td>xy<sup>2</sup>z</td>
<td>x<sup>2</sup>y<sup>2</sup>z</td>
<td>x<sup>3</sup>y<sup>2</sup>z</td>
<td>x<sup>4</sup>y<sup>2</sup>z</td>
<td>A<sub>52</sub></td>
<td>z<sup>4</sup></td>
<td>xz<sup>4</sup></td>
<td>x<sup>2</sup>z<sup>4</sup></td>
<td>A<sub>92</sub></td>
<td> </td>
<td>y<sup>4</sup>z<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>13</sub></td>
<td> </td>
<td>y<sup>2</sup></td>
<td>xy<sup>2</sup></td>
<td>x<sup>2</sup>y<sup>2</sup></td>
<td>x<sup>3</sup>y<sup>2</sup></td>
<td>x<sup>4</sup>y<sup>2</sup></td>
<td>A<sub>53</sub></td>
<td>z<sup>3</sup></td>
<td>xz<sup>3</sup></td>
<td>x<sup>2</sup>z<sup>3</sup></td>
<td>A<sub>93</sub></td>
<td> </td>
<td>y<sup>4</sup>z</td>
</tr>
<tr>
<td>A<sub>14</sub></td>
<td> </td>
<td>yz<sup>2</sup></td>
<td>xyz<sup>2</sup></td>
<td>x<sup>2</sup>yz<sup>2</sup></td>
<td>x<sup>3</sup>yz<sup>2</sup></td>
<td>x<sup>4</sup>yz<sup>2</sup></td>
<td>A<sub>54</sub></td>
<td>z<sup>2</sup></td>
<td>xz<sup>2</sup></td>
<td>x<sup>2</sup>z<sup>2</sup></td>
<td>A<sub>94</sub></td>
<td> </td>
<td>y<sup>4</sup></td>
</tr>
<tr>
<td>A<sub>15</sub></td>
<td> </td>
<td>yz</td>
<td>xyz</td>
<td>x<sup>2</sup>yz</td>
<td>x<sup>3</sup>yz</td>
<td>x<sup>4</sup>yz</td>
<td>A<sub>55</sub></td>
<td>z</td>
<td>xz</td>
<td>x<sup>2</sup>z</td>
<td>A<sub>95</sub></td>
<td> </td>
<td>y<sup>3</sup>z<sup>4</sup></td>
</tr>
<tr>
<td>A<sub>16</sub></td>
<td> </td>
<td>y</td>
<td>xy</td>
<td>x<sup>2</sup>y</td>
<td>x<sup>3</sup>y</td>
<td>x<sup>4</sup>y</td>
<td>A<sub>56</sub></td>
<td>1</td>
<td>x</td>
<td>x<sup>2</sup></td>
<td>A<sub>96</sub></td>
<td> </td>
<td>y<sup>3</sup>z<sup>3</sup></td>
</tr>
<tr>
<td>A<sub>17</sub></td>
<td> </td>
<td>z<sup>3</sup></td>
<td>xz<sup>3</sup></td>
<td>x<sup>2</sup>z<sup>3</sup></td>
<td>x<sup>3</sup>z<sup>3</sup></td>
<td>x<sup>4</sup>z<sup>3</sup></td>
<td>A<sub>57</sub></td>
<td> </td>
<td>y<sup>6</sup></td>
<td>xy<sup>6</sup></td>
<td>A<sub>97</sub></td>
<td> </td>
<td>y<sup>3</sup>z<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>18</sub></td>
<td> </td>
<td>z<sup>2</sup></td>
<td>xz<sup>2</sup></td>
<td>x<sup>2</sup>z<sup>2</sup></td>
<td>x<sup>3</sup>z<sup>2</sup></td>
<td>x<sup>4</sup>z<sup>2</sup></td>
<td>A<sub>58</sub></td>
<td> </td>
<td>y<sup>5</sup>z</td>
<td>xy<sup>5</sup>z</td>
<td>A<sub>98</sub></td>
<td> </td>
<td>y<sup>3</sup>z</td>
</tr>
<tr>
<td>A<sub>19</sub></td>
<td> </td>
<td>z</td>
<td>xz</td>
<td>x<sup>2</sup>z</td>
<td>x<sup>3</sup>z</td>
<td>x<sup>4</sup>z</td>
<td>A<sub>59</sub></td>
<td> </td>
<td>y<sup>5</sup></td>
<td>xy<sup>5</sup></td>
<td>A<sub>99</sub></td>
<td> </td>
<td>y<sup>3</sup></td>
</tr>
<tr>
<td>A<sub>20</sub></td>
<td> </td>
<td>1</td>
<td>x</td>
<td>x<sup>2</sup></td>
<td>x<sup>3</sup></td>
<td>x<sup>4</sup></td>
<td>A<sub>60</sub></td>
<td> </td>
<td>y<sup>4</sup>z<sup>2</sup></td>
<td>xy<sup>4</sup>z<sup>2</sup></td>
<td>A<sub>100</sub></td>
<td> </td>
<td>y<sup>2</sup>z<sup>5</sup></td>
</tr>
<tr>
<td>A<sub>21</sub></td>
<td> </td>
<td> </td>
<td>y<sup>4</sup></td>
<td>xy<sup>4</sup></td>
<td>x<sup>2</sup>y<sup>4</sup></td>
<td>x<sup>3</sup>y<sup>4</sup></td>
<td>A<sub>61</sub></td>
<td> </td>
<td>y<sup>4</sup>z</td>
<td>xy<sup>4</sup>z</td>
<td>A<sub>101</sub></td>
<td> </td>
<td>y<sup>2</sup>z<sup>4</sup></td>
</tr>
<tr>
<td>A<sub>22</sub></td>
<td> </td>
<td> </td>
<td>y<sup>3</sup>z</td>
<td>xy<sup>3</sup>z</td>
<td>x<sup>2</sup>y<sup>3</sup>z</td>
<td>x<sup>3</sup>y<sup>3</sup>z</td>
<td>A<sub>62</sub></td>
<td> </td>
<td>y<sup>4</sup></td>
<td>xy<sup>4</sup></td>
<td>A<sub>102</sub></td>
<td> </td>
<td>y<sup>2</sup>z<sup>3</sup></td>
</tr>
<tr>
<td>A<sub>23</sub></td>
<td> </td>
<td> </td>
<td>y<sup>3</sup></td>
<td>xy<sup>3</sup></td>
<td>x<sup>2</sup>y<sup>3</sup></td>
<td>x<sup>3</sup>y<sup>3</sup></td>
<td>A<sub>63</sub></td>
<td> </td>
<td>y<sup>3</sup>z<sup>3</sup></td>
<td>xy<sup>3</sup>z<sup>3</sup></td>
<td>A<sub>103</sub></td>
<td> </td>
<td>y<sup>2</sup>z<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>24</sub></td>
<td> </td>
<td> </td>
<td>y<sup>2</sup>z<sup>2</sup></td>
<td>xy<sup>2</sup>z<sup>2</sup></td>
<td>x<sup>2</sup>y<sup>2</sup>z<sup>2</sup></td>
<td>x<sup>3</sup>y<sup>2</sup>z<sup>2</sup></td>
<td>A<sub>64</sub></td>
<td> </td>
<td>y<sup>3</sup>z<sup>2</sup></td>
<td>xy<sup>3</sup>z<sup>2</sup></td>
<td>A<sub>104</sub></td>
<td> </td>
<td>y<sup>2</sup>z</td>
</tr>
<tr>
<td>A<sub>25</sub></td>
<td> </td>
<td> </td>
<td>y<sup>2</sup>z</td>
<td>xy<sup>2</sup>z</td>
<td>x<sup>2</sup>y<sup>2</sup>z</td>
<td>x<sup>3</sup>y<sup>2</sup>z</td>
<td>A<sub>65</sub></td>
<td> </td>
<td>y<sup>3</sup>z</td>
<td>xy<sup>3</sup>z</td>
<td>A<sub>105</sub></td>
<td> </td>
<td>y<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>26</sub></td>
<td> </td>
<td> </td>
<td>y<sup>2</sup></td>
<td>xy<sup>2</sup></td>
<td>x<sup>2</sup>y<sup>2</sup></td>
<td>x<sup>3</sup>y<sup>2</sup></td>
<td>A<sub>66</sub></td>
<td> </td>
<td>y<sup>3</sup></td>
<td>xy<sup>3</sup></td>
<td>A<sub>106</sub></td>
<td> </td>
<td>yz<sup>6</sup></td>
</tr>
<tr>
<td>A<sub>27</sub></td>
<td> </td>
<td> </td>
<td>yz<sup>3</sup></td>
<td>xyz<sup>3</sup></td>
<td>x<sup>2</sup>yz<sup>3</sup></td>
<td>x<sup>3</sup>yz<sup>3</sup></td>
<td>A<sub>67</sub></td>
<td> </td>
<td>y<sup>2</sup>z<sup>4</sup></td>
<td>xy<sup>2</sup>z<sup>4</sup></td>
<td>A<sub>107</sub></td>
<td> </td>
<td>yz<sup>5</sup></td>
</tr>
<tr>
<td>A<sub>28</sub></td>
<td> </td>
<td> </td>
<td>yz<sup>2</sup></td>
<td>xyz<sup>2</sup></td>
<td>x<sup>2</sup>yz<sup>2</sup></td>
<td>x<sup>3</sup>yz<sup>2</sup></td>
<td>A<sub>68</sub></td>
<td> </td>
<td>y<sup>2</sup>z<sup>3</sup></td>
<td>xy<sup>2</sup>z<sup>3</sup></td>
<td>A<sub>108</sub></td>
<td> </td>
<td>yz<sup>4</sup></td>
</tr>
<tr>
<td>A<sub>29</sub></td>
<td> </td>
<td> </td>
<td>yz</td>
<td>xyz</td>
<td>x<sup>2</sup>yz</td>
<td>x<sup>3</sup>yz</td>
<td>A<sub>69</sub></td>
<td> </td>
<td>y<sup>2</sup>z<sup>2</sup></td>
<td>xy<sup>2</sup>z<sup>2</sup></td>
<td>A<sub>109</sub></td>
<td> </td>
<td>yz<sup>3</sup></td>
</tr>
<tr>
<td>A<sub>30</sub></td>
<td> </td>
<td> </td>
<td>y</td>
<td>xy</td>
<td>x<sup>2</sup>y</td>
<td>x<sup>3</sup>y</td>
<td>A<sub>70</sub></td>
<td> </td>
<td>y<sup>2</sup>z</td>
<td>xy<sup>2</sup>z</td>
<td>A<sub>110</sub></td>
<td> </td>
<td>yz<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>31</sub></td>
<td> </td>
<td> </td>
<td>z<sup>4</sup></td>
<td>xz<sup>4</sup></td>
<td>x<sup>2</sup>z<sup>4</sup></td>
<td>x<sup>3</sup>z<sup>4</sup></td>
<td>A<sub>71</sub></td>
<td> </td>
<td>y<sup>2</sup></td>
<td>xy<sup>2</sup></td>
<td>A<sub>111</sub></td>
<td> </td>
<td>yz</td>
</tr>
<tr>
<td>A<sub>32</sub></td>
<td> </td>
<td> </td>
<td>z<sup>3</sup></td>
<td>xz<sup>3</sup></td>
<td>x<sup>2</sup>z<sup>3</sup></td>
<td>x<sup>3</sup>z<sup>3</sup></td>
<td>A<sub>72</sub></td>
<td> </td>
<td>yz<sup>5</sup></td>
<td>xyz<sup>5</sup></td>
<td>A<sub>112</sub></td>
<td> </td>
<td>y</td>
</tr>
<tr>
<td>A<sub>33</sub></td>
<td> </td>
<td> </td>
<td>z<sup>2</sup></td>
<td>xz<sup>2</sup></td>
<td>x<sup>2</sup>z<sup>2</sup></td>
<td>x<sup>3</sup>z<sup>2</sup></td>
<td>A<sub>73</sub></td>
<td> </td>
<td>yz<sup>4</sup></td>
<td>xyz<sup>4</sup></td>
<td>A<sub>113</sub></td>
<td> </td>
<td>z<sup>7</sup></td>
</tr>
<tr>
<td>A<sub>34</sub></td>
<td> </td>
<td> </td>
<td>z</td>
<td>xz</td>
<td>x<sup>2</sup>z</td>
<td>x<sup>3</sup>z</td>
<td>A<sub>74</sub></td>
<td> </td>
<td>yz<sup>3</sup></td>
<td>xyz<sup>3</sup></td>
<td>A<sub>114</sub></td>
<td> </td>
<td>z<sup>6</sup></td>
</tr>
<tr>
<td>A<sub>35</sub></td>
<td> </td>
<td> </td>
<td>1</td>
<td>x</td>
<td>x<sup>2</sup></td>
<td>x<sup>3</sup></td>
<td>A<sub>75</sub></td>
<td> </td>
<td>yz<sup>2</sup></td>
<td>xyz<sup>2</sup></td>
<td>A<sub>115</sub></td>
<td> </td>
<td>z<sup>5</sup></td>
</tr>
<tr>
<td>A<sub>36</sub></td>
<td> </td>
<td> </td>
<td> </td>
<td>y<sup>5</sup></td>
<td>xy<sup>5</sup></td>
<td>x<sup>2</sup>y<sup>5</sup></td>
<td>A<sub>76</sub></td>
<td> </td>
<td>yz</td>
<td>xyz</td>
<td>A<sub>116</sub></td>
<td> </td>
<td>z<sup>4</sup></td>
</tr>
<tr>
<td>A<sub>37</sub></td>
<td> </td>
<td> </td>
<td> </td>
<td>y<sup>4</sup>z</td>
<td>xy<sup>4</sup>z</td>
<td>x<sup>2</sup>y<sup>4</sup>z</td>
<td>A<sub>77</sub></td>
<td> </td>
<td>y</td>
<td>xy</td>
<td>A<sub>117</sub></td>
<td> </td>
<td>z<sup>3</sup></td>
</tr>
<tr>
<td>A<sub>38</sub></td>
<td> </td>
<td> </td>
<td> </td>
<td>y<sup>4</sup></td>
<td>xy<sup>4</sup></td>
<td>x<sup>2</sup>y<sup>4</sup></td>
<td>A<sub>78</sub></td>
<td> </td>
<td>z<sup>6</sup></td>
<td>xz<sup>6</sup></td>
<td>A<sub>118</sub></td>
<td> </td>
<td>z<sup>2</sup></td>
</tr>
<tr>
<td>A<sub>39</sub></td>
<td> </td>
<td> </td>
<td> </td>
<td>y<sup>3</sup>z<sup>2</sup></td>
<td>xy<sup>3</sup>z<sup>2</sup></td>
<td>x<sup>2</sup>y<sup>3</sup>z<sup>2</sup></td>
<td>A<sub>79</sub></td>
<td> </td>
<td>z<sup>5</sup></td>
<td>xz<sup>5</sup></td>
<td>A<sub>119</sub></td>
<td> </td>
<td>z</td>
</tr>
<tr>
<td>A<sub>40</sub></td>
<td> </td>
<td> </td>
<td> </td>
<td>y<sup>3</sup>z</td>
<td>xy<sup>3</sup>z</td>
<td>x<sup>2</sup>y<sup>3</sup>z</td>
<td>A<sub>80</sub></td>
<td> </td>
<td>z<sup>4</sup></td>
<td>xz<sup>4</sup></td>
<td>A<sub>120</sub></td>
<td> </td>
<td>1</td>
</tr>
</table>
<p>Polynomial shapes can be used to describe a large class of shapes
including the torus, the lemniscate, etc. For example, to declare a quartic
surface requires that each of the coefficients (<em><code>A1 ...
A35</code></em>) be placed in order into a single long vector of 35 terms. As an example let's define a torus the hard way. A Torus can be represented by the equation: <code>x<sup>4</sup> + y<sup>4</sup> + z<sup>4</sup> + 2 x<sup>2</sup> y<sup>2</sup> + 2 x<sup>2</sup> z<sup>2</sup> + 2 y<sup>2</sup> z<sup>2</sup> - 2 (r_02 + r_12)
x<sup>2</sup> + 2 (r_02 - r_12) y<sup>2</sup> - 2 (r_02 + r_12) z<sup>2</sup> + (r_02 - r_12)<sup>2</sup> = 0</code></p>
<p>Where r_0 is the major radius of the torus, the distance from the hole of
the donut to the middle of the ring of the donut, and r_1 is the minor radius
of the torus, the distance from the middle of the ring of the donut to the
outer surface. The following object declaration is for a torus having major
radius 6.3 minor radius 3.5 (Making the maximum width just under 20).</p>
<pre>
// Torus having major radius sqrt(40), minor radius sqrt(12)
quartic {
< 1, 0, 0, 0, 2, 0, 0, 2, 0,
-104, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 1, 0, 0, 2, 0, 56, 0,
0, 0, 0, 1, 0, -104, 0, 784 >
sturm
}
</pre>
<p>
Polynomial surfaces use highly complex computations and will not always render perfectly.
If the surface is not smooth, has dropouts, or extra random pixels, try using
the optional keyword <code>sturm</code> in the definition. This will cause a
slower but more accurate calculation method to be used. Usually, but not
always, this will solve the problem. If sturm does not work, try rotating
or translating the shape by some small amount.</p>
<p>
There are really so many different polynomial shapes, we cannot even
begin to list or describe them all. We suggest you find a good reference
or text book if you want to investigate the subject further.</p></div>
<a name="r3_4_5_3_6"></a>
<div class="content-level-h5" contains="Quadric" id="r3_4_5_3_6">
<h5>3.4.5.3.6 Quadric</h5>
<p>The <code>quadric</code> object can produce shapes like paraboloids (dish
shapes) and hyperboloids (saddle or hourglass shapes). It can also produce
ellipsoids, spheres, cones, and cylinders but you should use the <code>
sphere</code>, <code>cone</code>, and <code>cylinder</code> objects built
into POV-Ray because they are faster than the quadric version.</p>
<p class="Note"><strong>Note:</strong> Do not confuse "quaDRic" with
"quaRTic". A quadric is a 2nd order polynomial while a quartic
is 4th order.</p>
<p>
Quadrics render much
faster and are less error-prone but produce less complex objects. The syntax
is:</p>
<pre>
QUADRIC:
quadric {
<A,B,C>,<D,E,F>,<G,H,I>,J
[OBJECT_MODIFIERS...]
}
</pre>
<p>Although the syntax actually will parse 3 vector expressions followed by a
float, we traditionally have written the syntax as above where <em><code>
A</code></em> through <em><code>J</code></em> are float expressions. These 10
float that define a surface of x, y, z points which satisfy the equation A x<sup>2</sup>
+ B y<sup>2</sup> + C z<sup>2</sup> + D xy + E xz + F yz + G x + H y + I z + J = 0</p>
<p>Different values of <em><code>A, B, C, ... J</code></em> will give
different shapes. If you take any three dimensional point and use its x, y
and z coordinates in the above equation the answer will be 0 if the point is
on the surface of the object. The answer will be negative if the point is
inside the object and positive if the point is outside the object. Here are
some examples:</p>
<table SUMMARY="Some quartic shapes" width="100%">
<tr>
<td width="30%">X<sup>2</sup> + Y<sup>2</sup> + Z<sup>2</sup> - 1 = 0</td>
<td width="70%">Sphere</td>
</tr>
<tr>
<td>X<sup>2</sup> + Y<sup>2</sup> - 1 = 0</td>
<td>Infinite cylinder along the Z axis</td>
</tr>
<tr>
<td>X<sup>2</sup> + Y<sup>2</sup> - Z<sup>2</sup> = 0</td>
<td>Infinite cone along the Z axis</td>
</tr>
</table>
<p>The easiest way to use these shapes is to include the standard file <code>
shapes.inc</code> into your program. It contains several pre-defined quadrics
and you can transform these pre-defined shapes (using translate, rotate and
scale) into the ones you want. For a complete list, see the file <code>
shapes.inc</code>.</p></div>
<a name="r3_4_5_4"></a>
<div class="content-level-h4" contains="Constructive Solid Geometry" id="r3_4_5_4">
<h4>3.4.5.4 Constructive Solid Geometry</h4>
<p>In addition to all of the primitive shapes POV-Ray supports, you can also combine multiple simple shapes into complex shapes using <em> Constructive Solid Geometry</em> (CSG). There are four basic types of CSG operations: <a href="r3_4.html#r3_4_5_4_2">union</a>, <a href="r3_4.html#r3_4_5_4_3">intersection</a>, <a href="r3_4.html#r3_4_5_4_4">difference</a>, and <a href="r3_4.html#r3_4_5_4_5">merge</a>. CSG objects can be composed of primitives or other CSG objects to create more, and more complex shapes.</p>
</div>
<a name="r3_4_5_4_1"></a>
<div class="content-level-h5" contains="Inside and Outside" id="r3_4_5_4_1">
<h5>3.4.5.4.1 Inside and Outside</h5>
<p>Most shape primitives, like spheres, boxes and blobs divide the world into
two regions. One region is inside the object and one is outside. Given any
point in space you can say it is either inside or outside any particular
primitive object. Well, it could be exactly on the surface but this case is
rather hard to determine due to numerical problems.</p>
<p>
Even planes have an inside and an outside. By definition, the surface normal
of the plane points towards the outside of the plane. You should note that
triangles cannot be used as solid objects in CSG since they have no well defined inside and outside. Triangle-based shapes (<code>mesh</code> and <code>mesh2</code>) can only be used in CSG when they are closed objects and have an inside vector specified. </p>
<p class="Note"><strong>Note:</strong> Although the <code>triangle</code>, the <code>bicubic_patch</code> and some other shapes have no well defined inside and outside, they have a front- and backside which makes it possible to use a texture on the front side and an <code>interior_texture</code> on the back side.</p>
<p>
CSG uses the concepts of inside and outside to combine shapes together as
explained in the following sections.</p>
<p>
Imagine you have two objects that partially overlap like shown in the figure
below. Four different areas of points can be distinguished: points that are
neither in object <code>A</code> nor in object <code>B</code>, points that
are in object <code>A</code> but not in object <code>B</code>, points that
are not in object <code>A</code> but in object <code>B</code> and last not
least points that are in object <code>A</code> and object <code>B</code>.
</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/8/8f/RefImgObjoverl.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Two overlapping objects.</p>
</td>
</tr>
</table>
<p>Keeping this in mind it will be quite easy to understand how the CSG
operations work.</p>
<p>
When using CSG it is often useful to invert an object so that it will be
inside-out. The appearance of the object is not changed, just the way that
POV-Ray perceives it. When the <code>inverse</code> keyword is used the <em>
inside</em> of the shape is flipped to become the <em> outside</em> and vice
versa.</p>
<p>
The inside/outside distinction is not important for a <code>union</code>, but is important for <code>intersection</code>, <code>difference</code>, and <code>merge</code>. Therefore any objects may be combined using <code>union</code> but only solid objects, i.e. objects that have a well-defined interior can be used in the other kinds of CSG. The objects described in
<a href="r3_4.html#r3_4_5_2">Finite Patch Primitives</a> have no well defined inside/outside. All objects described in the sections <a href="r3_4.html#r3_4_5_1">Finite Solid Primitives</a> and <a href="r3_4.html#r3_4_5_3">Infinite Solid Primitives</a>.</p></div>
<a name="r3_4_5_4_2"></a>
<div class="content-level-h5" contains="Union" id="r3_4_5_4_2">
<h5>3.4.5.4.2 Union</h5>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/0/0d/RefImgUnionobj.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The union of two objects.</p>
</td>
</tr>
</table>
<p>The simplest kind of CSG is the <code>union</code>. The syntax is:</p>
<pre>
UNION:
union {
OBJECTS...
[OBJECT_MODIFIERS...]
}
</pre>
<p>Unions are simply glue used to bind two or more shapes into a single
entity that can be manipulated as a single object. The image above shows the
union of <code>A</code> and <code>B</code>. The new object created by the
union operation can be scaled, translated and rotated as a single shape. The
entire union can share a single texture but each object contained in the
union may also have its own texture, which will override any texture
statements in the parent object.</p>
<p>
You should be aware that the surfaces inside the union will not be removed.
As you can see from the figure this may be a problem for transparent unions.
If you want those surfaces to be removed you will have to use the <code>
merge</code> operations explained in a later section.</p>
<p>
The following union will contain a box and a sphere.</p>
<pre>
union {
box { <-1.5, -1, -1>, <0.5, 1, 1> }
cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 }
}
</pre>
<p>Earlier versions of POV-Ray placed restrictions on unions so you often had
to combine objects with <code>composite</code> statements. Those earlier
restrictions have been lifted so <code>composite</code> is no longer needed.
It is still supported for backwards compatibility.</p>
</div>
<a name="r3_4_5_4_2_1"></a>
<div class="content-level-h6" contains="Split_Union" id="r3_4_5_4_2_1">
<h6>3.4.5.4.2.1 Split_Union</h6>
<p><code>split_union</code> is a boolean keyword that can be added to a union.
It has two states <code>on</code>/<code>off</code>, its default is <code>on</code>.</p>
<p><code>split_union</code> is used when <a href="r3_4.html#r3_4_4_4_4">photons</a> are shot
at the CSG-object. The object is split up in its compound parts, photons are shot at
each part separately. This is to prevent photons from being shot at 'empty spaces' in the object,
for example the holes in a grid. With compact objects, without 'empty spaces'
<code>split_union off</code> can improve photon
gathering.</p>
<pre>
union {
object {...}
object {...}
split_union off
}
</pre></div>
<a name="r3_4_5_4_3"></a>
<div class="content-level-h5" contains="Intersection" id="r3_4_5_4_3">
<h5>3.4.5.4.3 Intersection</h5>
<p>The <code>intersection</code> object creates a shape containing only those
areas where all components overlap. A point is part of an intersection if it is
inside both objects, <code>A</code> and <code>B</code>, as show in the figure
below.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/7/75/RefImgIsectobj.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The intersection of two objects.</p>
</td>
</tr>
</table>
<p>The syntax is:</p>
<pre>
INTERSECTION:
intersection {
SOLID_OBJECTS...
[OBJECT_MODIFIERS...]
}
</pre>
<p>The component objects must have well defined inside/outside properties.
Patch objects are not allowed.</p>
<p class="Note"><strong>Note:</strong> If all components do not overlap, the intersection object disappears.</p>
<p>
Here is an example that overlaps:</p>
<pre>
intersection {
box { <-1.5, -1, -1>, <0.5, 1, 1> }
cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 }
}
</pre></div>
<a name="r3_4_5_4_4"></a>
<div class="content-level-h5" contains="Difference" id="r3_4_5_4_4">
<h5>3.4.5.4.4 Difference</h5>
<p>The CSG <code>difference</code> operation takes the intersection between
the first object and the inverse of all subsequent objects. Thus only points
inside object <code>A</code> and outside object <code>B</code> belong to the
difference of both objects.</p>
<p>
The result is a subtraction of the 2nd shape from the first shape as shown
in the figure below.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/3/3b/RefImgDiffobj.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The difference between two objects.</p>
</td>
</tr>
</table>
<p>The syntax is:</p>
<pre>
DIFFERENCE:
difference {
SOLID_OBJECTS...
[OBJECT_MODIFIERS...]
}
</pre>
<p>The component objects must have well defined inside/outside properties.
Patch objects are not allowed. </p>
<p class="Note"><strong>Note:</strong> If the first object is entirely inside the subtracted objects, the difference object disappears.</p>
<p>
Here is an example of a properly formed difference:</p>
<pre>
difference {
box { <-1.5, -1, -1>, <0.5, 1, 1> }
cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 }
}
</pre>
<p class="Note"><strong>Note:</strong> Internally, POV-Ray simply adds the <code>inverse</code> keyword
to the second (and subsequent) objects and then performs an intersection.</p>
<p> The
example above is equivalent to:</p>
<pre>
intersection {
box { <-1.5, -1, -1>, <0.5, 1, 1> }
cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 inverse }
}
</pre></div>
<a name="r3_4_5_4_5"></a>
<div class="content-level-h5" contains="Merge" id="r3_4_5_4_5">
<h5>3.4.5.4.5 Merge</h5>
<p>The <code>union</code> operation just glues objects together, it does not
remove the objects' surfaces inside the <code>union</code>. Under most
circumstances this does not matter. However if a transparent <code>
union</code> is used, those interior surfaces will be visible. The <code>
merge</code> operations can be used to avoid this problem. It works just like
<code>union</code> but it eliminates the inner surfaces like shown in the
figure below.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/2/25/RefImgMergeobj.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Merge removes inner surfaces.</p>
</td>
</tr>
</table>
<p>The syntax is:</p>
<pre>
MERGE:
merge {
SOLID_OBJECTS...
[OBJECT_MODIFIERS...]
}
</pre>
<p>The component objects must have well defined inside/outside properties.
Patch objects are not allowed. </p>
<p class="Note"><strong>Note:</strong> In general <code>merge</code> is slower rendering than <code>union</code> when used with non transparent objects. A small test may be needed to determine what is the optimal solution regarding speed and visual result.</p></div>
<a name="r3_4_5_5"></a>
<div class="content-level-h4" contains="Object Modifiers" id="r3_4_5_5">
<h4>3.4.5.5 Object Modifiers</h4>
<p>A variety of modifiers may be attached to objects. The following items may
be applied to any object:</p>
<pre>
OBJECT_MODIFIER:
clipped_by { UNTEXTURED_SOLID_OBJECT... } |
clipped_by { bounded_by } |
bounded_by { UNTEXTURED_SOLID_OBJECT... } |
bounded_by { clipped_by } |
no_shadow |
no_image [ Bool ] |
no_radiosity [ Bool ] |
no_reflection [ Bool ] |
inverse |
sturm [ Bool ] |
hierarchy [ Bool ] |
double_illuminate [ Bool ] |
hollow [ Bool ] |
interior { INTERIOR_ITEMS... } |
material { [MATERIAL_IDENTIFIER][MATERIAL_ITEMS...] } |
texture { TEXTURE_BODY } |
interior_texture { TEXTURE_BODY } |
pigment { PIGMENT_BODY } |
normal { NORMAL_BODY } |
finish { FINISH_ITEMS... } |
photons { PHOTON_ITEMS...}
radiosity { RADIOSITY_ITEMS...}
TRANSFORMATION
</pre>
<p>Transformations such as translate, rotate and scale have already been discussed. The modifiers <em><a href="r3_4.html#r3_4_6">Textures</a></em> and its parts <em><a href="r3_4.html#r3_4_6_1">Pigment</a></em>, <em><a href="r3_4.html#r3_4_6_2">Normal</a></em>, and <em><a href="r3_4.html#r3_4_6_3">Finish</a></em> as well as <em><a href="r3_4.html#r3_4_8_1">Interior</a></em>, and <em><a href="r3_4.html#r3_4_8">Media</a></em> (which is part of interior) are each in major chapters of their own below. In the sub-sections below we cover several other important modifiers: <code><a href="r3_4.html#r3_4_5_5_1">clipped_by</a></code>, <code><a href="r3_4.html#r3_4_5_5_2">bounded_by</a></code>, <code><a href="r3_4.html#r3_4_5_5_3">material</a></code>, <code><a href="r3_4.html#r3_4_5_5_5">inverse</a></code>, <code><a href="r3_4.html#r3_4_5_5_4">hollow</a></code>, <code><a href="r3_4.html#r3_4_5_5_6">no_shadow</a></code>, <code><a href="r3_4.html#r3_4_5_5_7">no_image</a></code>, <code><a href="r3_4.html#r3_4_5_5_8">no_reflection</a></code>, <code><a href="r3_4.html#r3_4_5_5_9">double_illuminate</a></code>, <code><a href="r3_4.html#r3_4_5_5_10">no_radiosity</a></code> and <code><a href="r3_4.html#r3_4_5_5_11">sturm</a></code>. Although the examples below use object statements and object identifiers, these modifiers may be used on any type of object such as sphere, box etc.</p></div>
<a name="r3_4_5_5_1"></a>
<div class="content-level-h5" contains="Clipped By Object Modifier" id="r3_4_5_5_1">
<h5>3.4.5.5.1 Clipped By Object Modifier</h5>
<p>The <code>clipped_by</code> statement is technically an object modifier
but it provides a type of CSG similar to CSG intersection. The syntax is:</p>
<pre>
CLIPPED_BY:
clipped_by { UNTEXTURED_SOLID_OBJECT... } |
clipped_by { bounded_by }
</pre>
<p>Where <em>UNTEXTURED_SOLID_OBJECT</em> is one or more solid objects which
have had no texture applied. For example:</p>
<pre>
object {
My_Thing
clipped_by{plane{y,0}}
}
</pre>
<p>Every part of the object <code>My_Thing</code> that is inside the plane is
retained while the remaining part is clipped off and discarded. In an <code>
intersection</code> object the hole is closed off. With <code>
clipped_by</code> it leaves an opening. For example the following figure
shows object <code>A</code> being clipped by object <code>B</code>.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/c/c6/RefImgClipobj.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">An object clipped by another object.</p>
</td>
</tr>
</table>
<p>You may use <code>clipped_by</code> to slice off portions of any shape. In
many cases it will also result in faster rendering times than other methods
of altering a shape. Occasionally you will want to use the <code>
clipped_by</code> and <code>bounded_by</code> options with the same object.
The following shortcut saves typing and uses less memory.</p>
<pre>
object {
My_Thing
bounded_by { box { <0,0,0>, <1,1,1> } }
clipped_by { bounded_by }
}
</pre>
<p>This tells POV-Ray to use the same box as a clip that was used as a
bound.</p></div>
<a name="r3_4_5_5_2"></a>
<div class="content-level-h5" contains="Bounded By Object Modifier" id="r3_4_5_5_2">
<h5>3.4.5.5.2 Bounded By Object Modifier</h5>
<p>The calculations necessary to test if a ray hits an object can be quite
time consuming. Each ray has to be tested against every object in the scene.
POV-Ray attempts to speed up the process by building a set of invisible
boxes, called bounding boxes, which cluster the objects together. This way a
ray that travels in one part of the scene does not have to be tested
against objects in another, far away part of the scene. When a large number
of objects are present the boxes are nested inside each other. POV-Ray can
use bounding boxes on any finite object and even some clipped or bounded
quadrics. However infinite objects (such as a planes, quartic, cubic and
poly) cannot be automatically bound. CSG objects are automatically bound if
they contain finite (and in some cases even infinite) objects. This works by
applying the CSG set operations to the bounding boxes of all objects used
inside the CSG object. For difference and intersection operations this will
hardly ever lead to an optimal bounding box. It is sometimes better
(depending on the complexity of the CSG object) to have you place a bounding
shape yourself using a <code>bounded_by</code> statement.</p>
<p>
Normally bounding shapes are not necessary but there are cases where they
can be used to speed up the rendering of complex objects. Bounding shapes
tell the ray-tracer that the object is totally enclosed by a simple shape.
When tracing rays, the ray is first tested against the simple bounding shape.
If it strikes the bounding shape the ray is further tested against the more
complicated object inside. Otherwise the entire complex shape is skipped,
which greatly speeds rendering. The syntax is:</p>
<pre>
BOUNDED_BY:
bounded_by { UNTEXTURED_SOLID_OBJECT... } |
bounded_by { clipped_by }
</pre>
<p>Where <em>UNTEXTURED_SOLID_OBJECT</em> is one or more solid objects which
have had no texture applied. For example:</p>
<pre>
intersection {
sphere { <0,0,0>, 2 }
plane { <0,1,0>, 0 }
plane { <1,0,0>, 0 }
bounded_by { sphere { <0,0,0>, 2 } }
}
</pre>
<p>The best bounding shape is a sphere or a box since these shapes are highly
optimized, although, any shape may be used. If the bounding shape is itself a
finite shape which responds to bounding slabs then the object which it
encloses will also be used in the slab system.</p>
<p>
While it may a good idea to manually add a <code>bounded_by</code> to
intersection, difference and merge, it is best to <em>never</em> bound a
union. If a union has no <code>bounded_by</code> POV-Ray can internally
split apart the components of a union and apply automatic bounding slabs to
any of its finite parts. Note that some utilities such as <code>
raw2pov</code> may be able to generate bounds more efficiently than
POV-Ray's current system. However most unions you create yourself can be
easily bounded by the automatic system. For technical reasons POV-Ray cannot
split a merge object. It is maybe best to hand bound a merge, especially if
it is very complex.</p>
<p class="Note"><strong>Note:</strong> If bounding shape is too small or positioned incorrectly it may
clip the object in undefined ways or the object may not appear at all. To do
true clipping, use <code>clipped_by</code> as explained in the previous
section. Occasionally you will want to use the <code>clipped_by</code> and
<code>bounded_by</code> options with the same object. The following shortcut
saves typing and uses less memory.</p>
<pre>
object {
My_Thing
clipped_by{ box { <0,0,0>,<1,1,1 > }}
bounded_by{ clipped_by }
}
</pre>
<p>This tells POV-Ray to use the same box as a bound that was used as a
clip.</p></div>
<a name="r3_4_5_5_3"></a>
<div class="content-level-h5" contains="Material" id="r3_4_5_5_3">
<h5>3.4.5.5.3 Material</h5>
<p>One of the changes in POV-Ray 3.1 was the removal of several items from <code>
texture { finish{</code>...<code>} }</code> and to move them to the new <code>
interior</code> statement. The <code><a href="r3_4.html#r3_4_6_4">halo</a></code> statement, formerly part of
<code><a href="r3_4.html#r3_4_6">texture</a></code>, is now renamed <code><a href="r3_4.html#r3_4_8">media</a></code> and made a part of
the <code><a href="r3_4.html#r3_4_8_1">interior</a></code>.</p>
<p>
This split was deliberate and purposeful (see
<a href="r3_4.html#r3_4_8_1_1">Why are Interior and Media Necessary?</a>)
however beta testers pointed out that it made it difficult to
entirely describe the surface properties and interior of an object in one
statement that can be referenced by a single identifier in a texture
library.</p>
<p>
The result is that we created a <em>wrapper</em> around <code>texture</code> and <code>interior</code> which we call <code>material</code>.</p>
<p>
The syntax is:</p>
<pre>
MATERIAL:
material { [MATERIAL_IDENTIFIER][MATERIAL_ITEMS...] }
MATERIAL_ITEMS:
TEXTURE | INTERIOR_TEXTURE | INTERIOR | TRANSFORMATIONS
</pre>
<p>For example:</p>
<pre>
#declare MyGlass=material{ texture{ Glass_T } interior{ Glass_I }}
object { MyObject material{ MyGlass}}
</pre>
<p>Internally, the <em>material</em> is not attached to the object. The
material is just a container that brings the texture and interior to the
object. It is the texture and interior itself that is attached to the object.
Users should still consider texture and interior as separate items attached
to the object.</p>
<p>
The material is just a <em>bucket</em> to carry them. If the object
already has a texture, then the material texture is layered over it. If the object
already has an interior, the material interior fully replaces it and the old
interior is destroyed. Transformations inside the material affect only the
textures and interiors which are inside the <code>material{}</code> wrapper
and only those textures or interiors specified are affected. For example:</p>
<pre>
object {
MyObject
material {
texture { MyTexture }
scale 4 //affects texture but not object or interior
interior { MyInterior }
translate 5*x //affects texture and interior, not object
}
}
</pre>
<p class="Note"><strong>Note:</strong> The <code>material</code> statement has nothing to do with the
<code><a href="r3_4.html#r3_4_6_5_3">material_map</a></code> statement. A <code>material_map</code> is <em> not</em> a way to create patterned material. See <a href="r3_4.html#r3_4_6_5_3">Material Maps</a> for explanation of this unrelated, yet similarly named, older feature.</p></div>
<a name="r3_4_5_5_4"></a>
<div class="content-level-h5" contains="Hollow Object Modifier" id="r3_4_5_5_4">
<h5>3.4.5.5.4 Hollow Object Modifier</h5>
<p>POV-Ray by default assumes that objects are made of a solid material that
completely fills the interior of an object. By adding the <code>
hollow</code> keyword to the object you can make it hollow, also see the
<a href="r3_4.html#r3_4_8_1_2">Empty and Solid Objects</a> chapter. That is very
useful if you want atmospheric effects to exist inside an object. It is even
required for objects containing an interior media. The keyword may optionally
be followed by a float expression which is interpreted as a boolean value.
For example <code>hollow off</code> may be used to force it off. When the
keyword is specified alone, it is the same as <code>hollow on</code>.
By default <code>hollow</code> is <code>off</code> when not specified.</p>
<p>
In order to get a hollow CSG object you just have to make the top level
object hollow. All children will assume the same <code>hollow</code> state
except when their state is explicitly set. The following example will set both
spheres inside the union hollow</p>
<pre>
union {
sphere { -0.5*x, 1 }
sphere { 0.5*x, 1 }
hollow
}
</pre>
<p>while the next example will only set the second sphere hollow because the
first sphere was explicitly set to be not hollow.</p>
<pre>
union {
sphere { -0.5*x, 1 hollow off }
sphere { 0.5*x, 1 }
hollow on
}
</pre></div>
<a name="r3_4_5_5_5"></a>
<div class="content-level-h5" contains="Inverse Object Modifier" id="r3_4_5_5_5">
<h5>3.4.5.5.5 Inverse Object Modifier</h5>
<p>When using <a href="r3_4.html#r3_4_5_4">CSG</a> it is often useful to invert an object so that it will be
inside-out. The appearance of the object is not changed, just the way that
POV-Ray perceives it. When the <code>inverse</code> keyword is used the <em>
inside</em> of the shape is flipped to become the <em>outside</em> and vice
versa. For example:</p>
<pre>
object { MyObject inverse }
</pre>
<p>The inside/outside distinction is also important when attaching
<code><a href="r3_4.html#r3_4_8_1">interior</a></code> to an object especially if
<code><a href="r3_4.html#r3_4_3_1">media</a></code> is also used. Atmospheric media
and fog also do not work as expected if your camera is inside an object.
Using <code>inverse</code> is useful to correct that problem.</p></div>
<a name="r3_4_5_5_6"></a>
<div class="content-level-h5" contains="No Shadow Object Modifier" id="r3_4_5_5_6">
<h5>3.4.5.5.6 No Shadow Object Modifier</h5>
<p>You may specify the <code>no_shadow</code> keyword in an object to make
that object cast no shadow. This is useful for special effects and for
creating the illusion that a light source actually is visible. This keyword
was necessary in earlier versions of POV-Ray which did not have the <code>
looks_like</code> statement. Now it is useful for creating things like laser
beams or other unreal effects. During test rendering it speeds things up if
<code>no_shadow</code> is applied.</p>
<p>
Simply attach the keyword as follows:</p>
<pre>
object {
My_Thing
no_shadow
}
</pre></div>
<a name="r3_4_5_5_7"></a>
<div class="content-level-h5" contains="No Image Object Modifier" id="r3_4_5_5_7">
<h5>3.4.5.5.7 No Image Object Modifier</h5>
<p>Syntax:</p>
<pre>
OBJECT {
[OBJECT_ITEMS...]
no_image
}
</pre>
<p>This keyword is very similar in usage and function to the
<code>no_shadow</code> keyword, and control an object's visibility.
<br>You can use any combination of no_image, no_reflection and no_shadow with your object.</p>
<p>When <code>no_image</code> is used, the object will not be seen by
the camera, either directly or through transparent/refractive objects. However,
it will still cast shadows, and show up in reflections (unless <code>no_reflection
</code> and/or <code>no_shadow</code> is used also).</p>
<p>Using these three keywords you can produce interesting effects like a sphere
casting a rectangular shadow, a cube that shows up as a cone in mirrors,
etc.</p></div>
<a name="r3_4_5_5_8"></a>
<div class="content-level-h5" contains="No Reflection Object Modifier" id="r3_4_5_5_8">
<h5>3.4.5.5.8 No Reflection Object Modifier</h5>
<p>Syntax:</p>
<pre>
OBJECT {
[OBJECT_ITEMS...]
no_reflection
}
</pre>
<p>This keyword is very similar in usage and function to the
<code>no_shadow</code> keyword, and control an object's visibility.
<br>You can use any combination of no_reflection, no_image and no_shadow with your object.</p>
<p>When <code>no_reflection</code> is used, the object will not show up in
reflections. It will be seen by the camera (and through transparent/refractive objects)
and cast shadows, unless <code>no_image</code> and/or <code>no_shadow
</code> is used.</p></div>
<a name="r3_4_5_5_9"></a>
<div class="content-level-h5" contains="Double Illuminate Object Modifier" id="r3_4_5_5_9">
<h5>3.4.5.5.9 Double Illuminate Object Modifier</h5>
<p>Syntax:</p>
<pre>
OBJECT {
[OBJECT_ITEMS...]
double_illuminate
}
</pre>
<p>A surface has two sides; usually, only the side facing the light source is illuminated,
the other side remains in shadow. When <code>double_illuminate</code> is used,
the other side is also illuminated.
<br>This is useful for simulating effects like translucency (as in a lamp shade, sheet of paper, etc).</p>
<p class="Note"><strong>Note:</strong> Using <code>double_illuminate</code> only illuminates both sides of the same
surface, so on a sphere, for example, you will not see the effect unless the
sphere is either partially transparent, or if the camera is inside and the light source
outside of the sphere (or vise versa).</p></div>
<a name="r3_4_5_5_10"></a>
<div class="content-level-h5" contains="No Radiosity Object Modifier" id="r3_4_5_5_10">
<h5>3.4.5.5.10 No Radiosity Object Modifier</h5>
<p>Specifying <code>no_radiosity</code> in an object block makes that object invisible to radiosity rays, in the same way as <code>no_image</code>, <code>no_reflection</code> and <code>no_shadow</code> make an object invisible to primary, reflected and shadow test rays, respectively.</p></div>
<a name="r3_4_5_5_11"></a>
<div class="content-level-h5" contains="Sturm Object Modifier" id="r3_4_5_5_11">
<h5>3.4.5.5.11 Sturm Object Modifier</h5>
<p>Some of POV-Ray's objects allow you to choose between a fast but
sometimes inaccurate root solver and a slower but more accurate one. This is
the case for all objects that involve the solution of a cubic or quartic
polynomial. There are analytic mathematical solutions for those polynomials
that can be used.</p>
<p>
Lower order polynomials are trivial to solve while higher order polynomials
require iterative algorithms to solve them. One of those algorithms is the
Sturmian root solver. For example:</p>
<pre>
blob {
threshold .65
sphere { <.5,0,0>, .8, 1 }
sphere { <-.5,0,0>,.8, 1 }
sturm
}
</pre>
<p>The keyword may optionally be followed by a float expression which is
interpreted as a boolean value. For example <code>sturm off</code> may be
used to force it off. When the keyword is specified alone, it is the same as
<code>sturm on</code>. By default <code>sturm</code> is <code>off</code> when not specified.</p>
<p>
The following list shows all objects for which the Sturmian root solver can
be used.</p>
<ul>
<li>blob</li>
<li>cubic</li>
<li>lathe (only with quadratic splines)</li>
<li>poly</li>
<li>prism (only with cubic splines)</li>
<li>quartic</li>
<li>sor</li>
<li>torus</li>
</ul></div>
<a name="r3_4_6"></a>
<div class="content-level-h3" contains="Texture" id="r3_4_6">
<h3>3.4.6 Texture</h3>
<p>The <code>texture</code> statement is an object modifier which describes
what the surface of an object looks like, i.e. its material. Textures are
combinations of pigments, normals, and finishes. Pigment is the color or
pattern of colors inherent in the material. Normal is a method of simulating
various patterns of bumps, dents, ripples or waves by modifying the surface
normal vector. Finish describes the reflective properties of a material.</p>
<p class="Note"><strong>Note:</strong> In previous versions of POV-Ray, the texture also contained
information about the interior of an object. This information has been moved
to a separate object modifier called <code>interior</code>. See
<a href="r3_4.html#r3_4_8_1">Interior</a> for details.</p>
<p>
There are three basic kinds of textures: plain, patterned, and layered. A
<em>plain texture</em> consists of a single pigment, an optional normal, and
a single finish. A <em>patterned texture</em> combines two or more textures
using a block pattern or blending function pattern. Patterned textures may be
made quite complex by nesting patterns within patterns. At the innermost
levels however, they are made up from plain textures. A <em>layered
texture</em> consists of two or more semi-transparent textures layered on top
of one another.</p>
<p class="Note"><strong>Note:</strong> Although we call a plain texture <em>plain</em> it
may be a very complex texture with patterned pigments and normals. The term
<em>plain</em> only means that it has a single pigment, normal, and
finish.</p>
<p>
The syntax for <code>texture</code> is as follows:</p>
<pre>
TEXTURE:
PLAIN_TEXTURE | PATTERNED_TEXTURE | LAYERED_TEXTURE
PLAIN_TEXTURE:
texture {
[TEXTURE_IDENTIFIER]
[PNF_IDENTIFIER...]
[PNF_ITEMS...]
}
PNF_IDENTIFIER:
PIGMENT_IDENTIFIER | NORMAL_IDENTIFIER | FINISH_IDENTIFIER
PNF_ITEMS:
PIGMENT | NORMAL | FINISH | TRANSFORMATION
LAYERED_TEXTURE:
NON_PATTERNED_TEXTURE...
PATTERNED_TEXTURE:
texture {
[PATTERNED_TEXTURE_ID]
[TRANSFORMATIONS...]
} |
texture {
PATTERN_TYPE
[TEXTURE_PATTERN_MODIFIERS...]
} |
texture {
tiles TEXTURE tile2 TEXTURE
[TRANSFORMATIONS...]
} |
texture {
material_map {
BITMAP_TYPE "bitmap.ext"
[MATERIAL_MODS...] TEXTURE... [TRANSFORMATIONS...]
}
}
TEXTURE_PATTERN_MODIFIER:
PATTERN_MODIFIER | TEXTURE_LIST |
texture_map { TEXTURE_MAP_BODY }
</pre>
<p>In the <em>PLAIN_TEXTURE</em>, each of the items are optional but if they are present the <em>TEXTURE_IDENTIFIER</em> must be first. If no texture identifier is given, then POV-Ray creates a copy of the default texture.</p>
<p>Next are optional pigment, normal, and/or finish identifiers which fully override any pigment, normal and finish already specified in the previous texture identifier or default texture. Typically this is used for backward compatibility to allow things like:</p>
<pre>
texture { MyPigment }
</pre>
<p>where <code>MyPigment</code> is a pigment identifier.</p>
<p>Finally we have optional <code>pigment</code>, <code>normal</code> or <code>finish</code> statements which modify any pigment, normal and finish already specified in the identifier. If no texture identifier is specified the <code> pigment</code>, <code>normal</code> and <code>finish</code> statements modify the current default values. This is the typical plain texture:</p>
<pre>
texture {
pigment { MyPigment }
normal { MyNormal }
finish { MyFinish }
scale SoBig
rotate SoMuch
translate SoFar
}
</pre>
<p>The <em>TRANSFORMATIONS</em> may be interspersed between the pigment, normal and finish statements but are generally specified last. If they are interspersed, then they modify only those parts of the texture already specified. For example:</p>
<pre>
texture {
pigment { MyPigment }
scale SoBig //affects pigment only
normal { MyNormal }
rotate SoMuch //affects pigment and normal
finish { MyFinish }
translate SoFar //finish is never transformable no matter what.
//Therefore affects pigment and normal only
}
</pre>
<p>Texture identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.</p>
<pre>
TEXTURE_DECLARATION:
#declare IDENTIFIER = TEXTURE |
#local IDENTIFIER = TEXTURE
</pre>
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40 characters long and <em>TEXTURE</em> is any valid <code>texture</code> statement. See <a href="r3_3.html#r3_3_2_2_2">#declare vs. #local</a> for information on identifier scope.</p>
<p>The sections below describe all of the options available for Pigment, Normal, and Finish. They are the main part of plain
textures. There are also separate sections for <a href="r3_4.html#r3_4_6_5">Patterned Textures</a>
and <a href="r3_4.html#r3_4_6_6">Layered Textures</a> which are made up of plain textures.</p>
<p class="Note"><strong>Note:</strong> The <code><a href="r3_4.html#r3_4_6_5_2">tiles</a></code> and
<code><a href="r3_4.html#r3_4_6_5_3">material_map</a></code> versions of patterned textures are obsolete and are only supported for backwards compatibility.</p></div>
<a name="r3_4_6_1"></a>
<div class="content-level-h4" contains="Pigment" id="r3_4_6_1">
<h4>3.4.6.1 Pigment</h4>
<p>The color or pattern of colors for an object is defined by a <code>pigment</code> statement. All plain textures must have a pigment. If you do not specify one the default pigment is used. The color you define is the way you want the object to look if fully illuminated. You pick the basic color inherent in the object and POV-Ray brightens or darkens it depending on the lighting in the scene. The parameter is called <code>pigment</code> because we are defining the basic color the object actually is rather than how it looks.</p>
<p>The syntax for pigment is:</p>
<pre>
PIGMENT:
pigment {
[PIGMENT_IDENTIFIER]
[PIGMENT_TYPE]
[PIGMENT_MODIFIER...]
}
PIGMENT_TYPE:
PATTERN_TYPE | COLOR |
image_map {
BITMAP_TYPE "bitmap.ext" [IMAGE_MAP_MODS...]
}
PIGMENT_MODIFIER:
PATTERN_MODIFIER | COLOR_LIST | PIGMENT_LIST |
color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
pigment_map { PIGMENT_MAP_BODY } | quick_color COLOR |
quick_colour COLOR
</pre>
<p>Each of the items in a pigment are optional but if they are present, they must be in the order shown. Any items after the <em> PIGMENT_IDENTIFIER</em> modify or override settings given in the identifier. If no identifier is specified then the items modify the pigment values in the current default texture. The <em>PIGMENT_TYPE</em> fall into roughly four categories. Each category is discussed the sub-sections which follow. The four categories are solid color and <code><a href="r3_4.html#r3_4_7_6">image_map</a></code> patterns which are specific to <code>pigment</code> statements or color list patterns, color mapped patterns which use POV-Ray's wide selection of general patterns. See <a href="r3_4.html#r3_4_7">Patterns</a> for details about specific patterns.</p>
<p>The pattern type is optionally followed by one or more pigment modifiers. In addition to general pattern modifiers such as transformations, turbulence, and warp modifiers, pigments may also have a <em>COLOR_LIST</em>, <em>PIGMENT_LIST</em>, <code><a href="r3_4.html#r3_4_6_1_2">color_map</a></code>, <code><a href="r3_4.html#r3_4_6_1_3">pigment_map</a></code>, and <code>quick_color</code> which are specific to pigments. See <a href="r3_4.html#r3_4_7_5">Pattern Modifiers</a> for information on general modifiers. The pigment-specific modifiers are described in sub-sections which follow. Pigment modifiers of any kind apply only to the pigment and not to other parts of the texture. Modifiers must be specified last.</p>
<p>A pigment statement is part of a <code>texture</code> specification. However it can be tedious to use a <code>texture</code> statement just to add a color to an object. Therefore you may attach a pigment directly to an object without explicitly specifying that it as part of a texture. For example instead of this:</p>
<pre>
object { My_Object texture {pigment { color Red } } }
</pre>
<p>you may shorten it to:</p>
<pre>
object { My_Object pigment {color Red } }
</pre>
<p>Doing so creates an entire <code>texture</code> structure with default <code>normal</code> and <code>finish</code> statements just as if you had explicitly typed the full <code> texture {...}</code> around it.</p>
<p class="Note"><strong>Note:</strong> an explicit texture statement is required, if you want to layer pigments.</p>
<p>Pigment identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.</p>
<pre>
PIGMENT_DECLARATION:
#declare IDENTIFIER = PIGMENT |
#local IDENTIFIER = PIGMENT
</pre>
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40 characters long and <em>PIGMENT</em> is any valid <code>pigment</code> statement. See <a href="r3_3.html#r3_3_2_2_2">#declare vs. #local</a> for information on identifier scope.</p>
</div>
<a name="r3_4_6_1_1"></a>
<div class="content-level-h5" contains="Solid Color Pigments" id="r3_4_6_1_1">
<h5>3.4.6.1.1 Solid Color Pigments</h5>
<p>The simplest type of pigment is a solid color. To specify a solid color you simply put a color specification inside a <code>pigment</code> statement. For example:</p>
<pre>
pigment { color Orange }
</pre>
<p>A color specification consists of the optional keyword <code> color</code> followed by a color identifier or by a specification of the amount of red, green, blue, filtered and unfiltered transparency in the surface. See section <a href="r3_3.html#r3_3_1_7">Specifying Colors</a> for more details about colors. Any pattern modifiers used with a solid color are ignored because there is no pattern to modify.</p>
</div>
<a name="r3_4_6_1_4"></a>
<div class="content-level-h5" contains="Color List Pigments" id="r3_4_6_1_4">
<h5>3.4.6.1.4 Color List Pigments</h5>
<p>There are four color list patterns: <code>checker</code>, <code>hexagon</code>, <code>brick</code> and <code>object</code>. The result is a pattern of solid colors with distinct edges rather than a blending of colors as with color
mapped patterns. Each of these patterns is covered in more detail in a later section. The syntax is:</p>
<pre>
COLOR_LIST_PIGMENT:
pigment {brick [COLOR_1, [COLOR_2]] [PIGMENT_MODIFIERS...] }|
pigment {checker [COLOR_1, [COLOR_2]] [PIGMENT_MODIFIERS...]}|
pigment {
hexagon [COLOR_1, [COLOR_2, [COLOR_3]]] [PIGMENT_MODIFIERS...]
}|
pigment {object OBJECT_IDENTIFIER | OBJECT {} [COLOR_1, COLOR_2]}
</pre>
<p>Each <em>COLOR_n</em> is any valid color specification. There should be a comma between each color or the <code>color</code> keyword should be used as a separator so that POV-Ray can determine where each color specification
starts and ends. The <code>brick</code> and <code>checker</code> pattern expects two colors and <code>hexagon</code> expects three. If an insufficient number of colors is specified then default colors are used.</p>
</div>
<a name="r3_4_6_1_5"></a>
<div class="content-level-h5" contains="Quick Color" id="r3_4_6_1_5">
<h5>3.4.6.1.5 Quick Color</h5>
<p>When developing POV-Ray scenes it is often useful to do low quality test runs that render faster. The <code>+Q</code> command line switch or <code>Quality</code> INI option can be used to turn off some time consuming color pattern and lighting calculations to speed things up. See <a href="r3_2.html#r3_2_8_3">Quality Settings</a> for details. However all settings of <code>+Q5</code> or <code>Quality=5</code> or lower turns off pigment calculations and creates gray objects.</p>
<p>By adding a <code>quick_color</code> to a pigment you tell POV-Ray what solid color to use for quick renders instead of a patterned pigment. For example:</p>
<pre>
pigment {
gradient x
color_map {
[0.0 color Yellow]
[0.3 color Cyan]
[0.6 color Magenta]
[1.0 color Cyan]
}
turbulence 0.5
lambda 1.5
omega 0.75
octaves 8
quick_color Neon_Pink
}
</pre>
<p>This tells POV-Ray to use solid <code>Neon_Pink</code> for test runs at quality <code>+Q5</code> or lower but to use the turbulent gradient pattern for rendering at <code>+Q6</code> and higher. Solid color pigments such as</p>
<pre>
pigment {color Magenta}
</pre>
<p>automatically set the <code>quick_color</code> to that value. You may override this if you want. Suppose you have 10 spheres on the screen and all are yellow. If you want to identify them individually you could give each a different <code>quick_color</code>. Foe example:</p>
<pre>
sphere {
<1,2,3>,4
pigment { color Yellow quick_color Red }
}
sphere {
<-1,-2,-3>,4
pigment { color Yellow quick_color Blue }
}
</pre>
<p>and so on. At <code>+Q6</code> or higher they will all be yellow but at <code>+Q5</code> or lower each would be different colors so you could identify them.</p>
<p>The alternate spelling <code>quick_colour</code> is also supported.</p></div>
<a name="r3_4_6_1_2"></a>
<div class="content-level-h5" contains="Color Map" id="r3_4_6_1_2">
<h5>3.4.6.1.2 Color Map</h5>
<p>Most of the color patterns do not use abrupt color changes of just two or three colors like those in the brick, checker or hexagon patterns. They instead use smooth transitions of many colors that gradually change from one point to the next. The colors are defined in a pigment modifier called a <code>color_map</code> that describes how the pattern blends from one color to the next.</p>
<p>Each of the various pattern types available is in fact a mathematical function that takes any x, y, z location and turns it into a number between 0.0 and 1.0 inclusive. That number is used to specify what mix of colors to use from the color map.</p>
<p>The syntax for <code> color_map</code> is as follows:</p>
<pre>
COLOR_MAP:
color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY }
COLOR_MAP_BODY:
COLOR_MAP_IDENTIFIER | COLOR_MAP_ENTRY...
COLOR_MAP_ENTRY:
[ Value COLOR ] |
[ Value_1, Value_2 color COLOR_1 color COLOR_2 ]
</pre>
<p>Where each <em><code>Value_n</code></em> is a float values between 0.0 and 1.0 inclusive and each <em>COLOR_n</em>, is color specifications. </p>
<p class="Note"><strong>Note:</strong> The <code>[]</code> brackets are part of the actual <em>
COLOR_MAP_ENTRY</em>. They are not notational symbols denoting optional parts. The brackets surround each entry in the color map.</p>
<p> There may be from 2 to 256 entries in the map. The alternate spelling <code>colour_map</code> may be used.</p>
<p>Here is an example:</p>
<pre>
sphere {
<0,1,2>, 2
pigment {
gradient x //this is the PATTERN_TYPE
color_map {
[0.1 color Red]
[0.3 color Yellow]
[0.6 color Blue]
[0.6 color Green]
[0.8 color Cyan]
}
}
}
</pre>
<p>The pattern function <code>gradient x</code> is evaluated and the result is a value from 0.0 to 1.0. If the value is less than the first entry (in this case 0.1) then the first color (red) is used. Values from 0.1 to 0.3 use a blend of red and yellow using linear interpolation of the two colors. Similarly values from 0.3 to 0.6 blend from yellow to blue.</p>
<p>The 3rd and 4th entries both have values of 0.6. This causes an immediate abrupt shift of color from blue to green. Specifically a value that is less than 0.6 will be blue but exactly equal to 0.6 will be green. Moving along, values from 0.6 to 0.8 will be a blend of green and cyan. Finally any value greater than or equal to 0.8 will be cyan.</p>
<p>If you want areas of unchanging color you simply specify the same color for two adjacent entries. For example:</p>
<pre>
color_map {
[0.1 color Red]
[0.3 color Yellow]
[0.6 color Yellow]
[0.8 color Green]
}
</pre>
<p>In this case any value from 0.3 to 0.6 will be pure yellow.</p>
<p>The first syntax version of <em>COLOR_MAP_ENTRY</em> with one float and one color is the current standard. The other double entry version is obsolete and should be avoided. The previous example would look as follows using the old syntax.</p>
<pre>
color_map {
[0.0 0.1 color Red color Red]
[0.1 0.3 color Red color Yellow]
[0.3 0.6 color Yellow color Yellow]
[0.6.0.8 color Yellow color Green]
[0.8 1.0 color Green color Green]
}
</pre>
<p>You may use <code>color_map</code> with any patterns except <code>brick</code>, <code>checker</code>, <code>hexagon</code>, <code>object</code> and <code>image_map</code>. You may declare and use <code>color_map</code> identifiers. For example:</p>
<pre>
#declare Rainbow_Colors=
color_map {
[0.0 color Magenta]
[0.33 color Yellow]
[0.67 color Cyan]
[1.0 color Magenta]
}
object {
My_Object
pigment {
gradient x
color_map { Rainbow_Colors }
}
}
</pre></div>
<a name="r3_4_6_1_3"></a>
<div class="content-level-h5" contains="Pigment Map" id="r3_4_6_1_3">
<h5>3.4.6.1.3 Pigment Map</h5>
<p>In addition to specifying blended colors with a color map you may create a blend of pigments using a <code>pigment_map</code>. The syntax for a pigment map is identical to a color map except you specify a pigment in each map
entry (and not a color).</p>
<p>The syntax for <code>pigment_map</code> is as follows:</p>
<pre>
PIGMENT_MAP:
pigment_map { PIGMENT_MAP_BODY }
PIGMENT_MAP_BODY:
PIGMENT_MAP_IDENTIFIER | PIGMENT_MAP_ENTRY...
PIGMENT_MAP_ENTRY:
[ Value PIGMENT_BODY ]
</pre>
<p>Where <em><code>Value</code></em> is a float value between 0.0 and 1.0 inclusive and each <em>PIGMENT_BODY</em> is anything which can be inside a <code>pigment{...}</code> statement. The <code>pigment</code> keyword and
<code>{}</code> braces need not be specified.</p>
<p class="Note"><strong>Note:</strong> The <code>[]</code> brackets are part of the actual <em>PIGMENT_MAP_ENTRY</em>. They are not notational symbols denoting optional parts. The brackets surround each entry in the pigment map.</p>
<p>There may be from 2 to 256 entries in the map.</p>
<p>For example:</p>
<pre>
sphere {
<0,1,2>, 2
pigment {
gradient x //this is the PATTERN_TYPE
pigment_map {
[0.3 wood scale 0.2]
[0.3 Jade] //this is a pigment identifier
[0.6 Jade]
[0.9 marble turbulence 1]
}
}
}
</pre>
<p>When the <code>gradient x</code> function returns values from 0.0 to 0.3 the scaled wood pigment is used. From 0.3 to 0.6 the pigment identifier Jade is used. From 0.6 up to 0.9 a blend of Jade and a turbulent marble is used. From 0.9 on up only the turbulent marble is used.</p>
<p>Pigment maps may be nested to any level of complexity you desire. The pigments in a map may have color maps or pigment maps or any type of pigment you want. Any entry of a pigment map may be a solid color however if all entries are solid colors you should use a <code>color_map</code> which will render slightly faster.</p>
<p>Entire pigments may also be used with the block patterns such as <code>checker</code>, <code>hexagon</code> and <code>brick</code>. For example:</p>
<pre>
pigment {
checker
pigment { Jade scale .8 }
pigment { White_Marble scale .5 }
}
</pre>
<p class="Note"><strong>Note:</strong> In the case of block patterns the <code>pigment</code> wrapping is required around the pigment information.</p>
<p>A pigment map is also used with the <code>average</code> pigment type. See
<a href="r3_4.html#r3_4_7_4_1">Average</a> for details.</p>
<p>You may not use <code>pigment_map</code> or individual pigments with an <code>image_map</code>. See section <a href="r3_4.html#r3_4_6_5_1">Texture Maps</a> for an alternative way to do this.</p>
<p>You may declare and use pigment map identifiers but the only way to declare a pigment block pattern list is to declare a pigment identifier for the entire pigment.</p></div>
<a name="r3_4_6_2"></a>
<div class="content-level-h4" contains="Normal" id="r3_4_6_2">
<h4>3.4.6.2 Normal</h4>
<p>Ray-tracing is known for the dramatic way it depicts reflection, refraction and lighting effects. Much of our perception depends on the reflective properties of an object. Ray tracing can exploit this by playing tricks on our perception to make us see complex details that are not really there.</p>
<p>Suppose you wanted a very bumpy surface on the object. It would be very difficult to mathematically model lots of bumps. We can however simulate the way bumps look by altering the way light reflects off of the surface. Reflection calculations depend on a vector called a <em> surface normal</em> vector. This is a vector which points away from the surface and is perpendicular to it. By artificially modifying (or perturbing) this normal vector you can simulate bumps. This is done by adding an optional <code>normal</code> statement.</p>
<p class="Note"><strong>Note:</strong> Attaching a normal pattern does not really modify the surface. It only affects the way light reflects or refracts at the surface so that it looks bumpy.</p>
<p> The syntax is:</p>
<pre>
NORMAL:
normal { [NORMAL_IDENTIFIER] [NORMAL_TYPE] [NORMAL_MODIFIER...] }
NORMAL_TYPE:
PATTERN_TYPE Amount |
bump_map { BITMAP_TYPE "bitmap.ext" [BUMP_MAP_MODS...]}
NORMAL_MODIFIER:
PATTERN_MODIFIER | NORMAL_LIST | normal_map { NORMAL_MAP_BODY } |
slope_map{ SLOPE_MAP_BODY } | bump_size Amount |
no_bump_scale Bool | accuracy Float
</pre>
<p>Each of the items in a normal are optional but if they are present, they must be in the order shown. Any items after the <em>NORMAL_IDENTIFIER</em> modify or override settings given in the identifier. If no identifier is specified then the items modify the normal values in the current default texture. The <em>PATTERN_TYPE</em> may optionally be followed by a float value that controls the apparent depth of the bumps. Typical values range from 0.0 to 1.0 but any value may be used. Negative values invert the
pattern. The default value if none is specified is 0.5.</p>
<p>There are four basic types of <em>NORMAL_TYPE</em>s. They are block pattern normals, continuous pattern normals, specialized normals and bump maps. They differ in the types of modifiers you may use with them. The pattern type is optionally followed by one or more normal modifiers. In addition to general pattern modifiers such as transformations, turbulence, and warp modifiers, normals may also have a <em>NORMAL_LIST</em>, <code><a href="r3_4.html#r3_4_6_2_2">slope_map</a></code>, <code><a href="r3_4.html#r3_4_6_2_1">normal_map</a></code>, and <code>bump_size</code> which are specific to normals. See <a href="r3_4.html#r3_4_7_5">Pattern Modifiers</a> for information on general modifiers. The normal-specific modifiers are described in sub-sections which follow. Normal modifiers of any kind apply only to the normal and not to other parts of the texture. Modifiers must be specified last.</p>
<p>Originally POV-Ray had some patterns which were exclusively used for pigments while others were exclusively used for normals. Since POV-Ray 3.0 you can use any pattern for either pigments or normals. For example it is now valid to use <code>ripples</code> as a pigment or <code>wood</code> as a normal type. The patterns <code>bumps</code>, <code>dents</code>, <code>ripples</code>, <code>waves</code>, <code> wrinkles</code>, and <code><a href="r3_4.html#r3_4_6_2_3">bump_map</a></code> were once exclusively normal patterns which could not be used as pigments. Because these six types use specialized normal modification calculations they cannot have <code><a href="r3_4.html#r3_4_6_2_2">slope_map</a></code>, <code><a href="r3_4.html#r3_4_6_2_1">normal_map</a></code> or wave shape modifiers. All other normal pattern types may use them. Because block patterns <code> checker</code>, <code>hexagon</code>, <code>object</code> and <code>brick</code> do not return a continuous series of values, they cannot use these modifiers either. See <a href="r3_4.html#r3_4_7">Patterns</a> for details about specific patterns.</p>
<p>A <code> normal</code> statement is part of a <code>texture</code> specification. However it can be tedious to use a <code>texture</code> statement just to add bumps to an object. Therefore you may attach a normal directly to an object without explicitly specifying that it as part of a texture. For example instead of this:</p>
<pre>
object {My_Object texture { normal { bumps 0.5 } } }
</pre>
<p>you may shorten it to:</p>
<pre>
object { My_Object normal { bumps 0.5 } }
</pre>
<p>Doing so creates an entire <code>texture</code> structure with default <code>pigment</code> and <code>finish</code>
statements just as if you had explicitly typed the full <code>texture {...}</code> around it. Normal identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.</p>
<pre>
NORMAL_DECLARATION:
#declare IDENTIFIER = NORMAL |
#local IDENTIFIER = NORMAL
</pre>
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40 characters long and <em>NORMAL</em> is any valid <code>normal</code> statement. See <a href="r3_3.html#r3_3_2_2_2">#declare vs. #local</a> for information on identifier scope.</p>
</div>
<a name="r3_4_6_2_4"></a>
<div class="content-level-h5" contains="Scaling normals" id="r3_4_6_2_4">
<h5>3.4.6.2.4 Scaling normals</h5>
<p>When scaling a normal, or when scaling an object after a normal is applied to it, the depth of the normal is affected by the scaling. This is not always wanted. If you want to turn off bump scaling for a texture or normal, you can do this by adding the keyword <code>no_bump_scale</code> to the texture's or normal's modifiers. This modifier will get passed on to all textures or normals contained in that texture or normal. Think of this like the way no_shadow gets passed on to objects contained in a CSG.</p>
<p>It is also important to note that if you add <code>no_bump_scale</code> to a normal or texture that is contained within another pattern (such as within a <code>texture_map</code> or <code>normal_map</code>), then the only scaling that will be ignored is the scaling of that texture or normal. Scaling of the parent texture or normal or of the object will affect the depth of the bumps, unless <code>no_bump_scale</code> is specified at the top-level of the texture (or normal, if the normal is not wrapped in a texture).</p>
<p class="Note"><strong>Note:</strong> See the section <a href="r3_4.html#r3_4_7_6_4">Using the Alpha Channel</a> for some important information regarding the use of <code><a href="r3_4.html#r3_4_6_2_3">bump_map</a></code>.</p></div>
<a name="r3_4_6_2_1"></a>
<div class="content-level-h5" contains="Normal Map" id="r3_4_6_2_1">
<h5>3.4.6.2.1 Normal Map</h5>
<p>Most of the time you will apply single normal pattern to an entire surface but you may also create a pattern or blend of normals using a <code>normal_map</code>. The syntax for a <code>normal_map</code> is identical to a <code>pigment_map</code> except you specify a <code> normal</code> in each map entry. The syntax for <code>normal_map</code> is as follows:</p>
<pre>
NORMAL_MAP:
normal_map { NORMAL_MAP_BODY }
NORMAL_MAP_BODY:
NORMAL_MAP_IDENTIFIER | NORMAL_MAP_ENTRY...
NORMAL_MAP_ENTRY:
[ Value NORMAL_BODY ]
</pre>
<p>Where <em><code>Value</code></em> is a float value between 0.0 and 1.0 inclusive and each <em>NORMAL_BODY</em> is anything which can be inside a <code>normal{...}</code> statement. The <code>normal</code> keyword and <code>{}</code> braces need not be specified.</p>
<p class="Note"><strong>Note:</strong> The <code>[]</code> brackets are part of the actual <em>NORMAL_MAP_ENTRY</em>. They are not notational symbols denoting optional parts. The brackets surround each entry in the normal map.</p>
<p> There may be from 2 to 256 entries in the map.</p>
<p>For example:</p>
<pre>
normal {
gradient x //this is the PATTERN_TYPE
normal_map {
[0.3 bumps scale 2]
[0.3 dents]
[0.6 dents]
[0.9 marble turbulence 1]
}
}
</pre>
<p>When the <code>gradient x</code> function returns values from 0.0 to 0.3 then the scaled bumps normal is used. From 0.3 to 0.6 dents pattern is used. From 0.6 up to 0.9 a blend of dents and a turbulent marble is used. From 0.9 on up only the turbulent marble is used.</p>
<p>Normal maps may be nested to any level of complexity you desire. The normals in a map may have slope maps or normal maps or any type of normal you want.</p>
<p>A normal map is also used with the <code>average</code> normal type. See <a href="r3_4.html#r3_4_7_4_1">Average</a> for details.</p>
<p>Entire normals in a normal list may also be used with the block patterns such as <code>checker</code>, <code>hexagon</code> and <code>brick</code>. For example:</p>
<pre>
normal {
checker
normal { gradient x scale .2 }
normal { gradient y scale .2 }
}
</pre>
<p class="Note"><strong>Note:</strong> In the case of block patterns the <code>normal</code> wrapping is required around the normal information.</p>
<p>You may not use <code>normal_map</code> or individual normals with a <code>bump_map</code>. See section <a href="r3_4.html#r3_4_6_5_1">Texture Maps</a> for an alternative way to do this.</p>
<p>You may declare and use normal map identifiers but the only way to declare a normal block pattern list is to declare a normal identifier for the entire normal.</p></div>
<a name="r3_4_6_2_2"></a>
<div class="content-level-h5" contains="Slope Map" id="r3_4_6_2_2">
<h5>3.4.6.2.2 Slope Map</h5>
<p>A <code>slope_map</code> is a normal pattern modifier which gives the user a great deal of control over the exact shape of the bumpy features. Each of the various pattern types available is in fact a mathematical function that takes any x, y, z location and turns it into a number between 0.0 and 1.0 inclusive. That number is used to specify where the various high and low spots are. The <code>slope_map</code> lets you further shape the contours. It is best illustrated with a gradient normal pattern. For example:</p>
<pre>
plane{ z, 0
pigment{ White }
normal { gradient x }
}
</pre>
<p>Gives a ramp wave pattern that looks like small linear ramps that climb from the points at x=0 to x=1 and then abruptly drops to 0 again to repeat the ramp from x=1 to x=2. A slope map turns this simple linear ramp into almost any wave shape you want. The syntax is as follows:</p>
<pre>
SLOPE_MAP:
slope_map { SLOPE_MAP_BODY }
SLOPE_MAP_BODY:
SLOPE_MAP_IDENTIFIER | SLOPE_MAP_ENTRY...
SLOPE_MAP_ENTRY:
[ Value, <Height, Slope> ]
</pre>
<p class="Note"><strong>Note:</strong> The <code>[]</code> brackets are part of the actual <em>SLOPE_MAP_ENTRY</em>. They are not notational symbols denoting optional parts. The brackets surround each entry in the slope map.</p>
<p>There may be from 2 to 256 entries in the map.</p>
<p>Each <em><code>Value</code></em> is a float value between 0.0 and 1.0 inclusive and each <em><code> <Height</code></em>, <em><code>Slope></code></em> is a 2 component vector such as <0,1> where the first value represents the apparent height of the wave and the second value represents the slope of the wave at that point. The height should range between 0.0 and 1.0 but any value could be used.</p>
<p>The slope value is the change in height per unit of distance. For example a slope of zero means flat, a slope of 1.0 means slope upwards at a 45 degree angle and a slope of -1 means slope down at 45 degrees. Theoretically a slope straight up would have infinite slope. In practice, slope values should be kept in the range -3.0 to +3.0. Keep in mind that this is only the visually apparent slope. A normal does not actually change the surface.</p>
<p>For example here is how to make the ramp slope up for the first half and back down on the second half creating a triangle wave with a sharp peak in the center.</p>
<pre>
normal {
gradient x // this is the PATTERN_TYPE
slope_map {
[0 <0, 1>] // start at bottom and slope up
[0.5 <1, 1>] // halfway through reach top still climbing
[0.5 <1,-1>] // abruptly slope down
[1 <0,-1>] // finish on down slope at bottom
}
}
</pre>
<p>The pattern function is evaluated and the result is a value from 0.0 to 1.0. The first entry says that at x=0 the apparent height is 0 and the slope is 1. At x=0.5 we are at height 1 and slope is still up at 1. The third entry also specifies that at x=0.5 (actually at some tiny fraction above 0.5) we have height 1 but slope -1 which is downwards. Finally at x=1 we are at height 0 again and still sloping down with slope -1.</p>
<p>Although this example connects the points using straight lines the shape is actually a cubic spline. This example creates a smooth sine wave.</p>
<pre>
normal {
gradient x // this is the PATTERN_TYPE
slope_map {
[0 <0.5, 1>] // start in middle and slope up
[0.25 <1.0, 0>] // flat slope at top of wave
[0.5 <0.5,-1>] // slope down at mid point
[0.75 <0.0, 0>] // flat slope at bottom
[1 <0.5, 1>] // finish in middle and slope up
}
}
</pre>
<p>This example starts at height 0.5 sloping up at slope 1. At a fourth of the way through we are at the top of the curve at height 1 with slope 0 which is flat. The space between these two is a gentle curve because the start and end slopes are different. At half way we are at half height sloping down to bottom out at 3/4ths. By the end we are climbing at slope 1 again to complete the cycle. There are more examples in <code> slopemap.pov</code> in the sample scenes.</p>
<p>A <code>slope_map</code> may be used with any pattern except <code>brick</code>, <code>checker</code>, <code>object</code>, <code>hexagon</code>, <code>bumps</code>, <code>dents</code>, <code> ripples</code>, <code>waves</code>, <code>wrinkles</code> and <code>bump_map</code>.</p>
<p>You may declare and use slope map identifiers. For example:</p>
<pre>
#declare Fancy_Wave =
slope_map { // Now let's get fancy
[0.0 <0, 1>] // Do tiny triangle here
[0.2 <1, 1>] // down
[0.2 <1,-1>] // to
[0.4 <0,-1>] // here.
[0.4 <0, 0>] // Flat area
[0.5 <0, 0>] // through here.
[0.5 <1, 0>] // Square wave leading edge
[0.6 <1, 0>] // trailing edge
[0.6 <0, 0>] // Flat again
[0.7 <0, 0>] // through here.
[0.7 <0, 3>] // Start scallop
[0.8 <1, 0>] // flat on top
[0.9 <0,-3>] // finish here.
[0.9 <0, 0>] // Flat remaining through 1.0
}
object{ My_Object
pigment { White }
normal {
wood
slope_map { Fancy_Wave }
}
}
</pre>
</div>
<a name="r3_4_6_2_2_1"></a>
<div class="content-level-h6" contains="Normals, Accuracy" id="r3_4_6_2_2_1">
<h6>3.4.6.2.2.1 Normals, Accuracy</h6>
<p>Surface normals that use patterns that were not designed for use with normals (anything other than bumps, dents, waves, ripples, and wrinkles) uses a <code>slope_map</code> whether you specify one or not. To create a perturbed normal from a pattern, POV-Ray samples the pattern at four points in a pyramid surrounding the desired point to determine the gradient of the pattern at the center of the pyramid. The distance that these points are from the center point determines the accuracy of the approximation. Using points too close together causes floating-point inaccuracies. However, using points too far apart can lead to artefacts as well as smoothing out features that should not be smooth.</p>
<p>Usually, points very close together are desired. POV-Ray currently uses a delta or accuracy distance of 0.02. Sometimes it is necessary to decrease this value to get better accuracy if you are viewing a close-up of the texture. Other times, it is nice to increase this value to smooth out sharp edges in the normal (for example, when using a 'solid' crackle pattern). For this reason, a new property, <code>accuracy</code>, has been added to normals. It only makes a difference if the normal uses a <code>slope_map</code> (either specified or implied).</p>
<p>You can specify the value of this accuracy (which is the distance between the sample points when determining the gradient of the pattern for slope_map) by adding <code>accuracy <float></code> to your normal. For all patterns, the default is 0.02.</p>
<p>For more on <code>slope_map</code> see the <a href="t2_3.html#t2_3_5_2_3">Slope Map Tutorial</a></p></div>
<a name="r3_4_6_2_3"></a>
<div class="content-level-h5" contains="Bump Map" id="r3_4_6_2_3">
<h5>3.4.6.2.3 Bump Map</h5>
<p>When all else fails and none of the normal pattern types meets your needs you can use a <code>bump_map</code> to wrap a 2-D bit-mapped bump pattern around your 3-D objects.</p>
<p>Instead of placing the color of the image on the shape like an <code>image_map</code> a <code>bump_map</code> perturbs the surface normal based on the color of the image at that point. The result looks like the image has been embossed into the surface. By default, a bump map uses the brightness of the actual color of the pixel. Colors are converted to gray scale internally before calculating height. Black is a low spot, white is a high spot. The image's index values may be used instead. See the sections <a href="r3_4.html#r3_4_6_2_3_3">Use_Index</a>
and <a href="r3_4.html#r3_4_6_2_3_3">Use_Color</a> below.</p>
</div>
<a name="r3_4_6_2_3_1"></a>
<div class="content-level-h6" contains="Specifying a Bump Map" id="r3_4_6_2_3_1">
<h6>3.4.6.2.3.1 Specifying a Bump Map</h6>
<p>The syntax for a <code>bump_map</code> is:</p>
<pre>
BUMP_MAP:
normal {
bump_map {
BITMAP_TYPE "bitmap.ext" [gamma GAMMA] [premultiplied BOOL]
[BUMP_MAP_MODS...]
}
[NORMAL_MODFIERS...]
}
BITMAP_TYPE:
exr | gif | hdr | iff | jpeg | pgm | png | ppm | sys | tga | tiff
BUMP_MAP_MOD:
map_type Type | once | interpolate Type | use_color |
use_colour | bump_size Value
</pre>
<p>After the required <em>BITMAP_TYPE</em> keyword is a string expression containing the name of a bitmapped bump file of the specified type. Several optional modifiers may follow the file specification. The modifiers are described below.</p>
<p class="Note"><strong>Note:</strong> Earlier versions of POV-Ray allowed some modifiers before the <em>BITMAP_TYPE</em> but that syntax is being phased out in favor of the syntax described here.</p>
<p>Filenames specified in the <code>bump_map</code> statements will be searched for in the home (current) directory first and, if not found, will then be searched for in directories specified by any <code>+L</code> or <code>Library_Path</code> options active. This would facilitate keeping all your bump maps files in a separate subdirectory and giving a <code>Library_Path</code> option to specify where your library of bump maps are. See <a href="r3_2.html#r3_2_5_4">Library Paths</a> for details.</p>
<p>By default, the bump pattern is mapped onto the x-y-plane. The bump pattern is <em>projected</em> onto the object as though there were a slide projector somewhere in the -z-direction. The pattern exactly fills the square area from (x,y) coordinates (0,0) to (1,1) regardless of the pattern's original size in pixels. If you would like to change this default you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired. If you would like to change this default orientation you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired.</p>
<p>
While POV-Ray will normally interpret the bump map input file as a container of linear data irregardless of file type, this can be overridden for any individual bump map input file by specifying <code>gamma</code> GAMMA immediately after the file name. For example:</p>
<pre>
bump_map {
jpeg "foobar.jpg" gamma 1.8
}
</pre>
<p>This will cause POV-Ray to perform gamma adjustment or -decoding on the input file data before building the bump map. Alternatively to a numerical value, <code>srgb</code> may be specified to denote that the file is pre-corrected or encoded using the <em>sRGB transfer function</em> instead of a power-law gamma function. See section <a href="t2_3.html#t2_3_4">Gamma Handling</a> for more information on gamma.</p>
<p>The file name is optionally followed by one or more <em>BITMAP_MODIFIERS</em>. The <code>bump_size</code>, <code>use_color</code> and <code>use_index</code> modifiers are specific to bump maps and are discussed in the following sections. See the section <a href="r3_4.html#r3_4_7_7">Bitmap Modifiers</a> where the generic bitmap modifiers <code>map_type</code>, <code>once</code> and <code>interpolate</code> are described.</p>
</div>
<a name="r3_4_6_2_3_2"></a>
<div class="content-level-h6" contains="Bump_Size" id="r3_4_6_2_3_2">
<h6>3.4.6.2.3.2 Bump_Size</h6>
<p>The relative bump size can be scaled using the <code>bump_size</code> modifier. The bump size number can be any number other than 0 but typical values are from about 0.1 to as high as 4.0 or 5.0.</p>
<pre>
normal {
bump_map {
gif "stuff.gif"
bump_size 5.0
}
}
</pre>
<p>Originally <code>bump_size</code> could only be used inside a bump map but it can now be used with any normal. Typically it is used to override a previously defined size. For example:</p>
<pre>
normal {
My_Normal //this is a previously defined normal identifier
bump_size 2.0
}
</pre>
</div>
<a name="r3_4_6_2_3_3"></a>
<div class="content-level-h6" contains="Use_Index and Use_Color" id="r3_4_6_2_3_3">
<h6>3.4.6.2.3.3 Use_Index and Use_Color</h6>
<p>Usually the bump map converts the color of the pixel in the map to a gray scale intensity value in the range 0.0 to 1.0 and calculates the bumps based on that value. If you specify <code>use_index</code>, the bump map uses the color's palette number to compute as the height of the bump at that point. So, color number 0 would be low and color number 255 would be high (if the image has 256 palette entries). The actual color of the pixels doesn't matter when using the index. This option is only available on
palette based formats. The <code>use_color</code> keyword may be specified to explicitly note that the color methods should be used instead. The alternate spelling <code>use_colour</code> is also valid. These modifiers may only be used inside the <code>bump_map</code> statement.</p></div>
<a name="r3_4_6_3"></a>
<div class="content-level-h4" contains="Finish" id="r3_4_6_3">
<h4>3.4.6.3 Finish</h4>
<p>The finish properties of a surface can greatly affect its appearance. How does light reflect? What happens in shadows? What kind of highlights are visible. To answer these questions you need a <code>finish</code>.</p>
<p>The syntax for <code>finish</code> is as follows:</p>
<pre>
FINISH:
finish { [FINISH_IDENTIFIER] [FINISH_ITEMS...] }
FINISH_ITEMS:
ambient COLOR | diffuse [albedo] Amount [, Amount] | emission COLOR |
brilliance Amount | phong [albedo] Amount | phong_size Amount | specular [albedo] Amount |
roughness Amount | metallic [Amount] | reflection COLOR |
crand Amount | conserve_energy BOOL_ON_OFF |
reflection { Color_Reflecting_Min [REFLECTION_ITEMS...] } |
subsurface { translucency COLOR } |
irid { Irid_Amount [IRID_ITEMS...] }
REFLECTION_ITEMS:
COLOR_REFLECTION_MAX | fresnel BOOL_ON_OFF |
falloff FLOAT_FALLOFF | exponent FLOAT_EXPONENT |
metallic FLOAT_METALLIC
IRID_ITEMS:
thickness Amount | turbulence Amount
</pre>
<p>The <em>FINISH_IDENTIFIER</em> is optional but should proceed all other items. Any items after the <em>FINISH_IDENTIFIER</em> modify or override settings given in the <em>FINISH_IDENTIFIER</em>. If no identifier is specified then the items modify the finish values in the current default texture.</p>
<p class="Note"><strong>Note:</strong> Transformations are not allowed inside a finish because finish items cover the entire surface uniformly. Each of the <em>FINISH_ITEMS</em> listed above is described in sub-sections below.</p>
<p>In earlier versions of POV-Ray, the <code>refraction</code>, <code>ior</code>, and <code>caustics</code> keywords were part of the <code>finish</code> statement but they are now part of the <code>interior</code> statement. They are still supported under <code>finish</code> for backward compatibility but the results may not be 100% identical to previous versions. See <a href="r3_4.html#r3_4_8_1_1">Why are Interior and Media Necessary?</a> for more details.</p>
<p>A <code>finish</code> statement is part of a <code>texture</code> specification. However it can be tedious to use a <code>texture</code> statement just to add a highlights or other lighting properties to an object. Therefore you may attach a finish directly to an object without explicitly specifying that it as part of a texture. For example instead of this:</p>
<pre>
object { My_Object texture { finish { phong 0.5 } } }
</pre>
<p>you may shorten it to:</p>
<pre>
object { My_Object finish { phong 0.5 } }
</pre>
<p>Doing so creates an entire <code>texture</code> structure with default <code>pigment</code> and <code>normal</code>
statements just as if you had explicitly typed the full <code>texture {...}</code> around it.</p>
<p>Finish identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.</p>
<pre>
FINISH_DECLARATION:
#declare IDENTIFIER = FINISH |
#local IDENTIFIER = FINISH
</pre>
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40 characters long and <em>FINISH</em> is any valid <code>finish</code> statement. See <a href="r3_3.html#r3_3_2_2_2">#declare vs. #local</a> for information on identifier scope.</p>
</div>
<a name="r3_4_6_3_1"></a>
<div class="content-level-h5" contains="Ambient" id="r3_4_6_3_1">
<h5>3.4.6.3.1 Ambient</h5>
<p>The light you see in dark shadowed areas comes from diffuse reflection off of other objects. This light cannot be modeled directly using ray-tracing, however, the <a href="t2_3.html#t2_3_8">radiosity</a> feature can do a realistic approximation at the cost of higher render times. For most scenes, especially in-door scenes, this is will greatly improve the end result.</p>
<p>The classic way to simulate <em>ambient lighting</em> in shadowed areas is to assume that light is scattered
everywhere in the room equally, so the effect can simply be calculated by adding a small amount of light to each texture,
whether or not a light is actually shining on that texture. This renders very fast, but has the disadvantage that shadowed
areas look flat.</p>
<p class="Note"><strong>Note:</strong> Without radiosity, ambient light does not account for the color of surrounding objects. If you walk into a room that has red walls, floor and ceiling then your white clothing will look pink from the reflected light. POV-Ray's ambient shortcut does not account for this.</p>
<p>The <code>ambient</code> keyword controls the amount of ambient light used for each object. In some situations the ambient light <em>might</em> also be tinted, for this a color value can be specified. For example:
<pre>
finish { ambient rgb <0.3,0.1,0.1> } //a pink ambient
</pre>
However, if all color components are equal, a single float value may be used. For example the single float value of 0.3 is treated as <0.3,0.3,0.3>. The default value is 0.1, which gives very little ambient light. As with light sources, physically meaningful values are greater than 0, but negative values actually work too, and the value may be arbitrarily high to simulate bright light.</p>
<p>You may also specify the overall ambient light level used when calculating the ambient lighting of an object using the global <code>ambient_light</code> setting. The total light is given by <em>Ambient = Finish_Ambient * Global_Ambient_Light_Source</em>. See the section <a href="r3_4.html#r3_4_1_2">Ambient Light</a> for more details.</p>
<p>Ambient light affects both shadowed and non-shadowed areas, so if you turn up the <code>ambient</code> value, you may want to turn down the <code>diffuse</code> and <code>reflection</code> values. Specifying a high <code>ambient</code> value for an object effectively gives it an intrinsic glow, however, if the intent is to actually have it glowing (as opposed to simulating background light), the <code>emission</code> keyword should be used instead. The difference is that actual glowing objects light up their surroundings in <a href="t2_3.html#t2_3_8">radiosity</a> scenes, while the <code>ambient</code> term is effectively set to zero.</p>
<p class="Note"><strong>Note:</strong> Specular reflected indirect illumination such as the flashlight shining in a mirror is not modeled by either ambient light or radiosity. For this, you need <a href="r3_4.html#r3_4_4_4">photons</a>.</p>
</div>
<a name="r3_4_6_3_2"></a>
<div class="content-level-h5" contains="Emission" id="r3_4_6_3_2">
<h5>3.4.6.3.2 Emission</h5>
<p>As of version 3.7, you can now add the <code>emission</code> keyword to the finish block. The intention is to simplify the use of materials designed for non-radiosity scenes in scenes with radiosity, or the design of scenes that can be rendered with or without radiosity.</p>
<p>The syntax and effect are virtually identical to <code><a href="r3_4.html#r3_4_6_3_1">ambient</a></code>, except that emission is unaffected by the global <code>ambient_light</code> parameter. An objects <code>ambient</code> term is now effectively set to 0 if radiosity is active, the exception being, in legacy scenes where the <code>#version</code> is set to less than 3.7</p>
</div>
<a name="r3_4_6_3_3"></a>
<div class="content-level-h5" contains="Diffuse Reflection Items" id="r3_4_6_3_3">
<h5>3.4.6.3.3 Diffuse Reflection Items</h5>
<p>When light reflects off of a surface the laws of physics say that it should leave the surface at the exact same angle it came in. This is similar to the way a billiard ball bounces off a bumper of a pool table. This perfect reflection is called <em>specular reflection</em>. However only very smooth polished surfaces reflect light in this way. Most of the time, light reflects and is scattered in all directions by the roughness of the surface. This scattering is called <em>diffuse reflection</em> because the light diffuses
or spreads in a variety of directions. It accounts for the majority of the reflected light we see.</p>
</div>
<a name="r3_4_6_3_3_1"></a>
<div class="content-level-h6" contains="Diffuse" id="r3_4_6_3_3_1">
<h6>3.4.6.3.3.1 Diffuse</h6>
<p>The keyword <code>diffuse</code> is used in a <code>finish</code> statement to control how much of the light coming directly from any light sources is reflected via diffuse reflection. The optional keyword <code>albedo</code> can be used right after diffuse to specify that the parameter is to be taken as the total diffuse/specular reflectance, rather than peak reflectance.</p>
<p class="Note"><strong>Note:</strong> When <code>brilliance</code> is equal to 1 <code>albedo</code> will have no effect on the diffuse parameter.</p>
<p>For example:</p>
<pre>
finish { diffuse albedo 0.7 }
</pre>
<p>Means that 70% of the light seen comes from direct illumination from light sources. The default value for diffuse is 0.6.</p>
<p>To model thin, diffusely-translucent objects (e.g. paper, curtains, leaves etc.), an optional 2nd float parameter has been added to the <code>diffuse</code> finish statement to control the effect of illumination from the back of the surface. The default value is 0.0, i.e. no diffuse backside illumination. For realistic results, the sum of both parameters should be between 0.0 and 1.0, and the 2nd parameter should be the smaller of the two.</p>
<p class="Note"><strong>Note:</strong> This feature is currently experimental and may be subject to change. In particular, the syntax as well as inter-operation with <code>double_illuminate</code>, multi-layered textures or <code>conserve_energy</code> are still under investigation.</p>
<p>A new sample scene, <code>~scenes/advanced/diffuse_back.pov</code>, has been provided to illustrate this new feature.</p>
</div>
<a name="r3_4_6_3_3_2"></a>
<div class="content-level-h6" contains="Brilliance" id="r3_4_6_3_3_2">
<h6>3.4.6.3.3.2 Brilliance</h6>
<p>The amount of direct light that diffuses from an object depends upon the angle at which it hits the surface. When light hits at a shallow angle it illuminates less. When it is directly above a surface it illuminates more. The <code>brilliance</code> keyword can be used in a <code>finish</code> statement to vary the way light falls off depending upon the angle of incidence. This controls the tightness of the basic diffuse illumination on objects and slightly adjusts the appearance of surface shininess. Objects may appear more metallic by increasing their brilliance. The default value is 1.0. Higher values from 5.0 to about 10.0 cause the light to fall off less at medium to low angles. There are no limits to the brilliance value. Experiment to see what works best for a particular situation. This is best used in concert with highlighting.</p>
</div>
<a name="r3_4_6_3_3_3"></a>
<div class="content-level-h6" contains="Crand Graininess" id="r3_4_6_3_3_3">
<h6>3.4.6.3.3.3 Crand Graininess</h6>
<p>Very rough surfaces, such as concrete or sand, exhibit a dark graininess in their apparent color. This is caused by the shadows of the pits or holes in the surface. The <code>crand</code> keyword can be added to a <code>finish</code> to cause a minor random darkening in the diffuse reflection of direct illumination. Typical values range from <code>crand 0.01</code> to <code>crand 0.5</code> or higher. The default value is 0. For example:</p>
<pre>
finish { crand 0.05 }
</pre>
<p>The grain or noise introduced by this feature is applied on a pixel-by-pixel basis. This means that it will look the same on far away objects as on close objects. The effect also looks different depending upon the resolution you are using for the rendering.</p>
<p class="Note"><strong>Note:</strong> The <code>crand</code> should not be used when rendering animations. This is the one of a few truly random features in POV-Ray and will produce an annoying flicker of flying pixels on any textures animated with a <code>crand</code> value. For these reasons it is not a very accurate way to model the rough surface effect.</p>
</div>
<a name="r3_4_6_3_3_4"></a>
<div class="content-level-h6" contains="Subsurface Light Transport" id="r3_4_6_3_3_4">
<h6>3.4.6.3.3.4 Subsurface Light Transport</h6>
<p>The subsurface light transport feature, also know as subsurface scattering, is enabled <em>ONLY</em> when a <code>global_settings</code> subsurface block is present. For example, to enable SSLT and use it's default settings, you can specify an empty block.</p>
<pre>
global_settings {
subsurface {}
}
</pre>
<p>To activate SSLT for a particular object you will also need to add the following statement to its finish block.</p>
<pre>
material {
texture {
pigment { PIGMENT }
finish {
...
subsurface { translucency COLOR }
}
}
interior { ior FLOAT }
}
</pre>
<p>The pigment determines the SSLT material's overall appearance when applied to an object with sufficiently large structures. The <code>translucency</code> color, which can alternatively be a float, determines the strength of the subsurface light transport effect. The material's index of refraction also affects the appearance, and is <em>essential</em> for SSLT materials, but doesn't generate a warning at parse time if omitted.</p>
<p class="Note"><strong>Note:</strong> The effect doesn't scale with the object, and values may be greater than 1.0</p>
<p>To adjust materials to the dimensions of your scene, you should use the <code>mm_per_unit</code> setting in the global settings block. The algorithm is designed to give realistic results at a scale of 10 mm per POV-Ray unit by default. For other scales, you can place the following statement in the <code>global_settings</code> block:</p>
<pre>
mm_per_unit INT
</pre>
<p class="Hint"><strong>Hint:</strong> Using these scaling examples as a guide you can easily come up with a suitable setting.</p>
<ul>
<li>1 cm per unit, set it to 10 (the default)</li>
<li>1 inch per unit, set it to 25.4</li>
<li>1 m per unit, set it to 1000</li>
</ul>
<p>To tune the algorithm for quality or performance, the number of samples for the diffuse scattering and single-scattering approximation, respectively, can be specified by placing the following statement in the <code>global_settings</code> section. Both values default is 50.</p>
<pre>
subsurface { samples INT, INT }
</pre>
<p>See the sample SSLT scene in <code>~scenes/subsurface/subsurface.pov</code> for more information. See also this PDF document, <a href="http://graphics.stanford.edu/papers/bssrdf/bssrdf.pdf">A Practical Model for Subsurface Light Transport</a>, for more in depth information about SSLT, including some sample values to use when defining new materials.</p>
<p>To specify whether subsurface light transport effects should be <em>applied</em> to incoming <code>radiosity</code> based diffuse illumination, you should place the following in the global settings <code>subsurface</code> block:</p>
<pre>
global_settings {
subsurface { radiosity BOOL }
}
</pre>
<p>If this setting is <code>off</code>, the default, subsurface light transport effects will only be applied to direct illumination from classic light sources. Setting this feature to <code>on</code> will improve realism especially for materials with high translucency, but at a significant cost in rendering time.</p>
<p>See the section <a href="r3_4.html#r3_4_4_3_4_6">Subsurface and Radiosity</a> for additional configuration information.</p>
<p class="Note"><strong>Note:</strong> Subsurface scattering is disabled in all quality levels except <code>+Q9</code> or higher.</p>
<p class="Warning"><strong>Warning:</strong> Be advised that the subsurface scattering feature is still experimental. These conditions, and possibly others, can apply. Usage and syntax is also subject to change!</p>
<ol>
<li>Incorrect use may result in hard crashes instead of parse warnings.</li>
<li>Pigments having any zero color components currently doesn't play nice with SSLT. For example use <code>rgb <1,0.01,0.01></code> instead of <code>rgb <1,0,0></code> as color literals or when declaring pigment identifiers.</li>
<li>A diffuse finish attribute of zero can also cause povray to throw an assertion failure.</li>
<li>Unions of overlapping objects will probably give unexpected results, however merge should work.</li>
<li>Mesh objects need to be closed (not <em>perfectly</em>) for realism.</li>
<li>To avoid seams between objects, they currently must <em>share</em> a common interior. It's not sufficient to have interiors with identical parameters, or even instances of the same defined interior. The only way to overcome this is to specify the interior in the parent CSG rather than the individual primitives. For the desired results:</li>
<ul>
<li><em>REMOVE</em> any interior statements from the material.</li>
<li><em>ADD</em> the interior statement to the union or merge.</li>
<li>For each part that needs a different <code>ior</code> (e.g. eyelashes or teeth) add an individual interior statement.</li>
</ul>
</ol>
</div>
<a name="r3_4_6_3_4"></a>
<div class="content-level-h5" contains="Highlights" id="r3_4_6_3_4">
<h5>3.4.6.3.4 Highlights</h5>
<p>Highlights are the bright spots that appear when a light source reflects off of a smooth object. They are a blend of specular reflection and diffuse reflection. They are specular-like because they depend upon viewing angle and illumination angle. However they are diffuse-like because some scattering occurs. In order to exactly model a highlight you would have to calculate specular reflection off of thousands of microscopic bumps called micro facets. The more that micro facets are facing the viewer the shinier the object appears and the tighter the highlights become. POV-Ray uses two different models to simulate highlights without calculating micro facets. They are the <em>specular</em> and <em>Phong</em> models.</p>
<p class="Note"><strong>Note:</strong> Specular and phong highlights are <em>not</em> mutually exclusive. It is possible to specify both and they will both take effect. Normally, however, you will only specify one or the other.</p>
</div>
<a name="r3_4_6_3_4_1"></a>
<div class="content-level-h6" contains="Phong Highlights" id="r3_4_6_3_4_1">
<h6>3.4.6.3.4.1 Phong Highlights</h6>
<p>The <code>phong</code> keyword in the <code>finish</code> statement controls the amount of phong highlighting on the object. It causes bright shiny spots on the object that are the color of the light source being reflected.</p>
<p>The <em>phong</em> method measures the average of the facets facing in the mirror direction from the light sources to the viewer.</p>
<p>Phong's value is typically from 0.0 to 1.0, where 1.0 causes complete saturation to the light source's color at the brightest area (center) of the highlight. The default value is 0.0 and gives no highlight.</p>
<p>The size of the highlight spot is defined by the <code>phong_size</code> value. The larger the phong size the tighter, or smaller, the highlight and the shinier the appearance. The smaller the phong size the looser, or larger, the highlight and the less glossy the appearance.</p>
<p>Typical values range from 1.0 (very dull) to 250 (highly polished) though any values may be used. The default value is 40 (plastic) if <code>phong_size</code> is not specified. </p>
<p>The optional keyword <code>albedo</code> can be used right after phong to specify that the parameter is to be taken as the total diffuse/specular reflectance, rather than peak reflectance.</p>
<p>For example:</p>
<pre>
finish { phong albedo 0.9 phong_size 60 }
</pre>
<p>If <code>phong</code> is not specified <code>phong_size</code> has no effect.</p>
</div>
<a name="r3_4_6_3_4_2"></a>
<div class="content-level-h6" contains="Specular Highlight" id="r3_4_6_3_4_2">
<h6>3.4.6.3.4.2 Specular Highlight</h6>
<p>The <code>specular</code> keyword in a <code>finish</code> statement produces a highlight which is very similar to phong highlighting but it uses slightly different model. The specular model more closely resembles real specular reflection and provides a more credible spreading of the highlights occurring near the object horizons.</p>
<p>The <code>specular</code> value is typically from 0.0 to 1.0, where 1.0 causes complete saturation to the light source's color at the brightest area (center) of the highlight. The default value is 0.0 and gives no highlight.</p>
<p>The size of the spot is defined by the value given the <code>roughness</code> keyword. Typical values range from 1.0 (very rough - large highlight) to 0.0005 (very smooth - small highlight). The default value, if roughness is not specified, is 0.05 (plastic).</p>
<p>It is possible to specify wrong values for <code>roughness</code> that will generate an error. Do not use 0! If you get errors, check to see if you are using a very, very small roughness value that may be causing the error.</p>
<p>The optional keyword <code>albedo</code> can be used right after specular to specify that the parameter is to be taken as the total diffuse/specular reflectance, rather than peak reflectance.</p>
<p>For example:</p>
<pre>
finish { specular albedo 0.9 roughness 0.02 }
</pre>
<p>If <code>specular</code> is not specified <code>roughness</code> has no effect.</p>
<p class="Note"><strong>Note:</strong> When light is reflected by a surface such as a mirror, it is called <em>specular reflection</em> however such reflection is not controlled by the <code>specular</code> keyword. The <code>reflection</code> keyword controls mirror-like specular reflection.</p>
</div>
<a name="r3_4_6_3_4_3"></a>
<div class="content-level-h6" contains="Metallic Highlight Modifier" id="r3_4_6_3_4_3">
<h6>3.4.6.3.4.3 Metallic Highlight Modifier</h6>
<p>The keyword <code>metallic</code> may be used with <code>phong</code> or <code>specular</code> highlights. This keyword indicates that the color of the highlights will be calculated by an empirical function that models the reflectivity of metallic
surfaces.</p>
<p>Normally highlights are the color of the light source. Adding this keyword filters the highlight so that white light reflected from a metallic surface takes the color specified by the pigment</p>
<p>The <code>metallic</code> keyword may optionally be follow by a numeric value to specify the influence the amount of the effect. If no keyword is specified, the default value is zero. If the keyword is specified without a value, the default value is 1.</p>
<p>For example:</p>
<pre>
finish {
phong 0.9
phong_size 60
metallic
}
</pre>
<p>If <code>phong</code> or <code>specular</code> keywords are not specified then <code>metallic</code> has no effect.</p>
</div>
<a name="r3_4_6_3_5"></a>
<div class="content-level-h5" contains="Specular Reflection" id="r3_4_6_3_5">
<h5>3.4.6.3.5 Specular Reflection</h5>
<p>When light does not diffuse and it <em>does</em> reflect at the same angle as it hits an object,
it is called <em>specular reflection</em>. Such mirror-like reflection is controlled by the
<code>reflection {...}</code> block in a <code>finish</code> statement.
</p>
<p>Syntax:</p>
<pre>
finish {
reflection {
[COLOR_REFLECTION_MIN,] COLOR_REFLECTION_MAX
[fresnel BOOL_ON_OFF]
[falloff FLOAT_FALLOFF]
[exponent FLOAT_EXPONENT]
[metallic FLOAT_METALLIC]
}
}
[interior { ior IOR }]
</pre>
<p>
The simplest use would be a perfect mirror:
</p>
<pre>
finish { reflection {1.0} ambient 0 diffuse 0 }
</pre>
<p>
This gives the object a mirrored finish. It will reflect all other elements in the scene.
Usually a single float value is specified after the keyword even though the syntax calls
for a color. For example a float value of 0.3 gets promoted to the full color vector
<0.3,0.3,0.3,0.3,0.3> which is acceptable because only the red, green and blue
parts are used.
</p>
<p>The value can range from 0.0 to 1.0. By default there is no reflection.</p>
<p class="Note"><strong>Note:</strong> You should be aware that:</p>
<ul>
<li>
Adding reflection to a texture makes it take longer to render because additional rays must be traced.
</li>
<li>
The reflected light may be tinted by specifying a color rather than a float. For example, <code>finish { reflection rgb <1,0,0> }</code> gives a red mirror that only reflects red light.
</li>
<li>
Although such reflection is called specular it is not controlled by the <code>specular</code> keyword. That keyword controls a specular highlight.
</li>
<li>
The old syntax for simple reflection: <code>reflection COLOR</code> and <code>reflection_exponent FLOAT</code> (without braces) is still supported for backward compatibility.
</li>
</ul>
<p><code>falloff</code> sets a falloff exponent in the variable reflection. This is the exponent
telling how fast the reflectivity will fall off, i.e. linear, squared, cubed, etc.</p>
<p>The <code>metallic</code> keyword is similar in function to the metallic keyword
used for highlights in finishes: it simulates the reflective properties of metallic surfaces,
where reflected light takes on the colour of the surface. When <code>metallic</code> is used,
the reflection color is multiplied by the pigment color at each point. You can
specify an optional float value, which is the amount of influence the <code>metallic</code>
keyword has on the reflected color. <code>metallic</code> uses the Fresnel equation so that
the color of the light is reflected at glancing angles, and the color of the metal is reflected
for angles close to the surface's normal.</p>
<p><strong>exponent</strong><br>
POV-Ray uses a limited light model that cannot distinguish between objects which are simply
brightly colored and objects which are extremely bright. A white piece of paper, a light
bulb, the sun, and a supernova, all would be modeled as <code>rgb<1,1,1></code> and
slightly off-white objects would be only slightly darker. It is especially difficult to model
partially reflective surfaces in a realistic way. Middle and lower brightness objects typically
look too bright when reflected. If you reduce the <code>reflection</code> value, it tends to
darken the bright objects too much. Therefore the optional <code>exponent</code> keyword has
been added. It produces non-linear reflection intensities. The default value of 1.0 produces
a linear curve. Lower values darken middle and low intensities and keeps high intensity
reflections bright. This is a somewhat experimental feature designed for artistic use. It does
not directly correspond to any real world reflective properties.
</p>
<p><strong>Variable reflection</strong><br>
Many materials, such as water, ceramic glaze, and linoleum are more reflective when viewed at shallow angles.
This can be simulated by also specifying a minimum reflection in the <code>reflection {...}</code> statement.
<br>For example:
</p>
<pre>
finish { reflection { 0.03, 1 }}
</pre>
<p>
uses the same function as the standard reflection, but the first parameter sets the minimum reflectivity.
It could be a color vector or a float (which is automatically promoted to a gray vector). This minimum
value is how reflective the surface will be when viewed from a direction parallel to its normal.
<br>
The second parameter sets the maximum reflectivity, which could also be a color vector or a float
(which is automatically promoted to a gray vector). This maximum parameter is how reflective the
surface will be when viewed at a 90-degree angle to its normal.</p>
<p class="Note"><strong>Note:</strong> You can make maximum reflection less than minimum reflection if you want, although the result
is something that does not occur in nature.
</p>
<p>When adding the <code>fresnel</code> keyword, the Fresnel reflectivity function is used instead of
standard reflection. It calculates reflectivity using the finish's IOR. So with a fresnel reflection_type
an <code>interior { ior IOR }</code> statement is required, even with opaque pigments. Remember that
in real life many opaque objects have a thin layer of transparent glaze on their surface, and it
is the glaze (which -does- have an IOR) that is reflective.
</p>
</div>
<a name="r3_4_6_3_6"></a>
<div class="content-level-h5" contains="Conserve Energy for Reflection" id="r3_4_6_3_6">
<h5>3.4.6.3.6 Conserve Energy for Reflection</h5>
<p>One of the features in POV-Ray is variable reflection, including realistic Fresnel
reflection (see the section on <a href="r3_4.html#r3_4_6_3_5">Variable Reflection</a>). Unfortunately, when this is coupled with constant transmittance, the texture
can look unrealistic. This unreal-ism is caused by the scene breaking the law of
conservation of energy. As the amount of light reflected changes, the amount of light
transmitted should also change (in a give-and-take relationship).</p>
<p>This can be achieved by adding the <code>conserve_energy</code> keyword
to the object's <code>finish {}</code>.
<br>When conserve_energy is enabled, POV-Ray will multiply the amount filtered
and transmitted by what is left over from reflection (for example, if reflection is 80%,
filter/transmit will be multiplied by 20%).</p>
</div>
<a name="r3_4_6_3_7"></a>
<div class="content-level-h5" contains="Iridescence" id="r3_4_6_3_7">
<h5>3.4.6.3.7 Iridescence</h5>
<p><em>Iridescence</em>, or Newton's thin film interference, simulates
the effect of light on surfaces with a microscopic transparent film overlay.
The effect is like an oil slick on a puddle of water or the rainbow hues of a
soap bubble. This effect is controlled by the <code>irid</code> statement
specified inside a <code>finish</code> statement.</p>
<p>This parameter modifies the surface color as a function of the angle between
the light source and the surface. Since the effect works in conjunction with
the position and angle of the light sources to the surface it does not behave
in the same ways as a procedural pigment pattern.</p>
<p>
The syntax is:</p>
<pre>
IRID:
irid { Irid_Amount [IRID_ITEMS...] }
IRID_ITEMS:
thickness Amount | turbulence Amount
</pre>
<p>The required <em><code>Irid_Amount</code></em> parameter is the
contribution of the iridescence effect to the overall surface color. As a
rule of thumb keep to around 0.25 (25% contribution) or less, but experiment.
If the surface is coming out too white, try lowering the <code>
diffuse</code> and possibly the <code>ambient</code> values of the
surface.</p>
<p>The <code>thickness</code> keyword represents the film's thickness. This
is an awkward parameter to set, since the thickness value has no relationship
to the object's scale. Changing it affects the scale or <em>
busy-ness</em> of the effect. A very thin film will have a high frequency of
color changes while a thick film will have large areas of color. The default
value is zero.</p>
<p>The thickness of the film can be varied with the <code>turbulence</code>
keyword. You can only specify the amount of turbulence with iridescence. The
octaves, lambda, and omega values are internally set and are not adjustable
by the user at this time. This parameter varies only a single value: the
thickness. Therefore the value must be a single float value. It cannot be a
vector as in other uses of the <code>turbulence</code> keyword.</p>
<p>In addition, perturbing the object's surface normal through the use of
bump patterns will affect iridescence.</p>
<p>For the curious, thin film interference occurs because, when the ray hits
the surface of the film, part of the light is reflected from that surface,
while a portion is transmitted into the film. This <em>subsurface</em> ray
travels through the film and eventually reflects off the opaque substrate.
The light emerges from the film slightly out of phase with the ray that was
reflected from the surface.</p>
<p>This phase shift creates interference, which varies with the wavelength of
the component colors, resulting in some wavelengths being reinforced, while
others are cancelled out. When these components are recombined, the result is
iridescence. See also the global setting <a href="r3_4.html#r3_4_1_5">Irid_Wavelength</a> for additional information.</p>
<p class="Note"><strong>Note:</strong> The version 3.7 iridescence feature has had a major overhaul. The syntax remains the same, however, <em>both</em> the thickness and amount values are now specified in microns. Consequently, iridescence effects will vary from previous versions.</p>
<p>The concept used for this feature came from the book <em>Fundamentals of
Three-Dimensional Computer Graphics</em> by Alan Watt (Addison-Wesley).</p></div>
<a name="r3_4_6_4"></a>
<div class="content-level-h4" contains="Halo" id="r3_4_6_4">
<h4>3.4.6.4 Halo</h4>
<p>Earlier versions of POV-Ray used a feature called <code>halo</code> to
simulate fine particles such as smoke, steam, fog, or flames. The <code>
halo</code> statement was part of the <code>texture</code> statement. This
feature has been discontinued and replaced by the <code>interior</code> and
<code>media</code> statements which are object modifiers outside the <code>
texture</code> statement.</p>
<p>See <a href="r3_4.html#r3_4_8_1_1">Why are Interior and Media Necessary?</a> for a detailed explanation on the reasons for the change. See also <a href="r3_4.html#r3_4_8">Media</a> for details on <code>media</code>.</p></div>
<a name="r3_4_6_5"></a>
<div class="content-level-h4" contains="Patterned Textures" id="r3_4_6_5">
<h4>3.4.6.5 Patterned Textures</h4>
<p>Patterned textures are complex textures made up of multiple textures. The
component textures may be plain textures or may be made up of patterned
textures. A plain texture has just one pigment, normal and finish statement.
Even a pigment with a pigment map is still one pigment and thus considered a
plain texture as are normals with normal map statements.</p>
<p>Patterned textures use either a <code>texture_map</code> statement to
specify a blend or pattern of textures or they use block textures such as
<code>checker</code> with a texture list or a bitmap similar to an image map
called a <em>material map</em> specified with a <code>material_map</code>
statement.</p>
<p>The syntax is...</p>
<pre>
PATTERNED_TEXTURE:
texture {
[PATTERNED_TEXTURE_ID]
[TRANSFORMATIONS...]
} |
texture {
PATTERN_TYPE
[TEXTURE_PATTERN_MODIFIERS...]
} |
texture {
tiles TEXTURE tile2 TEXTURE
[TRANSFORMATIONS...]
} |
texture {
material_map {
BITMAP_TYPE "bitmap.ext"
[BITMAP_MODS...] TEXTURE... [TRANSFORMATIONS...]
}
}
TEXTURE_PATTERN_MODIFIER:
PATTERN_MODIFIER | TEXTURE_LIST |
texture_map {
TEXTURE_MAP_BODY
}
</pre>
<p>There are restrictions on using patterned textures. A patterned texture
may not be used as a default texture, see the section: <a href="r3_3.html#r3_3_2_4">The #default Directive</a>.
A patterned texture cannot be used as a layer in a layered texture however
you may use layered textures as any of the textures contained within a
patterned texture.</p>
</div>
<a name="r3_4_6_5_1"></a>
<div class="content-level-h5" contains="Texture Maps" id="r3_4_6_5_1">
<h5>3.4.6.5.1 Texture Maps</h5>
<p>In addition to specifying blended color with a color map or a pigment map
you may create a blend of textures using <code>texture_map</code>. The syntax
for a texture map is identical to the pigment map except you specify a
texture in each map entry.</p>
<p>
The syntax for <code>texture_map</code> is as follows:</p>
<pre>
TEXTURE_MAP:
texture_map { TEXTURE_MAP_BODY }
TEXTURE_MAP_BODY:
TEXTURE_MAP_IDENTIFIER | TEXTURE_MAP_ENTRY...
TEXTURE_MAP_ENTRY:
[ Value TEXTURE_BODY ]
</pre>
<p>Where <em><code>Value</code></em> is a float value between 0.0 and 1.0
inclusive and each <em>TEXTURE_BODY</em> is anything which can be inside a
<code>texture{...}</code> statement. The <code>texture</code> keyword and
<code>{}</code> braces need not be specified.</p>
<p class="Note"><strong>Note:</strong> The <code>[]</code> brackets are part of the actual <em>
TEXTURE_MAP_ENTRY</em>. They are not notational symbols denoting optional
parts. The brackets surround each entry in the texture map.</p>
<p>There may be from 2 to 256 entries in the map.</p>
<p>
For example:</p>
<pre>
texture {
gradient x //this is the PATTERN_TYPE
texture_map {
[0.3 pigment{Red} finish{phong 1}]
[0.3 T_Wood11] //this is a texture identifier
[0.6 T_Wood11]
[0.9 pigment{DMFWood4} finish{Shiny}]
}
}
</pre>
<p>When the <code>gradient x</code> function returns values from 0.0 to 0.3
the red highlighted texture is used. From 0.3 to 0.6 the texture identifier
<code>T_Wood11</code> is used. From 0.6 up to 0.9 a blend of <code>
T_Wood11</code> and a shiny <code>DMFWood4</code> is used. From 0.9 on up
only the shiny wood is used.</p>
<p>
Texture maps may be nested to any level of complexity you desire. The
textures in a map may have color maps or texture maps or any type of texture
you want.</p>
<p>
The blended area of a texture map works by fully calculating both
contributing textures in their entirety and then linearly interpolating the
apparent colors. This means that reflection, refraction and lighting
calculations are done twice for every point. This is in contrast to using a
pigment map and a normal map in a plain texture, where the pigment is
computed, then the normal, then reflection, refraction and lighting are
calculated once for that point.</p>
<p>
Entire textures may also be used with the block patterns such as <code>
checker</code>, <code>hexagon</code> and <code>brick</code>. For
example...</p>
<pre>
texture {
checker
texture { T_Wood12 scale .8 }
texture {
pigment { White_Marble }
finish { Shiny }
scale .5
}
}
}
</pre>
<p class="Note"><strong>Note:</strong> In the case of block patterns the <code>texture</code> wrapping is required around the texture information. Also note that this syntax prohibits the use of a layered texture however you can work around this by declaring a texture identifier for the layered texture and referencing the identifier.</p>
<p>
A texture map is also used with the <code>average</code> texture type. See <a href="r3_4.html#r3_4_7_4_1">Average</a> for more details.</p>
<p>
You may declare and use texture map identifiers but the only way to declare
a texture block pattern list is to declare a texture identifier for the
entire texture.</p>
</div>
<a name="r3_4_6_5_2"></a>
<div class="content-level-h5" contains="Tiles" id="r3_4_6_5_2">
<h5>3.4.6.5.2 Tiles</h5>
<p>Earlier versions of POV-Ray had a patterned texture called a <em>tiles
texture</em>. It used the <code>tiles</code> and <code>tile2</code> keywords
to create a checkered pattern of textures.</p>
<pre>
TILES_TEXTURE:
texture {
tiles TEXTURE tile2 TEXTURE
[TRANSFORMATIONS...]
}
</pre>
<p>Although it is still supported for backwards compatibility you should use a <code>checker</code> block texture pattern described in the <a href="r3_4.html#r3_4_6_5_1">Texture Maps</a> section rather than tiles textures.</p>
</div>
<a name="r3_4_6_5_3"></a>
<div class="content-level-h5" contains="Material Maps" id="r3_4_6_5_3">
<h5>3.4.6.5.3 Material Maps</h5>
<p>The <code>material_map</code> patterned texture extends the concept of
image maps to apply to entire textures rather than solid colors. A material
map allows you to wrap a 2-D bit-mapped texture pattern around your 3-D
objects.</p>
<p>
Instead of placing a solid color of the image on the shape like an image
map, an entire texture is specified based on the index or color of the image
at that point. You must specify a list of textures to be used like a <em>
texture palette</em> rather than the usual color palette.</p>
<p>
When used with mapped file types such as GIF, and some PNG and TGA images,
the index of the pixel is used as an index into the list of textures you
supply. For unmapped file types such as some PNG and TGA images the 8 bit
value of the red component in the range 0-255 is used as an index.</p>
<p>
If the index of a pixel is greater than the number of textures in your list
then the index is taken modulo N where N is the length of your list of
textures.</p>
<p class="Note"><strong>Note:</strong> The <code>material_map</code> statement has nothing to do with the <code>material</code> statement. A <code>material_map</code> is <em>not</em> a way to create patterned <code>material</code>. See <a href="r3_4.html#r3_4_5_5_3">Material</a> for an explanation of this unrelated, yet similarly named, older feature.</p>
</div>
<a name="r3_4_6_5_3_1"></a>
<div class="content-level-h6" contains="Specifying a Material Map" id="r3_4_6_5_3_1">
<h6>3.4.6.5.3.1 Specifying a Material Map</h6>
<p>The syntax for a <code>material_map</code> is:</p>
<pre>
MATERIAL_MAP:
texture {
material_map {
BITMAP_TYPE "bitmap.ext"
[BITMAP_MODS...] TEXTURE... [TRANSFORMATIONS...]
}
}
BITMAP_TYPE:
exr | gif | hdr | iff | jpeg | pgm | png | ppm | sys | tga | tiff
BITMAP_MOD:
map_type Type | once | interpolate Type
</pre>
<p>After the required <em>BITMAP_TYPE</em> keyword is a string expression
containing the name of a bitmapped material file of the specified type.
Several optional modifiers may follow the file specification. The modifiers
are described below.</p>
<p class="Note"><strong>Note:</strong> Earlier versions of POV-Ray allowed some modifiers before the <em>BITMAP_TYPE</em> but that syntax is being phased out in favor of the syntax described here.</p>
<p>
Filenames specified in the <code>material_map</code> statements will be
searched for in the home (current) directory first and, if not found, will
then be searched for in directories specified by any <code>+L</code> or
<code>Library_Path</code> options active. This would facilitate keeping all
your material maps files in a separate subdirectory and giving a <code>
Library_Path</code> option to specify where your library of material maps
are. See the section <a href="r3_2.html#r3_2_5_4">Library Paths</a> for details.</p>
<p>
By default, the material is mapped onto the x-y-plane. The material is <em>
projected</em> onto the object as though there were a slide projector
somewhere in the -z-direction. The material exactly fills the square area
from (x,y) coordinates (0,0) to (1,1) regardless of the material's
original size in pixels. If you would like to change this default you may
translate, rotate or scale the texture to map it onto the
object's surface as desired.</p>
<p>
The file name is optionally followed by one or more <em>BITMAP_MODIFIERS</em>. There are no modifiers which are unique to a <code>material_map</code>. It only uses the generic bitmap modifiers <code>map_type</code>, <code>once</code> and <code>interpolate</code> described in <em>BITMAP_MODIFIERS</em>.</p>
<p>
Although <code>interpolate</code> is legal in material maps, the color
index is interpolated before the texture is chosen. It does not interpolate
the final color as you might hope it would. In general, interpolation of
material maps serves no useful purpose but this may be fixed in future
versions.</p>
<p>
Next is one or more <code>texture</code> statements. Each texture in the
list corresponds to an index in the bitmap file. For example:</p>
<pre>
texture {
material_map {
png "povmap.png"
texture { //used with index 0
pigment {color red 0.3 green 0.1 blue 1}
normal {ripples 0.85 frequency 10 }
finish {specular 0.75}
scale 5
}
texture { //used with index 1
pigment {White}
finish {
ambient 0 diffuse 0
reflection 0.9 specular 0.75
}
}
// used with index 2
texture {pigment{NeonPink} finish{Luminous}}
texture { //used with index 3
pigment {
gradient y
color_map {
[0.00 rgb < 1 , 0 , 0>]
[0.33 rgb < 0 , 0 , 1>]
[0.66 rgb < 0 , 1 , 0>]
[1.00 rgb < 1 , 0 , 0>]
}
}
finish{specular 0.75}
scale 8
}
}
scale 30
translate <-15, -15, 0>
}
</pre>
<p>After a <code>material_map</code> statement but still inside the texture
statement you may apply any legal texture modifiers. </p>
<p class="Note"><strong>Note:</strong> No other pigment, normal, or finish statements may be added to the texture outside the
material map.</p>
<p> The following is illegal:</p>
<pre>
texture {
material_map {
gif "matmap.gif"
texture {T1}
texture {T2}
texture {T3}
}
finish {phong 1.0}
}
</pre>
<p>The finish must be individually added to each texture. Earlier
versions of POV-Ray allowed such specifications but they were ignored. The
above restrictions on syntax were necessary for various bug fixes. This means
some POV-Ray 1.0 scenes using material maps many need minor modifications
that cannot be done automatically with the version compatibility mode.</p>
<p>
If particular index values are not used in an image then it may be necessary
to supply dummy textures. It may be necessary to use a paint program or other
utility to examine the map file's palette to determine how to arrange the
texture list.</p>
<p>
The textures within a material map texture may be layered but material map
textures do not work as part of a layered texture. To use a layered texture
inside a material map you must declare it as a texture identifier and invoke
it in the texture list.</p></div>
<a name="r3_4_6_6"></a>
<div class="content-level-h4" contains="Layered Textures" id="r3_4_6_6">
<h4>3.4.6.6 Layered Textures</h4>
<p>It is possible to create a variety of special effects using layered
textures. A layered texture consists of several textures that are partially
transparent and are laid one on top of the other to create a more complex
texture. The different texture layers show through the transparent portions
to create the appearance of one texture that is a combination of several
textures.</p>
<p>
You create layered textures by listing two or more textures one right after
the other. The last texture listed will be the top layer, the first one
listed will be the bottom layer. All textures in a layered texture other than
the bottom layer should have some transparency. For example:</p>
<pre>
object {
My_Object
texture {T1} // the bottom layer
texture {T2} // a semi-transparent layer
texture {T3} // the top semi-transparent layer
}
</pre>
<p>In this example T2 shows only where T3 is transparent and T1 shows only
where T2 and T3 are transparent.</p>
<p>
The color of underlying layers is filtered by upper layers but the results
do not look exactly like a series of transparent surfaces. If you had a stack
of surfaces with the textures applied to each, the light would be filtered
twice: once on the way in as the lower layers are illuminated by filtered
light and once on the way out. Layered textures do not filter the
illumination on the way in. Other parts of the lighting calculations work
differently as well. The results look great and allow for fantastic looking
textures but they are simply different from multiple surfaces. See <code>
stones.inc</code> in the standard include files directory for some
magnificent layered textures.</p>
<p class="Note"><strong>Note:</strong> In versions predating POV-Ray 3.5, <code>filter</code> used to work the same
as <code>transmit</code> in layered textures. It has been changed to work as filter should. This can change the appearance of "pre 3.5" textures a lot. The <code>#version</code> directive can be used to get the "pre 3.5" behavior.</p>
<p class="Note"><strong>Note:</strong> Layered textures must use the <code>texture</code> wrapped around any pigment, normal or finish statements. Do not use multiple pigment, normal or finish statements without putting them inside the texture statement.</p>
<p>
Layered textures may be declared. For example</p>
<pre>
#declare Layered_Examp =
texture {T1}
texture {T2}
texture {T3}
</pre>
<p>may be invoked as follows:</p>
<pre>
object {
My_Object
texture {
Layer_Examp
// Any pigment, normal or finish here
// modifies the bottom layer only.
}
}
</pre>
<p class="Note"><strong>Note:</strong> No macros are allowed in layered textures. The problem is that if a macro would contain a declare the parser could no longer guess that two or more texture identifiers are supposed to belong to the layered texture and not some other declare.</p>
<p>If you wish to use a layered texture in a block pattern, such as <code>
checker</code>, <code>hexagon</code>, or <code>brick</code>, or in a <code>
material_map</code>, you must declare it first and then reference it inside a
single texture statement. A patterned texture cannot be used as a layer in a
layered texture however you may use layered textures as any of the textures
contained within a patterned texture.</p></div>
<a name="r3_4_6_7"></a>
<div class="content-level-h4" contains="UV Mapping" id="r3_4_6_7">
<h4>3.4.6.7 UV Mapping</h4>
<p>All textures in POV-Ray are defined in 3 dimensions. Even planar image mapping is
done this way. However, it is sometimes more desirable to have the texture defined for
the surface of the object. This is especially true for bicubic_patch objects and mesh
objects, that can be stretched and compressed. When the object is stretched or
compressed, it would be nice for the texture to be <em>glued</em> to the object's
surface and follow the object's deformations.</p>
<p>When uv_mapping is used, then that object's texture will be mapped to it using
surface coordinates (u and v) instead of spatial coordinates (x, y, and z). This is
done by taking a slice of the object's regular 3D texture from the XY plane (Z=0) and
wrapping it around the surface of the object, following the object's surface coordinates.</p>
<p class="Note"><strong>Note:</strong> Some textures should be rotated to fit the slice in the XY plane.</p>
<p>Syntax:</p>
<pre>
texture {
uv_mapping pigment{PIGMENT_BODY} | pigment{uv_mapping PIGMENT_BODY}
uv_mapping normal {NORMAL_BODY } | normal {uv_mapping NORMAL_BODY }
uv_mapping texture{TEXTURE_BODY} | texture{uv_mapping TEXTURE_BODY)
}
</pre>
</div>
<a name="r3_4_6_7_1"></a>
<div class="content-level-h5" contains="Supported Objects" id="r3_4_6_7_1">
<h5>3.4.6.7.1 Supported Objects</h5>
<p>Surface mapping is currently defined for the following objects:</p>
<ul>
<li><strong>bicubic_patch</strong> : UV coordinates are based on the patch's parametric coordinates. They stretch with the control points. The default range is (0..1) and can be changed.</li>
<li><strong>box</strong> : the image is <em>wrapped</em> around the box, as shown below.</li>
<li><strong>lathe, sor</strong> : modified spherical mapping... the u coordinate (0..1) wraps around the y axis, while the v coordinate is linked to the object's control points (also ranging 0..1). Surface of Revolution also has special disc mapping on the end caps if the object is not 'open'.</li>
<li><strong>mesh, mesh2</strong> : UV coordinates are defined for each vertex and interpolated between.</li>
<li><strong>ovus</strong> : spherical mapping centered near the center of mass of the ovus (moving from one sphere to another as the ratio of radius progresses).</li>
<li><strong>parametric</strong> : In this case the map is not taken from a fixed set of coordinates but the map is taken from the area defined by the boundaries of the uv-space, in which the parametric surface has to be calculated.</li>
<li><strong>sphere</strong> : boring spherical mapping.</li>
<li><strong>torus</strong> : The map is taken from the area <0,0><1,1> where the u-coordinate is wrapped around the major radius and the the v-coordinate is wrapped around the minor radius. </li>
</ul>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/4/48/RefImgBoxmap.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">UV Boxmap</p>
</td>
</tr>
</table>
</div>
<a name="r3_4_6_7_2"></a>
<div class="content-level-h5" contains="UV Vectors" id="r3_4_6_7_2">
<h5>3.4.6.7.2 UV Vectors</h5>
<p>With the keyword <code>uv_vectors</code>, the UV coordinates of the corners can be
controlled for bicubic patches and standard triangle mesh.</p>
<p>For bicubic patches the UV coordinates can be specified for each of
the four corners of the patch. This goes right before the control points.
<br>The syntax is:</p>
<p><code> uv_vectors <corner1>,<corner2>,<corner3>,
<corner4></code>
<br>with default
<br><code> uv_vectors <0,0>,<1,0>,<1,1>,<0,1></code></p>
<p>For standard triangle meshes (not mesh2) you can specify the UV coordinates for each
of the three vertices <code>uv_vectors <uv1>,<uv2>,<uv3></code> inside each
mesh triangle. This goes right after the coordinates (or coordinates & normals with
smooth triangles) and right before the texture.
<br>Example:</p>
<pre>
mesh {
triangle {
<0,0,0>, <0.5,0,0>, <0.5,0.5,0>
uv_vectors <0,0>, <1,0>, <1,1>
}
triangle {
<0,0,0>, <0.5,0.5,0>, <0,0.5,0>
uv_vectors <0,0>, <1,1>, <0,1>
}
texture {
uv_mapping
pigment {
image_map {
sys "SomeImage"
map_type 0
interpolate 0
}
}
}
}
</pre></div>
<a name="r3_4_6_8"></a>
<div class="content-level-h4" contains="Triangle Texture Interpolation" id="r3_4_6_8">
<h4>3.4.6.8 Triangle Texture Interpolation</h4>
<p>This feature is utilized in a number of visualization approaches: triangles with
individual textures for each vertex, which are interpolated during rendering.</p>
<p>Syntax:</p>
<pre>
MESH_TRIANGLE:
triangle {
<Corner_1>,
<Corner_2>,
<Corner_3>
[MESH_TEXTURE]
} |
smooth_triangle {
<Corner_1>, <Normal_1>,
<Corner_2>, <Normal_2>,
<Corner_3>, <Normal_3>
[MESH_TEXTURE]
}
MESH_TEXTURE:
texture { TEXTURE_IDENTIFIER } |
texture_list {
TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER
}
</pre>
<p>To specify three vertex textures for the triangle, simply use <code>texture_list</code>
instead of texture.</p></div>
<a name="r3_4_6_9"></a>
<div class="content-level-h4" contains="Interior Texture" id="r3_4_6_9">
<h4>3.4.6.9 Interior Texture</h4>
<p>Syntax:</p>
<pre>
object {
texture { TEXTURE_ITEMS... }
interior_texture { TEXTURE_ITEMS...}
}
</pre>
<p>All surfaces have an exterior and interior surface. The
<code>interior_texture</code> simply allows to specify a separate texture for the
interior surface of the object. For objects with no well defined
inside/outside (bicubic_patch, triangle, ...) the <code>interior_texture</code> is
applied to the backside of the surface.
Interior surface textures use exactly the same syntax and should work in
exactly the same way as regular surface textures, except that they use
the keyword <code>interior_texture</code> instead of <code>texture</code>.</p>
<p class="Note"><strong>Note:</strong> Do not confuse <code>interior_texture {}</code> with <code>interior {}</code>:
the first one specifies surface properties, the second one specifies volume properties.</p></div>
<a name="r3_4_6_10"></a>
<div class="content-level-h4" contains="Cutaway Textures" id="r3_4_6_10">
<h4>3.4.6.10 Cutaway Textures</h4>
<p>Syntax:</p>
<pre>
difference | intersection {
OBJECT_1_WITH_TEXTURES
OBJECT_2_WITH_NO_TEXTURE
cutaway_textures
}
</pre>
<p>When using a CSG difference or intersection to <em>cut</em> away parts of an
object, it is sometimes desirable to allow the object to retain its original texture. Generally,
however, the texture of the surface that was used to do the cutting will be displayed.
<br>Also, if the cutting object was not given a texture by the user, the default texture
is assigned to it.</p>
<p>By using the <code>cutaway_textures</code> keyword in a CSG difference or
intersection, you specify that you do not want the default texture on the intersected
surface, but instead, the textures of the parent objects in the CSG should be used.
<br>POV-Ray will determine which texture(s) to use by doing insidedness tests on
the objects in the difference or intersection. If the intersection point is inside an object,
that object's texture will be used (and evaluated at the interior point).
<br>If the parent object is a CSG of objects with different textures, then the textures on
overlapping parts will be averaged together.</p></div>
<a name="r3_4_7"></a>
<div class="content-level-h3" contains="Pattern" id="r3_4_7">
<h3>3.4.7 Pattern</h3>
<p>POV-Ray uses a method called <em>three-dimensional solid texturing</em> to
define the color, bumpiness and other properties of an object. You specify
the way that the texture varies over a surface by specifying a <em>
pattern</em>. Patterns are used in pigments, normals and texture maps as well
as media density.</p>
<p>
All patterns in POV-Ray are three dimensional. For every point in space,
each pattern has a unique value. Patterns do not wrap around a surface like
putting wallpaper on an object. The patterns exist in 3d and the objects are
carved from them like carving an object from a solid block of wood or
stone.</p>
<p>
Consider a block of wood. It contains light and dark bands that are
concentric cylinders being the growth rings of the wood. On the end of the
block you see these concentric circles. Along its length you see lines that
are the veins. However the pattern exists throughout the entire block. If you
cut or carve the wood it reveals the pattern inside. Similarly an onion
consists of concentric spheres that are visible only when you slice it.
Marble stone consists of wavy layers of colored sediments that harden into
rock.</p>
<p>
These solid patterns can be simulated using mathematical functions. Other
random patterns such as granite or bumps and dents can be generated using a
random number system and a noise function.</p>
<p>
In each case, the x, y, z coordinate of a point on a surface is used to
compute some mathematical function that returns a float value. When used with
color maps or pigment maps, that value looks up the color of the pigment to
be used. In normal statements the pattern function result modifies or
perturbs the surface normal vector to give a bumpy appearance. Used with a
texture map, the function result determines which combinations of entire
textures to be used. When used with media density it specifies the density of
the particles or gasses.</p>
<p>
The following sections describe each pattern. See the sections <a href="r3_4.html#r3_4_6_1">Pigment</a>, <a href="r3_4.html#r3_4_6_2">Normal</a>, <a href="r3_4.html#r3_4_6_5">Patterned Textures</a> and <a href="r3_4.html#r3_4_7_1_8">Density</a> for more details on how to use patterns. Unless mentioned otherwise, all patterns use the <code>ramp_wave</code> wave type by default but may use any wave type and may be used with <code>color_map</code>,
<code>pigment_map</code>, <code>normal_map</code>, <code>slope_map</code>, <code>texture_map</code>, <code>density</code>, and <code>density_map</code>.</p>
<p class="Note"><strong>Note:</strong> Some patterns have a built in default color_map that does not result in a
grey-scale pattern. This may lead to unexpected results when one of these
patterns is used without a user specified color_map, for example in
functions or media.</p>
<p> These patterns are:</p>
<ul>
<li><code>agate</code></li>
<li><code>bozo</code></li>
<li><code>brick</code></li>
<li><code>checker</code></li>
<li><code>hexagon</code></li>
<li><code>mandel</code></li>
<li><code>marble</code></li>
<li><code>radial</code></li>
<li><code>square</code></li>
<li><code>triangular</code></li>
<li><code>wood</code></li>
</ul>
<p>See the following sections for more <em>pattern</em> and <em>pattern related topics</em>:</p>
<ul>
<li><a href="r3_4.html#r3_4_7_1">General Patterns</a></li>
<li><a href="r3_4.html#r3_4_7_2">Discontinuous Patterns</a></li>
<li><a href="r3_4.html#r3_4_7_3">Normal-Dependent Patterns</a></li>
<li><a href="r3_4.html#r3_4_7_4">Special Patterns</a></li>
<li><a href="r3_4.html#r3_4_7_5">Pattern Modifiers</a></li>
</ul></div>
<a name="r3_4_7_1"></a>
<div class="content-level-h4" contains="General Patterns" id="r3_4_7_1">
<h4>3.4.7.1 General Patterns</h4>
<p>Many patterns can be used in textures, normals and media. These patterns are <code>agate</code>, <code>boxed</code>, <code>bozo</code>, <code>brick</code>, <code>bumps</code>, <code>cubic</code>, <code>cylindrical</code>, <code>density_file</code>, <code>dents</code>, <code>facets</code>, <code>fractal</code>, <code>function</code>, <code>gradient</code>, <code>granite</code>, <code>hexagon</code>,
<code>leopard</code>, <code>marble</code>, <code>onion</code>, <code>pavement</code>, <code>pigment_pattern</code>, <code>planar</code>, <code>quilted</code>, <code>radial</code>, <code>ripples</code>, <code>spherical</code>, <code>spiral1</code>, <code>spiral2</code>,
<code>spotted</code>, <code>square</code>, <code>tiling</code>, <code>waves</code>, <code>wood</code>, and <code>wrinkles</code>.</p></div>
<a name="r3_4_7_1_1"></a>
<div class="content-level-h5" contains="Agate Pattern" id="r3_4_7_1_1">
<h5>3.4.7.1.1 Agate Pattern</h5>
<p>The <code>agate</code> pattern is a banded pattern similar to marble but
it uses a specialized built-in turbulence function that is different from the
traditional turbulence. The traditional turbulence can be used as well but it
is generally not necessary because agate is already very turbulent. You may
control the amount of the built-in turbulence by adding the optional <code>
agate_turb</code> keyword followed by a float value. For example:</p>
<pre>
pigment {
agate
agate_turb 0.5
color_map {MyMap}
}
</pre>
<p>The <code>agate</code> pattern has a default color_map built in that results
in a brown and white pattern with smooth transitions.</p>
<p>Agate as used in a normal:</p>
<pre>
normal {
agate [Bump_Size]
[MODIFIERS...]
}
</pre></div>
<a name="r3_4_7_1_2"></a>
<div class="content-level-h5" contains="Boxed Pattern" id="r3_4_7_1_2">
<h5>3.4.7.1.2 Boxed Pattern</h5>
<p>The <code>boxed</code> pattern creates a 2x2x2 unit cube centered at the
origin. It is computed by: <em> value =1.0- min(1, max(abs(X), abs(Y),
abs(Z)))</em> It starts at 1.0 at the origin and decreases to a minimum value
of 0.0 as it approaches any plane which is one unit from the origin. It
remains at 0.0 for all areas beyond that distance. This pattern was
originally created for use with <code>halo</code> or <code>media</code> but
it may be used anywhere any pattern may be used.</p></div>
<a name="r3_4_7_1_3"></a>
<div class="content-level-h5" contains="Bozo Pattern" id="r3_4_7_1_3">
<h5>3.4.7.1.3 Bozo Pattern</h5>
<p>The <code>bozo</code> pattern is a very smooth, random noise function that
is traditionally used with some turbulence to create clouds. The <code>
spotted</code> pattern is identical to <code>bozo</code> but in early
versions of POV-Ray spotted did not allow turbulence to be added. Turbulence
can now be added to any pattern so these are redundant but both are retained
for backwards compatibility. The <code>bumps</code> pattern is also identical
to <code>bozo</code> when used anywhere except in a <code>normal</code>
statement. When used as a normal pattern, <code>bumps</code> uses a slightly
different method to perturb the normal with a similar noise function.</p>
<p>
The <code>bozo</code> noise function has the following properties:</p>
<p> 1. It is defined over 3D space i.e., it takes x, y, and z and returns
the noise value there.</p>
<p>
2. If two points are far apart, the noise values at those points are
relatively random.</p>
<p>
3. If two points are close together, the noise values at those points are
close to each other.</p>
<p>You can visualize this as having a large room and a thermometer that
ranges from 0.0 to 1.0. Each point in the room has a temperature. Points that
are far apart have relatively random temperatures. Points that are close
together have close temperatures. The temperature changes smoothly but
randomly as we move through the room.</p>
<p>
Now let's place an object into this room along with an artist. The
artist measures the temperature at each point on the object and paints that
point a different color depending on the temperature. What do we get? A
POV-Ray bozo texture!</p>
<p>The <code>bozo</code> pattern has a default color_map built in that results
in a green, blue, red and white pattern with sharp transitions.</p>
<p class="Note"><strong>Note:</strong> The appearance of the bozo pattern depends on the noise generator used.
The default type is 2. This may be changed using the <code>noise_generator</code> keyword. See the section Pattern Modifiers: <a href="r3_4.html#r3_4_7_5_4">noise_generator</a>.</p></div>
<a name="r3_4_7_1_4"></a>
<div class="content-level-h5" contains="Brick Pattern" id="r3_4_7_1_4">
<h5>3.4.7.1.4 Brick Pattern</h5>
<p>The <code>brick</code> pattern generates a pattern of bricks. The bricks
are offset by half a brick length on every other row in the x- and
z-directions. A layer of mortar surrounds each brick. The syntax is given
by</p>
<pre>
pigment {
brick COLOR_1, COLOR_2
[brick_size <Size>] [mortar Size]
}
</pre>
<p>where <em>COLOR_1</em> is the color of the mortar and <em>COLOR_2</em> is
the color of the brick itself. If no colors are specified a default deep red
and dark gray are used. The default size of the brick and mortar together is
<8, 3, 4.5> units. The default thickness of the mortar is 0.5 units.
These values may be changed using the optional <code>brick_size</code> and
<code>mortar</code> pattern modifiers. You may also use pigment statements in
place of the colors. For example:</p>
<pre>
pigment {
brick pigment{Jade}, pigment{Black_Marble}
}
</pre>
<p>This example uses normals:</p>
<pre>
normal { brick 0.5 }
</pre>
<p>The float value is an optional bump size. You may also use full normal
statements. For example:</p>
<pre>
normal {
brick normal{bumps 0.2}, normal{granite 0.3}
}
</pre>
<p>When used with textures, the syntax is</p>
<pre>
texture {
brick texture{T_Gold_1A}, texture{Stone12}
}
</pre>
<p>This is a block pattern which cannot use wave types, <code>
color_map</code>, or <code>slope_map</code> modifiers.</p>
<p>The <code>brick</code> pattern has a default color_map built in that
results in red bricks and grey mortar.</p></div>
<a name="r3_4_7_1_5"></a>
<div class="content-level-h5" contains="Bumps Pattern" id="r3_4_7_1_5">
<h5>3.4.7.1.5 Bumps Pattern</h5>
<p>The <code>bumps</code> pattern was originally designed only to be used as
a normal pattern. It uses a very smooth, random noise function that creates
the look of rolling hills when scaled large or a bumpy orange peel when
scaled small. Usually the bumps are about 1 unit apart.</p>
<p>
When used as a normal pattern, this pattern uses a specialized normal
perturbation function. This means that the pattern cannot be used with <code>
normal_map</code>, <code>slope_map</code> or wave type modifiers in a <code>
normal</code> statement.</p>
<p>
When used as a pigment pattern or texture pattern, the <code>bumps</code>
pattern is identical to <code>bozo</code> or <code>spotted</code> and is
similar to normal bumps but is not identical as are most normals when
compared to pigments.</p>
<p class="Note"><strong>Note:</strong> The appearance of the bumps pattern depends on the noise generator used.
The default type is 2. This may be changed using the <code>noise_generator</code> keyword. See the section Pattern Modifiers: <a href="r3_4.html#r3_4_7_5_4">noise_generator</a>.</p></div>
<a name="r3_4_7_1_6"></a>
<div class="content-level-h5" contains="Cubic Pattern" id="r3_4_7_1_6">
<h5>3.4.7.1.6 Cubic Pattern</h5>
<p>The <code>cubic</code> pattern takes six texture elements and maps each one to each of the six pyramids centered at each half-axis, effectively mapping each texture element to each side of a origin-centered cube.</p>
<table class="centered" width="670px" cellpadding="0" cellspacing="10">
<tr>
<td>
<p class="caption">The cubic pattern and the order of texture elements</p>
<p class="tabletext">The first group of elements map to the positive half-axis, in the X, Y and Z axes respectively. The same order is applied to the last group of elements, except on the negative half-axis.</p>
</td>
<td>
<img class="right" width="120px" src="images/4/4b/RefImgCubic.png">
</td>
</tr>
</table>
<p>The syntax is:</p>
<pre>
texture {
cubic
TEXTURE_ELEMENT_1
...
TEXTURE_ELEMENT_6
}
</pre></div>
<a name="r3_4_7_1_7"></a>
<div class="content-level-h5" contains="Cylindrical Pattern" id="r3_4_7_1_7">
<h5>3.4.7.1.7 Cylindrical Pattern</h5>
<p>The <code>cylindrical</code> pattern creates a one unit radius cylinder
along the Y axis. It is computed by: <em> value = 1.0-min(1, sqrt(X^2 +
Z^2))</em> It starts at 1.0 at the origin and decreases to a minimum value of
0.0 as it approaches a distance of 1 unit from the Y axis. It remains at 0.0
for all areas beyond that distance. This pattern was originally created for
use with <code>halo</code> or <code>media</code> but it may be used anywhere
any pattern may be used.</p></div>
<a name="r3_4_7_1_8"></a>
<div class="content-level-h5" contains="Density File Pattern" id="r3_4_7_1_8">
<h5>3.4.7.1.8 Density File Pattern</h5>
<p>The <code>density_file</code> pattern is a 3-D bitmap pattern that
occupies a unit cube from location <0,0,0> to <1,1,1>. The data
file is a raw binary file format created for POV-Ray called <code>df3</code>
format. The syntax provides for the possibility of implementing other formats
in the future. This pattern was originally created for use with <code>
halo</code> or <code>media</code> but it may be used anywhere any pattern may
be used. The syntax is:</p>
<pre>
pigment {
density_file df3 "filename.df3"
[interpolate Type] [PIGMENT_MODIFIERS...]
}
</pre>
<p>where <em><code>"filename.df3"</code></em> is a file name of the
data file.</p>
<p>
As a normal pattern, the syntax is</p>
<pre>
normal {
density_file df3 "filename.df3" [, Bump_Size]
[interpolate Type]
[NORMAL_MODIFIERS...]
}
</pre>
<p>The optional float <em><code>Bump_Size</code></em> should follow the file
name and any other modifiers follow that.</p>
<p>The density pattern occupies the unit cube regardless of the dimensions in voxels.
It remains at 0.0 for all areas beyond the unit cube. The data in the range of 0 to 255,
in case of 8 bit resolution, are scaled into a float value in the range 0.0 to 1.0.</p>
<p> The <code>interpolate</code> keyword may be specified to add interpolation
of the data. The default value of zero specifies no interpolation. A value of
one specifies tri-linear interpolation, a value of two specifies tri-cubic
interpolation</p>
<p> See the sample scenes for data file <code>include\spiral.df3</code>,and
the scenes which use it: <code>~scenes\textures\patterns\densfile.pov</code>,
<code>~scenes\interior\media\galaxy.pov</code> for examples.</p>
</div>
<a name="r3_4_7_1_8_1"></a>
<div class="content-level-h6" contains="df3 file format" id="r3_4_7_1_8_1">
<h6>3.4.7.1.8.1 df3 file format</h6>
<dl>
<dt>Header:</dt>
<dd> The <code>df3</code> format consists of a 6 byte header of three
16-bit integers with high order byte first. These three values give the
x,y,z size of the data in pixels (or more appropriately called <em>voxels
</em>).</dd>
<dt>Data:</dt>
<dd> The header is followed by x*y*z unsigned integer bytes of data with a
resolution of 8, 16 or 32 bit. The data are written with high order byte
first (big-endian). The resolution of the data is determined by the size
of the df3-file. That is, if the file is twice (minus header, of course)
as long as an 8 bit file then it is assumed to contain 16 bit ints and
if it is four times as long 32 bit ints.</dd>
</dl></div>
<a name="r3_4_7_1_9"></a>
<div class="content-level-h5" contains="Dents Pattern" id="r3_4_7_1_9">
<h5>3.4.7.1.9 Dents Pattern</h5>
<p>The <code>dents</code> pattern was originally designed only to be used as
a normal pattern. It is especially interesting when used with metallic
textures. It gives impressions into the metal surface that look like dents
have been beaten into the surface with a hammer. Usually the dents are about
1 unit apart.</p>
<p>When used as a normal pattern, this pattern uses a specialized normal
perturbation function. This means that the pattern cannot be used with <code>
normal_map</code>, <code>slope_map</code> or wave type modifiers in a <code>
normal</code> statement.</p>
<p>When used as a pigment pattern or texture pattern, the <code>dents</code>
pattern is similar to normal dents but is not identical as are most normals
when compared to pigments.</p></div>
<a name="r3_4_7_1_10"></a>
<div class="content-level-h5" contains="Facets Pattern" id="r3_4_7_1_10">
<h5>3.4.7.1.10 Facets Pattern</h5>
<pre>
normal {
facets [coords SCALE_VALUE | size FACTOR]
[NORMAL_ITEMS...]
}
</pre>
<p>The <code>facets</code> pattern is designed to be used as a normal,
it is not suitable for use as a pigment: it will cause an error.
<br> There are two forms of the facets pattern. One is most suited for use with rounded surfaces,
and one is most suited for use with flat surfaces.</p>
<p>If <code>coords</code> is specified, the facets pattern creates facets with a size on the same order
as the specified SCALE_VALUE. This version of facets is most suited for use with flat surfaces, but will
also work with curved surfaces. The boundaries of the facets coincide with the boundaries of the cells in
the standard crackle pattern. The coords version of this pattern may be quite similar to a crackle normal
pattern with solid specified.</p>
<p>If <code>size</code> is specified, the facets texture uses a different function that creates facets
only on curved surfaces. The FACTOR determines how many facets are created, with smaller values
creating more facets, but it is not directly related to any real-world measurement. The same factor
will create the same pattern of facets on a sphere of any size.
<br>This pattern creates facets by snapping normal vectors to the closest vectors in a perturbed grid
of normal vectors. Because of this, if a surface has normal vectors that do not vary along one or more
axes, there will be no facet boundaries along those axes.</p></div>
<a name="r3_4_7_1_11"></a>
<div class="content-level-h5" contains="Fractal Pattern" id="r3_4_7_1_11">
<h5>3.4.7.1.11 Fractal Pattern</h5>
<p>Fractal patterns supported in POV-Ray:</p>
<ul>
<li>The Mandelbrot set with exponents up to 33. The formula for these is: <code>z(n+1) = z(n)^p + c</code>, where <code>p</code> is the correspondent exponent.</li>
<li>The equivalent Julia sets.</li>
<li>The magnet1 and magnet2 fractals (which are derived from some magnetic renormalization transformations; see the fractint help for more details). Both 'Mandelbrot' and 'Julia' versions of them are supported.</li>
</ul>
<p>For the Mandelbrot and Julia sets, higher exponents will be slower for two reasons:</p>
<ol>
<li> For the exponents 2,3 and 4 an optimized algorithm is used. Higher exponents use a generic algorithm for raising a complex number to an integer exponent, and this is a bit slower than an optimized version for a certain exponent.</li>
<li> The higher the exponent, the slower it will be. This is because the amount of operations needed to raise a complex number to an integer exponent is directly proportional to the exponent. This means that exponent 10 will be (very) roughly twice as slow as exponent 5.</li>
</ol>
<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="centered" width="680px" src="images/1/14/RefImgMandelExponents.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Mandelbrot and Julia fractal patterns of exponents 2 to 5</p>
</td>
</tr>
</table>
<p>The syntax is:</p>
<pre>
MANDELBROT:
mandel ITERATIONS [, BUMP_SIZE]
[exponent EXPONENT]
[exterior EXTERIOR_TYPE, FACTOR]
[interior INTERIOR_TYPE, FACTOR]
JULIA:
julia COMPLEX, ITERATIONS [, BUMP_SIZE]
[exponent EXPONENT]
[exterior EXTERIOR_TYPE, FACTOR]
[interior INTERIOR_TYPE, FACTOR]
MAGNET MANDEL:
magnet MAGNET_TYPE mandel ITERATIONS [, BUMP_SIZE]
[exterior EXTERIOR_TYPE, FACTOR]
[interior INTERIOR_TYPE, FACTOR]
MAGNET JULIA:
magnet MAGNET_TYPE julia COMPLEX, ITERATIONS [, BUMP_SIZE]
[exterior EXTERIOR_TYPE, FACTOR]
[interior INTERIOR_TYPE, FACTOR]
</pre>
<p>Where:</p>
<p><code>ITERATIONS</code> is the number of times to iterate (up to 2^32-1) the algorithm.</p>
<p><code>COMPLEX</code> is a 2D vector denoting a complex number.</p>
<p><code>MAGNET_TYPE</code> is either 1 or 2.</p>
<p><code>exponent</code> is an integer between 2 and 33. If not given, the default is 2.</p>
<p><code>interior</code> and <code>exterior</code> specify special coloring algorithms. You can specify one of them or both at the same time. They only work with the fractal patterns.
<br><code>EXTERIOR_TYPE</code> and <code>INTERIOR_TYPE</code> are integer
values between 0 and 6 (inclusive). When not specified, the default value of INTERIOR_TYPE
is 0 and for EXTERIOR_TYPE 1.
<br><code>FACTOR</code> is a float. The return value of the pattern is multiplied by
<code>FACTOR</code> before returning it. This can be used to scale the value range
of the pattern when using interior and exterior coloring (this is often needed to get the
desired effect). The default value of FACTOR is 1.</p>
<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="centered" width="320px" src="images/a/a4/RefImgMagnet.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Magnet mandel and julia type 1 and 2 fractal patterns</p>
</td>
</tr>
</table>
<p>The different values of <code>EXTERIOR_TYPE</code> and <code>INTERIOR_TYPE</code> have the following
meaning:</p>
<ul>
<li>0: Returns just 1</li>
<li>1: For exterior: The number of iterations until bailout divided by ITERATIONS.
<br><p class="Note"><strong>Note:</strong> This is not scaled by FACTOR (since it is internally
scaled by 1/ITERATIONS instead).</p> For interior: The absolute value of the smallest point in the orbit of the calculated point</li>
<li>2: Real part of the last point in the orbit</li>
<li>3: Imaginary part of the last point in the orbit</li>
<li>4: Squared real part of the last point in the orbit</li>
<li>5: Squared imaginary part of the last point in the orbit</li>
<li>6: Absolute value of the last point in the orbit</li>
<li>7: For exterior only: the number of iterations modulo FACTOR and divided by FACTOR.
<br><p class="Note"><strong>Note:</strong> This is of course not scaled by FACTOR. The covered range is 0 to FACTOR-1/FACTOR.</p></li>
<li>8: For exterior only: the number of iterations modulo FACTOR+1 and divided by FACTOR.
<br><p class="Note"><strong>Note:</strong> This is of course not scaled by FACTOR. The covered range is 0 to 1.</p></li>
</ul>
<p>Example:</p>
<pre>
box {<-2, -2, 0>, <2, 2, 0.1>
pigment {
julia <0.353, 0.288>, 30
interior 1, 1
color_map {
[0 rgb 0]
[0.2 rgb x]
[0.4 rgb x+y]
[1 rgb 1]
[1 rgb 0]
}
}
}
</pre>
<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="centered" width="680px" src="images/a/a0/RefImgJuliaColorings.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Different exterior and interior coloring types of fractal patterns</p>
</td>
</tr>
</table></div>
<a name="r3_4_7_1_12"></a>
<div class="content-level-h5" contains="Function Pattern" id="r3_4_7_1_12">
<h5>3.4.7.1.12 Function Pattern</h5>
<p>Allows you to use a function { } block as pattern.</p>
<pre>
pigment {
function { USER_DEFINED_FUNCTIONS }
[PIGMENT_MODIFIERS...]
}
</pre>
<p>Declaring a function:<br>
By default a function takes three parameters (x,y,z) and you do not have
to explicitly specify the parameter names when declaring it. When using
the identifier, the parameters must be specified.</p>
<pre>
#declare Foo = function { x + y + z}
pigment {
function { Foo(x, y, z) }
[PIGMENT_MODIFIERS...]
}
</pre>
<p>On the other hand, if you need more or less than three parameters when
declaring a function, you also have to explicitly specify the parameter
names.</p>
<pre>
#declare Foo = function(x,y,z,t) { x + y + z + t}
pigment {
function { Foo(x, y, z, 4) }
[PIGMENT_MODIFIERS...]
}
</pre>
<p>Using function in a normal:</p>
<pre>
#declare Foo = function { x + y + z}
normal {
function { Foo(x, y, z) } [Bump_Size]
[MODIFIERS...]
}
</pre>
</div>
<a name="r3_4_7_1_12_1"></a>
<div class="content-level-h6" contains="What can be used" id="r3_4_7_1_12_1">
<h6>3.4.7.1.12.1 What can be used</h6>
<p>All float expressions and operators. See the section <a href="r3_3.html#r3_3_1_5_4">User-Defined Functions</a> for what is legal in POV-Ray. Of special interest here is the <code>pattern</code> option, that makes it possible to use patterns as functions</p>
<pre>
#declare FOO = function {
pattern {
checker
}
}
</pre>
<p>User defined functions (like equations).</p>
<p>Since pigments can be declared as functions, they can also be used in
functions. They must be declared first. When using the identifier, you
have to specify which component of the color vector should be used. To
do this, the dot notation is used: Function(x,y,z).red</p>
<pre>
#declare FOO = function {pigment { checker } }
pigment {
function { FOO(x,y,z).green }
[PIGMENT_MODIFIERS...]
}
</pre>
<p>POV-Ray has a large amount of pre-defined functions. These are mainly
algebraic surfaces but there is also a mesh function and noise3d
function. See section <a href="r3_4.html#r3_4_9_1_7">Internal Functions</a> for a complete list and some
explanation on the parameters to use. These internal functions can be
included through the functions.inc include file.</p>
<pre>
#include "functions.inc"
#declare FOO = function {pigment { checker } }
pigment {
function { FOO(x,y,z).green & f_noise3d(x*2, y*3,z)}
[PIGMENT_MODIFIERS...]
}
</pre>
</div>
<a name="r3_4_7_1_12_2"></a>
<div class="content-level-h6" contains="Function Image" id="r3_4_7_1_12_2">
<h6>3.4.7.1.12.2 Function Image</h6>
<p>Syntax :</p>
<code>function Width, Height { FUNCTION_BODY }</code>
<p>Not a real pattern, but listed here for convenience. This keyword defines
a new 'internal' bitmap image type. The pixels of the image are derived
from the Function_Body, with Function_Body either being a regular
function, a pattern function or a pigment function. In case of a pigment
function the output image will be in color, in case of a pattern or regular
function the output image will be grayscale. All variants of grayscale
pigment functions are available using the regular function syntax, too.
In either case the image will use 16 bit per component</p>
<p class="Note"><strong>Note:</strong> Functions are evaluated on the x-y plane. This is different from
the pattern image type for the reason that it makes using uv functions
easier.</p>
<p>Width and Height specify the resolution of the resulting 'internal' bitmap image.
The image is taken from the square region <code><0,0,0>, <1,1,0></code></p>
<p>The <code>function</code> statement can be used wherever an image specifier
like <code>tga</code> or <code>png</code> may be used. Some uses include
creating heightfields from procedural textures or wrapping a slice of a 3d
texture or function around a cylinder or extrude it along an axis.</p>
<p>Examples:</p>
<pre>
plane {y, -1
pigment {
image_map {
function 10,10 {
pigment { checker 1,0 scale .5 }
}
}
rotate x*90
}
}
</pre>
<pre>
height_field {
function 200,200 {
pattern {
bozo
}
}
translate -0.5
scale 10
pigment {rgb 1}
}
</pre>
<p class="Note"><strong>Note:</strong> For height fields and other situations where color is not needed
it is easier to use <code>function n,n {pattern{...}}</code> than <code>function n,n {pigment{...}}</code>.
The pattern functions are returning a scalar, not a color vector, thus a pattern is grayscale.</p></div>
<a name="r3_4_7_1_13"></a>
<div class="content-level-h5" contains="Gradient Pattern" id="r3_4_7_1_13">
<h5>3.4.7.1.13 Gradient Pattern</h5>
<p>One of the simplest patterns is the <code>gradient</code> pattern. It is
specified as</p>
<pre>
pigment {
gradient <Orientation>
[PIGMENT_MODIFIERS...]
}
</pre>
<p>where <em><code><Orientation></code></em> is a vector pointing in
the direction that the colors blend. For example</p>
<pre>
pigment { gradient x } // bands of color vary as you move
// along the "x" direction.
</pre>
<p>produces a series of smooth bands of color that look like layers of colors
next to each other. Points at x=0 are the first color in the color map. As
the x location increases it smoothly turns to the last color at x=1. Then it
starts over with the first again and gradually turns into the last color at
x=2. In POV-Ray versions older than 3.5 the pattern reverses for negative values of x.
As per POV-Ray 3.5 this is not the case anymore. Using <code>gradient
y</code> or <code>gradient z</code> makes the colors blend along the y- or
z-axis. Any vector may be used but x, y and z are most common.</p>
<p>
As a normal pattern, gradient generates a saw-tooth or ramped wave
appearance. The syntax is</p>
<pre>
normal {
gradient <Orientation> [, Bump_Size]
[NORMAL_MODIFIERS...]
}
</pre>
<p>where the vector <em><code><Orientation></code></em> is a required
parameter but the float <em><code>Bump_Size</code></em> which follows is
optional.</p>
<p class="Note"><strong>Note:</strong> The comma is required especially if <em>Bump_Size</em> is
negative.</p>
<p>If only the range -1 to 1 was used of the old gradient, for example in a
<code>sky_sphere</code>, it can be replaced by the <code>planar</code> or <code>marble</code>
pattern and revert the color_map. Also rotate the pattern for other orientations than <code>y</code>.
A more general solution is to use <code>function{abs(x)}</code> as a pattern instead
of <code>gradient x</code> and similar for <code>gradient y</code> and <code>gradient z</code>.</p></div>
<a name="r3_4_7_1_14"></a>
<div class="content-level-h5" contains="Granite Pattern" id="r3_4_7_1_14">
<h5>3.4.7.1.14 Granite Pattern</h5>
<p>The <code>granite</code> pattern uses a simple 1/f fractal noise function
to give a good granite pattern. This pattern is used with creative color maps
in <code>stones.inc</code> to create some gorgeous layered stone
textures.</p>
<p>
As a normal pattern it creates an extremely bumpy surface that looks like a
gravel driveway or rough stone.</p>
<p class="Note"><strong>Note:</strong> The appearance of the granite pattern depends on the noise generator used.
The default type is 2. This may be changed using the <code>noise_generator</code> keyword. See the Pattern Modifiers section: <a href="r3_4.html#r3_4_7_5_4">noise_generator</a>.</p></div>
<a name="r3_4_7_1_15"></a>
<div class="content-level-h5" contains="Leopard Pattern" id="r3_4_7_1_15">
<h5>3.4.7.1.15 Leopard Pattern</h5>
<p>Leopard creates regular geometric pattern of circular spots. The formula
used is: <em> value = Sqr((sin(x)+sin(y)+sin(z))/3)</em></p></div>
<a name="r3_4_7_1_16"></a>
<div class="content-level-h5" contains="Marble Pattern" id="r3_4_7_1_16">
<h5>3.4.7.1.16 Marble Pattern</h5>
<p>The <code>marble</code> pattern is very similar to the <code>gradient
x</code> pattern. The gradient pattern uses a default <code>ramp_wave</code>
wave type which means it uses colors from the color map from 0.0 up to 1.0 at
location x=1 but then jumps back to the first color for x > 1 and repeats
the pattern again and again. However the <code>marble</code> pattern uses
the <code>triangle_wave</code> wave type in which it uses the color map from
0 to 1 but then it reverses the map and blends from 1 back to zero. For
example:</p>
<pre>
pigment {
gradient x
color_map {
[0.0 color Yellow]
[1.0 color Cyan]
}
}
</pre>
<p>This blends from yellow to cyan and then it abruptly changes back to
yellow and repeats. However replacing <code>gradient x</code> with <code>
marble</code> smoothly blends from yellow to cyan as the x coordinate goes
from 0.0 to 0.5 and then smoothly blends back from cyan to yellow by
x=1.0.</p>
<p>
Earlier versions of POV-Ray did not allow you to change wave types. Now that
wave types can be changed for most any pattern, the distinction between
<code>marble</code> and <code>gradient x</code> is only a matter of default
wave types.</p>
<p>
When used with turbulence and an appropriate color map, this pattern looks
like veins of color of real marble, jade or other types of stone. By default,
marble has no turbulence.</p>
<p>The <code>marble</code> pattern has a default color_map built in that results
in a red, black and white pattern with smooth and sharp transitions.</p></div>
<a name="r3_4_7_1_17"></a>
<div class="content-level-h5" contains="Onion Pattern" id="r3_4_7_1_17">
<h5>3.4.7.1.17 Onion Pattern</h5>
<p>The <code>onion</code> is a pattern of concentric spheres like the layers
of an onion. <em> Value = mod(sqrt(Sqr(X)+Sqr(Y)+Sqr(Z)), 1.0)</em> Each
layer is one unit thick.</p></div>
<a name="r3_4_7_1_18"></a>
<div class="content-level-h5" contains="Pavement Pattern" id="r3_4_7_1_18">
<h5>3.4.7.1.18 Pavement Pattern</h5>
<p>The <code>pavement</code> is a pattern which paves the x-z plane with a single polyform tile. A polyform is a plane figure constructed by joining together identical basic polygons. The <code>number_of_sides</code> is used to choose that basic polygon: an equilateral triangle (3), a square (4) or a hexagon (6). The <code>number_of_tiles</code> is used to choose the number of basic polygons in the tile while <code>pattern</code> is used to choose amongst the variants.</p>
<p>The syntax is:</p>
<pre>
pigment {
pavement
[PAVEMENT_MODIFIERS...]
}
PAVEMENT_MODIFIERS:
number_of_sides SIDES_VALUE | number_of_tiles TILES_VALUE | pattern PATTERN_VALUE |
exterior EXTERIOR_VALUE | interior INTERIOR_VALUE | form FORM_VALUE |
PATTERN_MODIFIERS
</pre>
<p>A table of the number of patterns:</p>
<table>
<tr><th rowspan="2"> Sides </th><th colspan="6"><center>Tiles</center></th></tr>
<tr><th>1</th><th>2</th><th>3</th><th>4</th><th> 5</th><th> 6</th></tr>
<tr><th><center>3</center></th><td>1</td><td>1</td><td>1</td><td>3</td><td> 4</td><td>12</td></tr>
<tr><th><center>4</center></th><td>1</td><td>1</td><td>2</td><td>5</td><td>12</td><td>35</td></tr>
<tr><th><center>6</center></th><td>1</td><td>1</td><td>3</td><td>7</td><td>22</td><td> </td></tr>
</table>
<table class="centered" width="650x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="630px" src="images/9/9e/RefImgPavement.png">
</td>
</tr>
<tr>
<td>
<p class="caption">The various patterns with 6 squares.</p>
</td>
</tr>
</table>
<p>There is no nomenclature for pattern, they are just numbered from 1 to the maximum relevant value.</p>
<dl>
<dt><code>form</code></dt>
<dd>0, 1 or 2, a special 3 is allowed for square only which copy the look of <code>interior</code> for some additional variations.</dd>
</dl>
<dl>
<dt><code>interior</code></dt>
<dd>0, 1 or 2</dd>
</dl>
<dl>
<dt><code>exterior</code></dt>
<dd>0, 1 or 2; Not used for hexagon.</dd>
</dl>
<p>The <code>form</code>, <code>exterior</code> and <code>interior</code> specify the look of angle used for respectively slow convex (turning side), quick convex (pointy tile) and concave angle (interior angle between many tiles).</p>
<ul><li>0 is a normal pointy angle. (a right angle for square)</li>
<li>1 is the same as 0, but the pointy angle is broken in two. For square, the two corners are broken so as to share middle angle.</li>
<li>2 is a smooth negotiation of the angle, without pointy part.</li>
</ul>
<p class="Note"><strong>Note: </strong> The case of paving the plane with tiles made of 6 hexagons is not supported because not all such tiles would pave the plane. For example, the ring made of six hexagons is not able to pave the plane.</p></div>
<a name="r3_4_7_1_19"></a>
<div class="content-level-h5" contains="Pigment Pattern" id="r3_4_7_1_19">
<h5>3.4.7.1.19 Pigment Pattern</h5>
<p>Use any pigment as a pattern. Instead of using the pattern directly on the object, a
pigment_pattern converts the pigment to gray-scale first. For each point, the gray-value
is checked against a list and the corresponding item is then used for the texture at
that particular point. For values between listed items, an averaged texture is calculated.
<br>Texture items can be color, pigment, normal or texture and are specified in a
color_map, pigment_map, normal_map or texture_map.
<br>It takes a standard pigment specification.</p>
<p>Syntax:</p>
<pre>
PIGMENT:
pigment {
pigment_pattern { PIGMENT_BODY }
color_map { COLOR_MAP_BODY } |
colour_map { COLOR_MAP_BODY } |
pigment_map { PIGMENT_MAP_BODY }
}
NORMAL:
normal {
pigment_pattern { PIGMENT_BODY } [Bump_Size]
normal_map { NORMAL_MAP_BODY }
}
TEXTURE:
texture {
pigment_pattern { PIGMENT_BODY }
texture_map { TEXTURE_MAP_BODY }
}
ITEM_MAP_BODY:
ITEM_MAP_IDENTIFIER | ITEM_MAP_ENTRY...
ITEM_MAP_ENTRY:
[ GRAY_VALUE ITEM_MAP_ENTRY... ]
</pre>
<p>This pattern is also useful when parent and children patterns need to be
transformed independently from each other. Transforming the pigment_pattern
will not affect the child textures. When any of the child textures should be
transformed, apply it to the specific MAP_ENTRY.</p>
<p>This can be used with any pigments, ranging from a simple checker to very
complicated nested pigments. For example:</p>
<pre>
pigment {
pigment_pattern {
checker White, Black
scale 2
turbulence .5
}
pigment_map {
[ 0, checker Red, Green scale .5 ]
[ 1, checker Blue, Yellow scale .2 ]
}
}
</pre>
<p class="Note"><strong>Note:</strong> This pattern uses a pigment to get the gray values. If you want to
get the pattern from an image, you should use the <a href="r3_4.html#r3_4_7_4_2">image_pattern</a>.</p></div>
<a name="r3_4_7_1_20"></a>
<div class="content-level-h5" contains="Planar Pattern" id="r3_4_7_1_20">
<h5>3.4.7.1.20 Planar Pattern</h5>
<p>The <code>planar</code> pattern creates a horizontal stripe plus or minus
one unit above and below the X-Z plane. It is computed by: <em> value =1.0-
min(1, abs(Y))</em> It starts at 1.0 at the origin and decreases to a minimum
value of 0.0 as the Y values approaches a distance of 1 unit from the X-Z
plane. It remains at 0.0 for all areas beyond that distance. This pattern was
originally created for use with <code>halo</code> or <code>media</code> but
it may be used anywhere any pattern may be used.</p></div>
<a name="r3_4_7_1_21"></a>
<div class="content-level-h5" contains="Quilted Pattern" id="r3_4_7_1_21">
<h5>3.4.7.1.21 Quilted Pattern</h5>
<p>The <code>quilted</code> pattern was originally designed only to be used
as a normal pattern. The quilted pattern is so named because it can create a
pattern somewhat like a quilt or a tiled surface. The squares are actually
3-D cubes that are 1 unit in size.</p>
<p>
When used as a normal pattern, this pattern uses a specialized normal
perturbation function. This means that the pattern cannot be used with <code>
normal_map</code>, <code>slope_map</code> or wave type modifiers in a <code>
normal</code> statement.</p>
<p>
When used as a pigment pattern or texture pattern, the <code>quilted</code>
pattern is similar to normal quilted but is not identical as are most normals
when compared to pigments.</p>
<p>
The two parameters <code>control0</code> and <code>control1</code> are used
to adjust the curvature of the <em>seam</em> or <em>gouge</em> area between
the <code>quilts</code>.</p>
<p>
The syntax is:</p>
<pre>
pigment {
quilted
[QUILTED_MODIFIERS...]
}
QUILTED_MODIFIERS:
control0 Value_0 | control1 Value_1 | PIGMENT_MODIFIERS
</pre>
<p>The values should generally be kept to around the 0.0 to 1.0 range. The
default value is 1.0 if none is specified. Think of this gouge between the
tiles in cross-section as a sloped line.</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/7/7d/RefImgQuiltpt1.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Quilted pattern with c0=0 and different values for c1.</p>
</td>
</tr>
</table>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/b/b1/RefImgQuiltpt2.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Quilted pattern with c0=0.33 and different values for c1.</p>
</td>
</tr>
</table>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/c/c8/RefImgQuiltpt3.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Quilted pattern with c0=0.67 and different values for c1.</p>
</td>
</tr>
</table>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/e/e9/RefImgQuiltpt4.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">Quilted pattern with c0=1 and different values for c1.</p>
</td>
</tr>
</table>
<p>This straight slope can be made to curve by adjusting the two control
values. The control values adjust the slope at the top and bottom of the
curve. A control values of 0 at both ends will give a linear slope, as shown
above, yielding a hard edge. A control value of 1 at both ends will give an
"s" shaped curve, resulting in a softer, more rounded edge.</p>
<p>The syntax for use as a normal is:</p>
<pre>
normal {
quilted [Bump_Size]
[QUILTED_MODIFIERS...]
}
QUILTED_MODIFIERS:
control0 Value_0 | control1 Value_1 | PIGMENT_MODIFIERS
</pre></div>
<a name="r3_4_7_1_22"></a>
<div class="content-level-h5" contains="Radial Pattern" id="r3_4_7_1_22">
<h5>3.4.7.1.22 Radial Pattern</h5>
<p>The <code>radial</code> pattern is a radial blend that wraps around the
+y-axis. The color for value 0.0 starts at the +x-direction and wraps the
color map around from east to west with 0.25 in the -z-direction, 0.5 in -x,
0.75 at +z and back to 1.0 at +x. Typically the pattern is used with a <code>
frequency</code> modifier to create multiple bands that radiate from the
y-axis. For example:</p>
<pre>
pigment {
radial
color_map {
[0.5 Black]
[0.5 White]
}
frequency 10
}
</pre>
<p>creates 10 white bands and 10 black bands radiating from the y axis.</p>
<p>The <code>radial</code> pattern has a default color_map built in that results
in a yellow, magenta and cyan pattern with smooth transitions.</p></div>
<a name="r3_4_7_1_23"></a>
<div class="content-level-h5" contains="Ripples Pattern" id="r3_4_7_1_23">
<h5>3.4.7.1.23 Ripples Pattern</h5>
<p>The <code>ripples</code> pattern was originally designed only to be used
as a normal pattern. It makes the surface look like ripples of water. The
ripples radiate from 10 random locations inside the unit cube area
<0,0,0> to <1,1,1>. Scale the pattern to make the centers closer
or farther apart.</p>
<p>
Usually the ripples from any given center are about 1 unit apart. The <code>
frequency</code> keyword changes the spacing between ripples. The <code>
phase</code> keyword can be used to move the ripples outwards for realistic
animation.</p>
<p>
The number of ripple centers can be changed with the global parameter</p>
<pre>
global_settings { number_of_waves Count }
</pre>
<p>somewhere in the scene. This affects the entire scene. You cannot change the number of wave centers on individual patterns. See the section <a href="r3_4.html#r3_4_1_10">Number Of Waves</a> for details.</p>
<p>When used as a normal pattern, this pattern uses a specialized normal
perturbation function. This means that the pattern cannot be used with <code>
normal_map</code>, <code>slope_map</code> or wave type modifiers in a <code>normal</code> statement.</p>
<p>When used as a pigment pattern or texture pattern, the <code>ripples</code>
pattern is similar to normal ripples but is not identical as are most normals
when compared to pigments.</p></div>
<a name="r3_4_7_1_24"></a>
<div class="content-level-h5" contains="Spherical Pattern" id="r3_4_7_1_24">
<h5>3.4.7.1.24 Spherical Pattern</h5>
<p>The <code>spherical</code> pattern creates a one unit radius sphere, with its center at
the origin. It is computed by: <em> value = 1.0-min(1, sqrt(X^2 + Y^2 +
Z^2))</em> It starts at 1.0 at the origin and decreases to a minimum value of 0.0
as it approaches a distance of 1 unit from the origin in any direction. It
remains at 0.0 for all areas beyond that distance. This pattern was
originally created for use with <code>halo</code> or <code>media</code> but
it may be used anywhere any pattern may be used.</p></div>
<a name="r3_4_7_1_25"></a>
<div class="content-level-h5" contains="Spiral1 Pattern" id="r3_4_7_1_25">
<h5>3.4.7.1.25 Spiral1 Pattern</h5>
<p>The <code>spiral1</code> pattern creates a spiral that winds around the
z-axis similar to a screw. When viewed sliced in the x-y plane, it looks like
the spiral arms of a galaxy. Its syntax is:</p>
<pre>
pigment {
spiral1 Number_of_Arms
[PIGMENT_MODIFIERS...]
}
</pre>
<p>The <em><code>Number_of_Arms</code></em> value determines how may arms are
winding around the z-axis.</p>
<p>
As a normal pattern, the syntax is</p>
<pre>
normal {
spiral1 Number_of_Arms [, Bump_Size]
[NORMAL_MODIFIERS...]
}
</pre>
<p>where the <code>Number_of_Arms</code> value is a required
parameter but the float <em><code>Bump_Size</code></em> which follows is
optional. </p>
<p class="Note"><strong>Note:</strong> The comma is required especially if <em>Bump_Size</em> is
negative.</p>
<p>The pattern uses the <code>triangle_wave</code> wave type by default but may
use any wave type.</p></div>
<a name="r3_4_7_1_26"></a>
<div class="content-level-h5" contains="Spiral2 Pattern" id="r3_4_7_1_26">
<h5>3.4.7.1.26 Spiral2 Pattern</h5>
<p>The <code>spiral2</code> pattern creates a double spiral that winds around
the z-axis similar to <code>spiral1</code> except that it has two overlapping spirals
which twist in opposite directions. The result sometimes looks like a basket
weave or perhaps the skin of pineapple. The center of a sunflower also has a
similar double spiral pattern. Its syntax is:</p>
<pre>
pigment {
spiral2 Number_of_Arms
[PIGMENT_MODIFIERS...]
}
</pre>
<p>The <em><code>Number_of_Arms</code></em> value determines how may arms are
winding around the z-axis. As a normal pattern, the syntax is</p>
<pre>
normal {
spiral2 Number_of_Arms [, Bump_Size]
[NORMAL_MODIFIERS...]
}
</pre>
<p>where the <code>Number_of_Arms</code> value is a required
parameter but the float <em><code>Bump_Size</code></em> which follows is
optional.</p>
<p class="Note"><strong>Note:</strong> The comma is required especially if <em>Bump_Size</em> is negative. The pattern uses the <code>triangle_wave</code> wave type by default but may use any wave type.</p></div>
<a name="r3_4_7_1_27"></a>
<div class="content-level-h5" contains="Spotted Pattern" id="r3_4_7_1_27">
<h5>3.4.7.1.27 Spotted Pattern</h5>
<p>The <code>spotted</code> pattern is identical to the <code>bozo</code>
pattern. Early versions of POV-Ray did not allow turbulence to be used with
spotted. Now that any pattern can use turbulence there is no difference
between <code>bozo</code> and <code>spotted</code>. See the section <a href="r3_4.html#r3_4_7_1_3">Bozo</a> for details.</p></div>
<a name="r3_4_7_1_28"></a>
<div class="content-level-h5" contains="Tiling Pattern" id="r3_4_7_1_28">
<h5>3.4.7.1.28 Tiling Pattern</h5>
<p>The <code>tiling</code> pattern creates a series tiles in the x-z plane. See the image below for examples of the twenty-seven available patterns.</p>
<p>The syntax is as follows:</p>
<pre>
pigment {
tiling Pattern_Number
[PATTERN_MODIFIERS...]
}
</pre>
<table class="centered" width="580px" cellpadding="0" cellspacing="10">
<tr>
<td><img class="centered" width="560px" src="images/d/d0/RefImgTiling2.gif"></td>
</tr>
<tr>
<td><p class="caption">The various tiling patterns annotated by tiling pattern and tiling type respectively</p></td>
</tr>
</table>
<p>For each pattern, each individual tile of the pattern has the same beveling as the other tiles in that pattern, allowing regular caulking to be defined. For a pattern with N tile types (where N is the tiling type noted in the above image) the main color/texture of the tiles are at x/N with x going from 0 to N-1, and the extreme color/texture caulk for these tiles are at (x+1)/N. The bevel covers the range between these two values.</p>
<p>To begin exploring the <code>tiling</code> pattern right away, see the distribution file <code>~scenes/textures/pattern/tiling.pov</code>. It uses obvious colors to better illustrate how the feature works, and you can optionally write it's <code>color_map</code> to a text file. Once you get a feel for the break points, you can always define you own map!</p></div>
<a name="r3_4_7_1_29"></a>
<div class="content-level-h5" contains="Waves Pattern" id="r3_4_7_1_29">
<h5>3.4.7.1.29 Waves Pattern</h5>
<p>The <code>waves</code> pattern was originally designed only to be used as
a normal pattern. It makes the surface look like waves on water. The <code>
waves</code> pattern looks similar to the <code>ripples</code> pattern except
the features are rounder and broader. The effect is to make waves that look
more like deep ocean waves. The waves radiate from 10 random locations inside
the unit cube area <0,0,0> to <1,1,1>. Scale the pattern to make
the centers closer or farther apart.</p>
<p>Usually the waves from any given center are about 1 unit apart. The <code>
frequency</code> keyword changes the spacing between waves. The <code>
phase</code> keyword can be used to move the waves outwards for realistic
animation.</p>
<p>The number of wave centers can be changed with the global parameter</p>
<pre>
global_settings { number_of_waves Count }
</pre>
<p>somewhere in the scene. This affects the entire scene. You cannot change the number of wave centers on individual patterns. See the section <a href="r3_4.html#r3_4_1_10">Number Of Waves</a> for details.</p>
<p>When used as a normal pattern, this pattern uses a specialized normal
perturbation function. This means that the pattern cannot be used with <code>
normal_map</code>, <code>slope_map</code> or wave type modifiers in a <code>normal</code> statement.</p>
<p>When used as a pigment pattern or texture pattern, the <code>waves</code>
pattern is similar to normal waves but is not identical as are most normals
when compared to pigments.</p></div>
<a name="r3_4_7_1_30"></a>
<div class="content-level-h5" contains="Wood Pattern" id="r3_4_7_1_30">
<h5>3.4.7.1.30 Wood Pattern</h5>
<p>The <code>wood</code> pattern consists of concentric cylinders centered on
the z-axis. When appropriately colored, the bands look like the growth rings
and veins in real wood. Small amounts of turbulence should be added to make
it look more realistic. By default, wood has no turbulence.</p>
<p>Unlike most patterns, the <code>wood</code> pattern uses the <code>
triangle_wave</code> wave type by default. This means that like marble, wood
uses color map values 0.0 to 1.0 then repeats the colors in reverse order
from 1.0 to 0.0. However you may use any wave type.</p>
<p>The <code>wood</code> pattern has a default color_map built in that results
in a light and dark brown pattern with sharp transitions.</p></div>
<a name="r3_4_7_1_31"></a>
<div class="content-level-h5" contains="Wrinkles Pattern" id="r3_4_7_1_31">
<h5>3.4.7.1.31 Wrinkles Pattern</h5>
<p>The <code>wrinkles</code> pattern was originally designed only to be used
as a normal pattern. It uses a 1/f noise pattern similar to granite but the
features in wrinkles are sharper. The pattern can be used to simulate
wrinkled cellophane or foil. It also makes an excellent stucco texture.</p>
<p>When used as a normal pattern, this pattern uses a specialized normal
perturbation function. This means that the pattern cannot be used with <code>
normal_map</code>, <code>slope_map</code> or wave type modifiers in a <code>
normal</code> statement.</p>
<p>When used as a pigment pattern or texture pattern, the <code>wrinkles</code>
pattern is similar to normal wrinkles but is not identical as are most
normals when compared to pigments.</p>
<p class="Note"><strong>Note:</strong> The appearance of the wrinkles pattern depends on the noise generator used.
The default type is 2. This may be changed using the <code>noise_generator</code> keyword. See the section Pattern Modifiers: <a href="r3_4.html#r3_4_7_5_4">noise_generator</a>.</p></div>
<a name="r3_4_7_2"></a>
<div class="content-level-h4" contains="Discontinuous Patterns" id="r3_4_7_2">
<h4>3.4.7.2 Discontinuous Patterns</h4>
<p>Some patterns are discontinuous, meaning their slope is infinite. These patterns are not suitable for use as object norms, as objects with discontinuous norms may look odd. These patterns work best for textures and media. They are <code>cells</code>, <code>checker</code>, <code>crackle</code>, <code>hexagon</code>, <code>object</code>, <code>square</code> and <code>triangular</code>.</p>
<p class="Note"><strong>Note:</strong> The cell and crackle patterns are mixed cases, that is, they are discontinuous at their respective boundaries. However, there is no limit to the different number of values, in the range of 0 to 1, that they can generate.</p></div>
<a name="r3_4_7_2_1"></a>
<div class="content-level-h5" contains="Cells Pattern" id="r3_4_7_2_1">
<h5>3.4.7.2.1 Cells Pattern</h5>
<p>The <code>cells</code> pattern fills 3d space with unit cubes. Each cube gets a
random value from 0 to 1.</p>
<p><code>cells</code> is not very suitable as a normal as it has no smooth
transitions of one grey value to another.</p></div>
<a name="r3_4_7_2_2"></a>
<div class="content-level-h5" contains="Checker Pattern" id="r3_4_7_2_2">
<h5>3.4.7.2.2 Checker Pattern</h5>
<p>The <code>checker</code> pattern produces a checkered pattern consisting
of alternating squares of two colors. The syntax is:</p>
<pre>
pigment { checker [COLOR_1 [, COLOR_2]] [PATTERN_MODIFIERS...] }
</pre>
<p>If no colors are specified then default blue and green colors are
used.</p>
<p>
The checker pattern is actually a series of cubes that are one unit in size.
Imagine a bunch of 1 inch cubes made from two different colors of modeling
clay. Now imagine arranging the cubes in an alternating check pattern and
stacking them in layer after layer so that the colors still alternate in
every direction. Eventually you would have a larger cube. The pattern of
checks on each side is what the POV-Ray checker pattern produces when applied
to a box object. Finally imagine cutting away at the cube until it is carved
into a smooth sphere or any other shape. This is what the checker pattern
would look like on an object of any kind.</p>
<p>
You may also use pigment statements in place of the colors. For example:</p>
<pre>
pigment { checker pigment{Jade}, pigment{Black_Marble} }
</pre>
<p>This example uses normals:</p>
<pre>
normal { checker 0.5 }
</pre>
<p>The float value is an optional bump size. You may also use full normal
statements. For example:</p>
<pre>
normal {
checker normal{gradient x scale .2}, normal{gradient y scale .2}
}
</pre>
<p>When used with textures, the syntax is</p>
<pre>
texture { checker texture{T_Wood_3A}, texture{Stone12} }
</pre>
<p>The <code>checker</code> pattern has a default color_map built in that
results in blue and green tiles.</p>
<p>This use of checker as a texture pattern replaces the special tiles
texture in previous versions of POV-Ray. You may still use <code>
tiles</code> but it may be phased out in future versions so checker textures
are best.</p>
<p>
This is a block pattern which cannot use wave types, <code>
color_map</code>, or <code>slope_map</code> modifiers.</p></div>
<a name="r3_4_7_2_3"></a>
<div class="content-level-h5" contains="Crackle Pattern" id="r3_4_7_2_3">
<h5>3.4.7.2.3 Crackle Pattern</h5>
<p>The <code>crackle</code> pattern is a set of random tiled multifaceted cells. The crackle pattern is only semi-procedural, requiring random values to be computed and cached for subsequent queries, with a fixed amount of data per unit-cube in crackle pattern coordinate space. Scaled smaller than the density of actual ray-object-intersections computed, it will eventually lead to a separate crackle cache entry being created for each and every intersection. After the cache reaches a certain size (currently 30mb per thread), new entries for that particular block will be discarded after they are calculated. Starting a new block will allow the caching to resume working again. While discarding the data is of course inefficient, it's still preferable to chewing up 100% of the available physical RAM and then hitting the swap-file.</p>
<p>There is a choice between different types:</p>
<p><strong>Standard Crackle</strong></p>
<p>Mathematically, the set crackle(p)=0 is a 3D Voronoi diagram of a field of semi random points and crackle(p) < 0 is the distance from the set along the shortest path (a Voronoi diagram is the locus of points equidistant from their two nearest neighbors from a set of disjoint points, like the membranes in suds are to the centers of the bubbles).</p>
<ul>
<li>With a large scale and no turbulence it makes a pretty good stone wall or floor.</li>
<li>With a small scale and no turbulence it makes a pretty good crackle ceramic glaze.</li>
<li>Using high turbulence it makes a good marble that avoids the problem of apparent
parallel layers in traditional marble.</li>
</ul>
<p><strong>Form</strong></p>
<pre>
pigment {
crackle form <FORM_VECTOR>
[PIGMENT_ITEMS ...]
}
normal {
crackle [Bump_Size]
form <FORM_VECTOR>
[NORMAL_ITEMS ...]
}
</pre>
<p>Form determines the linear combination of distances used to create the pattern. Form is a vector.</p>
<ul>
<li>The first component determines the multiple of the distance to the closest point to be used in determining the value of the pattern at a particular point.</li>
<li>The second component determines the coefficient applied to the second-closest distance.</li>
<li>The third component corresponds to the third-closest distance.</li>
</ul>
<p>The standard form is <-1,1,0> (also the default), corresponding to the difference in the distances to the closest and second-closest points in the cell array. Another commonly-used form is <1,0,0>, corresponding to the distance to the closest point, which produces a pattern that looks roughly like a random collection of intersecting spheres or cells.</p>
<ul>
<li>Other forms can create very interesting effects, but it is best to keep the sum of the coefficients low.</li>
<li>If the final computed value is too low or too high, the resultant pigment will be saturated with the color at the low or high end of the <code>color_map</code>. In this case, try multiplying the form vector by a constant.</li>
</ul>
<p><strong>Metric</strong></p>
<pre>
pigment {
crackle metric METRIC_VALUE
[PIGMENT_ITEMS ...]
}
normal {
crackle [Bump_Size]
metric METRIC_VALUE
[NORMAL_ITEMS ...]
}
</pre>
<p>Changing the metric changes the function used to determine which cell center is closer, for purposes of determining which cell a particular point falls in. The standard Euclidean distance function has a metric of 2. Changing the metric value changes the boundaries of the cells. A metric value of 3, for example, causes the boundaries to curve, while a very large metric constrains the boundaries to a very small set of possible orientations.</p>
<ul>
<li>The default for metric is 2, as used by the standard crackle texture.</li>
<li>Metrics other than 1 or 2 can lead to substantially longer render times, as the method used to calculate such metrics is not as efficient.</li>
</ul>
<p><strong>Offset</strong></p>
<pre>
pigment {
crackle offset OFFSET_VALUE
[PIGMENT_ITEMS ...]
}
normal {
crackle [Bump_Size]
offset OFFSET_VALUE
[NORMAL_ITEMS ...]
}
</pre>
<p>The offset is used to displace the pattern from the standard xyz space along a fourth dimension.</p>
<ul>
<li>It can be used to round off the <em>pointy</em> parts of a cellular normal texture or procedural heightfield by keeping the distances from becoming zero.</li>
<li>It can also be used to move the calculated values into a specific range if the result is saturated at one end of the color_map.</li>
<li>The default offset is zero.</li>
</ul>
<p><strong>Solid</strong></p>
<pre>
pigment {
crackle solid
[PIGMENT_ITEMS ...]
}
normal {
crackle [Bump_Size]
solid
[NORMAL_ITEMS ...]
}
</pre>
<p>Causes the same value to be generated for every point within a specific cell. This has practical applications in making easy stained-glass windows or flagstones. There is no provision for mortar, but mortar may be created by layering or texture-mapping a
standard crackle texture with a solid one. The default for this parameter is off.</p></div>
<a name="r3_4_7_2_4"></a>
<div class="content-level-h5" contains="Hexagon Pattern" id="r3_4_7_2_4">
<h5>3.4.7.2.4 Hexagon Pattern</h5>
<p>The <code>hexagon</code> pattern is a block pattern that generates a
repeating pattern of hexagons in the x-z-plane. In this instance imagine tall
rods that are hexagonal in shape and are parallel to the y-axis and grouped
in bundles like shown in the example image. Three separate colors should be
specified as follows:</p>
<pre>
pigment {
hexagon [COLOR_1 [, COLOR_2 [, COLOR_3]]]
[PATTERN_MODIFIERS...]
}
</pre>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<img class="center" width="640px" src="images/5/5b/RefImgHexpat.gif">
</td>
</tr>
<tr>
<td>
<p class="caption">The hexagon pattern.</p>
</td>
</tr>
</table>
<p>The three colors will repeat the hexagonal pattern with hexagon <em>
COLOR_1</em> centered at the origin, <em>COLOR_2</em> in the +z-direction and
<em>COLOR_3</em> to either side. Each side of the hexagon is one unit long.
The hexagonal rods of color extend infinitely in the +y- and -y-directions.
If no colors are specified then default blue, green and red colors are
used.</p>
<p>
You may also use pigment statements in place of the colors. For example:</p>
<pre>
pigment {
hexagon
pigment { Jade },
pigment { White_Marble },
pigment { Black_Marble }
}
</pre>
<p>This example uses normals:</p>
<pre>
normal { hexagon 0.5 }
</pre>
<p>The float value is an optional bump size. You may also use full normal
statements. For example:</p>
<pre>
normal {
hexagon
normal { gradient x scale .2 },
normal { gradient y scale .2 },
normal { bumps scale .2 }
}
</pre>
<p>When used with textures, the syntax is...</p>
<pre>
texture {
hexagon
texture { T_Gold_3A },
texture { T_Wood_3A },
texture { Stone12 }
}
</pre>
<p>The <code>hexagon</code> pattern has a default color_map built in that results
in red, blue and green tiles.</p>
<p>This is a block pattern which cannot use wave types, <code>
color_map</code>, or <code>slope_map</code> modifiers.</p></div>
<a name="r3_4_7_2_5"></a>
<div class="content-level-h5" contains="Object Pattern" id="r3_4_7_2_5">
<h5>3.4.7.2.5 Object Pattern</h5>
<p>The <code>object</code> pattern takes an object as input. It generates a, two item,
color list pattern. Whether a point is assigned to one item or the other depends on
whether it is inside the specified object or not. </p>
<p>Object's used in the <code>object</code> pattern cannot have a texture and must
be solid - these are the same limitations as for <code>bounded_by</code> and
<code>clipped_by</code>.</p>
<p>Syntax:</p>
<pre>
object {
OBJECT_IDENTIFIER | OBJECT {}
LIST_ITEM_A, LIST_ITEM_B
}
</pre>
<p>Where OBJ_IDENTIFIER is the target object (which must be declared), or use the
full object syntax. LIST_ITEM_A and LIST_ITEM_B are the colors, pigments, or whatever
the pattern is controlling. LIST_ITEM_A is used for all points outside the object,
and LIST_ITEM_B is used for all points inside the object.</p>
<p>Example:</p>
<pre>
pigment {
object {
myTextObject
color White
color Red
}
turbulence 0.15
}
</pre>
<p class="Note"><strong>Note:</strong> This is a block pattern which <em>cannot</em> use wave types, <code>color_map</code>, or <code>slope_map</code> modifiers.</p></div>
<a name="r3_4_7_2_6"></a>
<div class="content-level-h5" contains="Square Pattern" id="r3_4_7_2_6">
<h5>3.4.7.2.6 Square Pattern</h5>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td width="200px">
<img class="left" width="200px" src="images/4/4c/RefImgSquare.png">
</td>
<td>
<p>The <code>square</code> pattern is a block pattern that generates a repeating pattern of squares in the x-z plane. In this instance imagine tall rods that are square in shape and are parallel to the y-axis and grouped in bundles like shown in the example image. Four separate colors should be specified as follows:</p>
</td>
</tr>
<tr>
<td>
<p class="caption">The square pattern.</p>
</td>
<td></td>
</tr>
</table>
<pre>
pigment {
square [COLOR_1 [, COLOR_2 [, COLOR_3 [, COLOR_4]]]]
[PATTERN_MODIFIERS...]
}
</pre>
<p>Each side of the square is one unit long. The square rods of color extend infinitely in the +y and -y directions. If no colors are specified then default blue, green, red and yellow colors are used.</p>
<p>
You may also use pigment statements in place of the colors. For example:</p>
<pre>
pigment {
square
pigment { Aquamarine },
pigment { Turquoise },
pigment { Sienna },
pigment { SkyBlue }
}
</pre>
<p>When used with textures, the syntax is...</p>
<pre>
texture {
square
texture{ T_Wood1 },
texture{ T_Wood2 },
texture{ T_Wood4 },
texture{ T_Wood8 }
}
</pre>
<p>The <code>square</code> pattern has a default color map built in that results in red, blue, yellow and green tiles.</p>
<p>This is a block pattern so, use of wave types, <code>color_map</code>, or <code>slope_map</code> modifiers is <em>not</em> allowed.</p></div>
<a name="r3_4_7_2_7"></a>
<div class="content-level-h5" contains="Triangular Pattern" id="r3_4_7_2_7">
<h5>3.4.7.2.7 Triangular Pattern</h5>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td width="200px">
<img class="right" width="200px" src="images/6/64/RefImgTriangular.png">
</td>
<td>
<p>The <code>triangular</code> pattern is a block pattern that generates a repeating pattern of triangles in the x-z plane. In this instance imagine tall rods that are triangular in shape and are parallel to the y-axis and grouped in bundles like shown in the example image. Six separate colors should be specified as follows:</p>
</td>
</tr>
<tr>
<td>
<p class="caption">The triangular pattern.</p>
</td>
<td></td>
</tr>
</table>
<pre>
pigment {
triangular [COLOR_1 [, COLOR_2 [, COLOR_3 [, COLOR_4 [, COLOR_5 [, COLOR_6]]]]]]
[PATTERN_MODIFIERS...]
}
</pre>
<p>Each side of the triangle is one unit long. The triangular rods of color extend infinitely in the +y and -y directions. If no colors are specified then default blue, green, red, magenta, cyan and yellow colors are used.</p>
<p>
You may also use pigment statements in place of the colors. For example:</p>
<pre>
pigment {
triangular
pigment { Aquamarine },
pigment { Turquoise },
pigment { Sienna },
pigment { Aquamarine },
pigment { Turquoise },
pigment { SkyBlue }
}
</pre>
<p>When used with textures, the syntax is...</p>
<pre>
texture {
triangular
texture{ T_Wood1 },
texture{ T_Wood2 },
texture{ T_Wood4 },
texture{ T_Wood8 },
texture{ T_Wood16 },
texture{ T_Wood10 }
}
</pre>
<p>The <code>triangular</code> pattern has a default color map built in that results in red, blue, cyan, magenta, yellow and green tiles.</p>
<p>This is a block pattern so, use of wave types, <code>color_map</code>, or <code>slope_map</code> modifiers is <em>not</em> allowed.</p></div>
<a name="r3_4_7_3"></a>
<div class="content-level-h4" contains="Normal-Dependent Patterns" id="r3_4_7_3">
<h4>3.4.7.3 Normal-Dependent Patterns</h4>
<p>Some patterns depend on the normal vector in addition to a position vector. As such, these patterns are suitable for object normals only. They are <code>aoi</code> and <code>slope</code>.</p></div>
<a name="r3_4_7_3_1"></a>
<div class="content-level-h5" contains="Aoi Pattern" id="r3_4_7_3_1">
<h5>3.4.7.3.1 Aoi Pattern</h5>
<p>The <code>aoi</code> pattern can be used with <code>pigment</code>, <code>normal</code> and <code>texture</code> statements. The syntax is as follows:</p>
<pre>
pigment {
aoi
pigment_map {
[0.0 MyPigmentA]
...
[1.0 MyPigmentZ]
}
}
normal {
aoi
normal_map {
[0.0 MyNormalA]
...
[1.0 MyNormalZ]
}
}
texture {
aoi
texture_map {
[0.0 MyTextureA]
...
[1.0 MyTextureZ]
}
}
</pre>
<p>It gives a value proportional to the angle between the ray and the surface; for consistency with the slope pattern, values range from 0.5 where ray is tangent to the surface, to 1.0 where perpendicular; in practice, values below 0.5 may occur in conjunction with smooth triangles or meshes.</p>
<p class="Note"><strong>Note:</strong> This differs from the current MegaPOV implementation, where the values range from 0.5 down to 0.0 instead. If compatibility with MegaPOV is desired, it is recommended to mirror the gradient at 0.5, e.g.:</p>
<pre>
pigment {
aoi
pigment_map {
[0.0 MyPigment3]
[0.2 MyPigment2]
[0.5 MyPigment1]
[0.8 MyPigment2]
[1.0 MyPigment3]
}
}
</pre></div>
<a name="r3_4_7_3_2"></a>
<div class="content-level-h5" contains="Slope Pattern" id="r3_4_7_3_2">
<h5>3.4.7.3.2 Slope Pattern</h5>
<p>The <code>slope</code> pattern uses the normal of a surface to calculate the slope
at a given point. It then creates the pattern value dependent on the slope and optionally
the altitude. It can be used for pigments, normals and textures, but not for media densities.For pigments the syntax is:</p>
<pre>
pigment {
slope {
<Direction> [, Lo_slope, Hi_slope ]
[ altitude <Altitude> [, Lo_alt, Hi_alt ]]
}
[PIGMENT_MODIFIERS...]
}
</pre>
<p>The slope value at a given point is dependent on the angle between the <code><Direction></code> vector and the normal of the surface at that point.</p>
<p>For example:</p>
<ul>
<li> When the surface normal points in the opposite direction of the <code><Direction></code> vector (180 degrees), the slope is 0.0.</li>
<li> When the surface normal is perpendicular to the <code><Direction></code> vector (90 degrees), the slope is 0.5.</li>
<li> When the surface normal is parallel to the <code><Direction></code> vector (0 degrees), the slope is 1.0.</li>
</ul>
<p>When using the simplest variant of the syntax:</p>
<pre>
slope { <Direction> }
</pre>
<p>the pattern value for a given point is the same as the slope value. <code><Direction></code> is a 3-D vector and will usually be <code><0,-1,0></code> for landscapes, but any direction can be used.</p>
<p>By specifying <code>Lo_slope</code> and <code>Hi_slope</code> you get more control:</p>
<pre>
slope { <Direction>, Lo_slope, Hi_slope }
</pre>
<p><code>Lo_slope</code> and <code>Hi_slope</code> specifies which range of slopes are used, so you can control which slope values return which pattern values. <code>Lo_slope</code> is the slope value that returns 0.0 and <code>Hi_slope</code> is the slope value that returns 1.0.</p>
<p>For example, if you have a height_field and <code><Direction></code> is set to <code><0,-1,0></code>, then the slope values would only range from 0.0 to 0.5 because height_fields cannot have overhangs. If you do not specify <code>Lo_slope</code> and <code>Hi_slope</code>, you should keep in mind that the texture for the flat (horizontal) areas must be set at 0.0 and the texture for the steep (vertical) areas at 0.5 when designing the texture_map. The part from 0.5 up to 1.0 is not used then. But, by setting <code>Lo_slope</code> and <code>Hi_slope</code> to 0.0 and 0.5 respectively, the slope range will be stretched over the entire map, and the texture_map can then be defined from 0.0 to 1.0.</p>
<p>By adding an optional <code><Altitude></code> vector:</p>
<pre>
slope {
<Direction>
altitude <Altitude>
}
</pre>
<p>the pattern will be influenced not only by the slope but also by a special gradient. <code><Altitude></code> is a 3-D vector that specifies the direction of the gradient. When <code><Altitude></code> is specified, the pattern value is a weighted average of the slope value and the gradient value. The weights are the lengths of the vectors <code><Direction></code> and <code><Altitude></code>. So if <code><Direction></code> is much longer than <code><Altitude></code> it means that the slope has greater effect on the results than the gradient. If on the other hand <code><Altitude></code> is longer, it means that the gradient has more effect on the results than the slope.</p>
<p>When adding the <code><Altitude></code> vector, the default gradient is defined from 0 to 1 units along the specified axis. This is fine when your object is defined within this range, otherwise a correction is needed. This can be done with the optional <code>Lo_alt</code> and <code>Hi_alt</code> parameters:</p>
<pre>
slope {
<Direction>
altitude <Altitude>, Lo_alt, Hi_alt
}
</pre>
<p>They define the range of the gradient along the axis defined by the <Altitude> vector.</p>
<p>For example, with an <code><Altitude></code> vector set to y and an object going from -3 to 2 on
the y axis, the <code>Lo_alt</code> and <code>Hi_alt</code> parameters should be set to -3 and 2 respectively.</p>
<p class="Note"><strong>Note:</strong> You should be aware of the following pitfalls when using the <code>slope</code> pattern.</p>
<ul>
<li>You may use the turbulence keyword inside slope pattern definitions but it may cause unexpected results. Turbulence is a 3-D distortion of a pattern. Since slope is only defined on surfaces of objects, a 3-D turbulence is not applicable to the slope component. However, if you are using altitude, the altitude component of the pattern will be affected by turbulence.</li>
<li>If your object is larger than the range of altitude you have specified, you may experience unexpected discontinuities. In that case it is best to adjust the <code>Lo_alt</code> and <code>Hi_alt</code> values so they fit to your object.</li>
<li>The slope pattern does not work for the sky_sphere, because the sky_sphere is a background feature and does not have a surface. similarly, it does not work for media densities.</li>
</ul>
<p>As of version 3.7 the <code>slope</code> pattern has been extended to specify a reference point instead of a direction; the new syntax variant is as follows:</p>
<pre>
slope {
point_at <ReferencePoint> [, Lo_Slope, Hi_Slope ]
}
</pre>
<p class="Note"><strong>Note:</strong> This variant currently does <em>not</em> allow for the <code>altitude</code> keyword to be used.</p>
<p>The functionality is similar to MegaPOV's <code>aoi <ReferencePoint></code> pattern, except that the values are reversed, i.e. range from 0.0 for surfaces facing away from the point in question, to 1.0 for surfaces facing towards that point; thus, <code>slope { <Vector> }</code> and <code>slope { point_at <Vector>*VeryLargeNumber }</code> have virtually the same effect.</p></div>
<a name="r3_4_7_4"></a>
<div class="content-level-h4" contains="Special Patterns" id="r3_4_7_4">
<h4>3.4.7.4 Special Patterns</h4>
<p>Some patterns are not "real" patterns, but behave like patterns and are used in the same location as a regular pattern. They are <code>average</code> and <code>image</code>.</p></div>
<a name="r3_4_7_4_1"></a>
<div class="content-level-h5" contains="Average Pattern" id="r3_4_7_4_1">
<h5>3.4.7.4.1 Average Pattern</h5>
<p>Technically <code>average</code> is not a pattern type but it is listed here
because the syntax is similar to other patterns. Typically a pattern type specifies
how colors or normals are chosen from a <code>pigment_map</code>,
<code>texture_map</code>, <code>density_map</code>, or <code>normal_map
</code>, however <code>average</code> tells POV-Ray to
average together all of the patterns you specify. Average was originally
designed to be used in a normal statement with a <code>normal_map</code> as a
method of specifying more than one normal pattern on the same surface.
However average may be used in a pigment statement with a <code>
pigment_map</code> or in a texture statement with a <code>texture_map</code>
or media density with <code>density_map</code> to average colors too.</p>
<p>
When used with pigments, the syntax is:</p>
<pre>
AVERAGED_PIGMENT:
pigment {
pigment_map {
PIGMENT_MAP_ENTRY...
}
}
PIGMENT_MAP_ENTRY:
[ [Weight] PIGMENT_BODY ]
</pre>
<p>Where <em><code>Weight</code></em> is an optional float value that
defaults to 1.0 if not specified. This weight value is the relative weight
applied to that pigment. Each <em>PIGMENT_BODY</em> is anything which can be
inside a <code>pigment{...}</code> statement. The <code>pigment</code>
keyword and <code>{}</code> braces need not be specified.</p>
<p class="Note"><strong>Note:</strong> The <code>[]</code> brackets are part of the actual <em>
PIGMENT_MAP_ENTRY</em>. They are not notational symbols denoting optional
parts. The brackets surround each entry in the <code>pigment_map</code>.</p>
<p>
There may be from 2 to 256 entries in the map.</p>
<p>
For example</p>
<pre>
pigment {
average
pigment_map {
[1.0 Pigment_1]
[2.0 Pigment_2]
[0.5 Pigment_3]
}
}
</pre>
<p>All three pigments are evaluated. The weight values are multiplied by the
resulting color. They are then divided by the total of the weights which, in
this example is 3.5. When used with <code>texture_map</code> or <code>
density_map</code> it works the same way.</p>
<p>
When used with a <code>normal_map</code> in a normal statement, multiple
copies of the original surface normal are created and are perturbed by each
pattern. The perturbed normals are then weighted, added and normalized.</p>
<p>
See the sections <a href="r3_4.html#r3_4_6_1_3">Pigment Maps and Pigment Lists</a>, <a href="r3_4.html#r3_4_6_2_1">Normal Maps and Normal Lists</a>, <a href="r3_4.html#r3_4_6_5_1">Texture Maps</a>, and <a href="r3_4.html#r3_4_8_4_3">Density Maps and Density Lists</a> for more information.</p></div>
<a name="r3_4_7_4_2"></a>
<div class="content-level-h5" contains="Image Pattern" id="r3_4_7_4_2">
<h5>3.4.7.4.2 Image Pattern</h5>
<p>Instead of placing the color of the image on the object like an <code>image_map</code>, an <code>image_pattern</code> specifies an entire texture item (color, pigment, normal or texture) based on the gray value at that point.</p>
<p>This gray-value is checked against a list and the corresponding item is then used for the texture at that particular point. For values between listed items, an averaged texture is calculated.</p>
<p>It takes a standard image specification and has one option, <code>use_alpha</code>, which works similar to <code>use_color</code> or <code>use_index</code>.</p>
<p class="Note"><strong>Note:</strong> See the section <a href="r3_4.html#r3_4_7_6_4">Using the Alpha Channel</a> for some important information regarding the use of <code>image_pattern</code>.</p>
<p>Syntax:</p>
<pre>
PIGMENT:
pigment {
IMAGE_PATTERN
color_map { COLOR_MAP_BODY } |
colour_map { COLOR_MAP_BODY } |
pigment_map { PIGMENT_MAP_BODY }
}
NORMAL:
normal {
IMAGE_PATTERN [Bump_Size]
normal_map { NORMAL_MAP_BODY }
}
TEXTURE:
texture {
IMAGE_PATTERN
texture_map { TEXTURE_MAP_BODY }
}
IMAGE_PATTERN:
image_pattern {
BITMAP_TYPE "bitmap.ext" [gamma GAMMA] [premultiplied BOOL]
[IMAGE_MAP_MODS...]
}
IMAGE_MAP_MOD:
map_type Type | once | interpolate Type | use_alpha
ITEM_MAP_BODY:
ITEM_MAP_IDENTIFIER | ITEM_MAP_ENTRY...
ITEM_MAP_ENTRY:
[ GRAY_VALUE ITEM_MAP_ENTRY... ]
</pre>
<p>It is also useful for creating texture <em>masks</em>, like the following:</p>
<pre>
texture {
image_pattern { tga "image.tga" use_alpha }
texture_map {
[0 Mytex ]
[1 pigment { transmit 1 } ]
}
}
</pre>
<p class="Note"><strong>Note:</strong> This pattern uses an image to get the gray values from. If you want exactly the
same possibilities but need to get gray values from a pigment, you can use the <a href="r3_4.html#r3_4_6_1_3">pigment_pattern</a>.</p>
<p>
While POV-Ray will normally interpret the image pattern input file as a container of linear data irregardless of file type, this can be overridden for any individual image pattern input file by specifying <code>gamma</code> GAMMA immediately after the file name. For example:</p>
<pre>
image_pattern {
jpeg "foobar.jpg" gamma 1.8
}
</pre>
<p>This will cause POV-Ray to perform gamma adjustment or -decoding on the input file data before building the image pattern. Alternatively to a numerical value, <code>srgb</code> may be specified to denote that the file format is pre-corrected or encoded using the <em>sRGB transfer function</em> instead of a power-law gamma function. See section <a href="t2_3.html#t2_3_4">Gamma Handling</a> for more information on gamma.</p></div>
<a name="r3_4_7_5"></a>
<div class="content-level-h4" contains="Pattern Modifiers" id="r3_4_7_5">
<h4>3.4.7.5 Pattern Modifiers</h4>
<p>Pattern modifiers are statements or parameters which modify how a pattern
is evaluated or tells what to do with the pattern. The complete syntax
is:</p>
<pre>
PATTERN_MODIFIER:
BLEND_MAP_MODIFIER | AGATE_MODIFIER | DENSITY_FILE_MODIFIER |
QUILTED_MODIFIER | BRICK_MODIFIER | SLOPE_MODIFIER |
noise_generator Number| turbulence <Amount> |
octaves Count | omega Amount | lambda Amount |
warp { [WARP_ITEMS...] } | TRANSFORMATION
BLEND_MAP_MODIFIER:
frequency Amount | phase Amount | ramp_wave | triangle_wave |
sine_wave | scallop_wave | cubic_wave | poly_wave [Exponent]
AGATE_MODIFIER:
agate_turb Value
BRICK_MODIFIER:
brick_size Size | mortar Size
DENSITY_FILE_MODIFIER:
interpolate Type
SLOPE_MODIFIERS:
<Altitude>
<Lo_slope,Hi_slope>
<Lo_alt,Hi_alt>
QUILTED_MODIFIER:
control0 Value | control1 Value
PIGMENT_MODIFIER:
PATTERN_MODIFIER | COLOR_LIST | PIGMENT_LIST |
color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
pigment_map{ PIGMENT_MAP_BODY } | quick_color COLOR |
quick_colour COLOR
COLOR NORMAL_MODIFIER:
PATTERN_MODIFIER | NORMAL_LIST |
normal_map { NORMAL_MAP_BODY } | slope_map{ SLOPE_MAP_BODY } |
bump_size Amount
TEXTURE_PATTERN_MODIFIER:
PATTERN_MODIFIER | TEXTURE_LIST |
texture_map{ TEXTURE_MAP_BODY }
DENSITY_MODIFIER:
PATTERN_MODIFIER | DENSITY_LIST | COLOR_LIST |
color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
density_map { DENSITY_MAP_BODY }
</pre>
<p>Default values for pattern modifiers:</p>
<pre>
dist_exp : 0
falloff : 2.0
frequency : 1.0
lambda : 2.0
major_radius : 1
map_type : 0
noise_generator : 2
octaves : 6
omega : 0.5
orientation : <0,0,1>
phase : 0.0
poly_wave : 1.0
strength : 1.0
turbulence : <0,0,0>
</pre>
<p>The modifiers <em>PIGMENT_LIST</em>, <code>quick_color</code>, and <code>pigment_map</code> apply only to pigments. See the section <a href="r3_4.html#r3_4_6_1">Pigment</a> for details on these pigment-specific pattern modifiers.</p>
<p>The modifiers <em>COLOR_LIST</em> and <code>color_map</code> apply only to pigments and densities. See the sections <a href="r3_4.html#r3_4_6_1">Pigment</a> and <a href="r3_4.html#r3_4_7_1_8">Density</a> for details on these pigment-specific pattern modifiers.</p>
<p>The modifiers <em> NORMAL_LIST</em>, <code>bump_size</code>, <code>slope_map</code> and <code>normal_map</code> apply only to normals. See the section <a href="r3_4.html#r3_4_6_2">Normal</a> for details on these normal-specific pattern
modifiers.</p>
<p>The <em>TEXTURE_LIST</em> and <code>texture_map</code> modifiers can only be used with patterned textures. See the section <a href="r3_4.html#r3_4_6_5_1">Texture Maps</a> for details.</p>
<p>The <em>DENSITY_LIST</em> and <code>density_map</code> modifiers only work with <code>media{density{..}}</code> statements. See the section <a href="r3_4.html#r3_4_7_1_8">Density</a> for details.</p>
<p>The <code>agate_turb</code> modifier can only be used with the <code>agate</code> pattern. See the section <a href="r3_4.html#r3_4_7_1_1">Agate</a> for details.</p>
<p>The <code>brick_size</code> and <code>mortar</code> modifiers can only be used with the <code>brick</code> pattern. See the section <a href="r3_4.html#r3_4_7_1_4">Brick</a> for details.</p>
<p>The <code>control0</code> and <code>control1</code> modifiers can only be used with the <code>quilted</code> pattern. See the section <a href="r3_4.html#r3_4_7_1_21">Quilted</a> for details.</p>
<p>The <code>interpolate</code> modifier can only be used with the <code>density_file</code> pattern. See the section <a href="r3_4.html#r3_4_7_1_8">Density File</a> for details.</p>
<p>The general purpose pattern modifiers in the following sections can be used with <code>pigment</code>, <code>normal</code>, <code>texture</code>, or <code>density</code> patterns.</p>
</div>
<a name="r3_4_7_5_1"></a>
<div class="content-level-h5" contains="Transforming Patterns" id="r3_4_7_5_1">
<h5>3.4.7.5.1 Transforming Patterns</h5>
<p>The most common pattern modifiers are the transformation modifiers <code>translate</code>, <code>rotate</code>, <code>scale</code>, <code>transform</code>, and <code>matrix</code>. For details on these commands see the section <a href="r3_3.html#r3_3_1_12">Transformations</a>.</p>
<p>These modifiers may be placed inside pigment, normal, texture, and density
statements to change the position, size and orientation of the patterns.</p>
<p>Transformations are performed in the order in which you specify them.
However in general the order of transformations relative to other pattern
modifiers such as <code>turbulence</code>, <code>color_map</code> and other
maps is not important. For example scaling before or after turbulence makes
no difference. The turbulence is done first, then the scaling regardless of
which is specified first. However the order in which transformations are
performed relative to <code>warp</code> statements is important. See the section <a href="r3_4.html#r3_4_7_5_5">Warp</a> for details.</p>
</div>
<a name="r3_4_7_5_2"></a>
<div class="content-level-h5" contains="Frequency and Phase" id="r3_4_7_5_2">
<h5>3.4.7.5.2 Frequency and Phase</h5>
<p>The <code>frequency</code> and <code>phase</code> modifiers act as a type
of scale and translate modifiers for various blend maps. They only have
effect when blend maps are used. Blend maps are <code>color_map</code>,
<code>pigment_map</code>, <code>normal_map</code>, <code>slope_map</code>,
<code>density_map</code>, and <code>texture_map</code>. This discussion uses
a color map as an example but the same principles apply to the other blend
map types.</p>
<p>The <code>frequency</code> keyword adjusts the number of times that a color
map repeats over one cycle of a pattern. For example <code>gradient</code> covers color map values 0 to 1 over the range from x=0 to x=1. By adding <code>frequency 2.0</code> the color map repeats twice over that same range. The same effect can be achieved using <code>scale 0.5*x</code> so the frequency keyword is not that useful for patterns like gradient.</p>
<p>However the radial pattern wraps the color map around the +y-axis once. If
you wanted two copies of the map (or 3 or 10 or 100) you would have to build
a bigger map. Adding <code>frequency 2.0</code> causes the color map to be
used twice per revolution. Try this:</p>
<pre>
pigment {
radial
color_map{
[0.5 color Red]
[0.5 color White]
}
frequency 6
}
</pre>
<p>The result is six sets of red and white radial stripes evenly spaced
around the object.</p>
<p>The float after <code>frequency</code> can be any value. Values greater than
1.0 causes more than one copy of the map to be used. Values from 0.0 to 1.0
cause a fraction of the map to be used. Negative values reverses the map.</p>
<p>The <code>phase</code> value causes the map entries to be shifted so that the map starts and ends at a different place. In the example above if you render successive frames at <code>phase 0</code> then <code>phase 0.1</code>, <code>phase 0.2</code>, etc. you could create an animation that rotates the stripes. The same effect can be easily achieved by rotating the <code>radial</code> pigment using <code>rotate y*Angle</code> but there are other uses where phase can be handy.</p>
<p>Sometimes you create a great looking gradient or wood color map but you want
the grain slightly adjusted in or out. You could re-order the color map
entries but that is a pain. A phase adjustment will shift everything but
keep the same scale. Try animating a <code>mandel</code> pigment for a color
palette rotation effect.</p>
<p>These values work by applying the following formula</p>
<p><em> New_Value = fmod ( Old_Value * Frequency + Phase, 1.0 ). </em></p>
<p>The <code>frequency</code> and <code>phase</code> modifiers have no effect on block patterns <code>checker</code>, <code>brick</code>, and <code>hexagon</code> nor do they effect <code>image_map</code>, <code>bump_map</code> or <code>material_map</code>. They also have no effect in normal statements when used with <code>bumps</code>, <code>dents</code>, <code>quilted</code> or <code>wrinkles</code> because these normal patterns cannot use <code>normal_map</code> or <code>slope_map</code>.</p>
<p>They can be used with normal patterns <code>ripples</code> and <code>waves</code> even though these two patterns cannot use <code>normal_map</code> or <code>slope_map</code> either. When used with <code>ripples</code> or <code>waves</code>, <code>frequency</code> adjusts the space between features and <code>phase</code> can be adjusted from 0.0 to 1.0 to cause the ripples or waves to move relative to their center for animating the features.</p>
</div>
<a name="r3_4_7_5_3"></a>
<div class="content-level-h5" contains="Waveforms" id="r3_4_7_5_3">
<h5>3.4.7.5.3 Waveforms</h5>
<p>POV-Ray allows you to apply various wave forms to the pattern function
before applying it to a blend map. Blend maps are <code>color_map</code>,
<code>pigment_map</code>, <code>normal_map</code>, <code>slope_map</code>,
<code>density_map</code>, and <code>texture_map</code>.</p>
<p>
Most of the patterns which use a blend map, use the entries in the map in
order from 0.0 to 1.0. The effect can most easily be seen when these patterns
are used as normal patterns with no maps. Patterns such as <code>
gradient</code> or <code>onion</code> generate a groove or slot that looks
like a ramp that drops off sharply. This is called a <code>ramp_wave</code>
wave type and it is the default wave type for most patterns. However the
<code>wood</code> and <code>marble</code> patterns use the map from 0.0 to
1.0 and then reverses it and runs it from 1.0 to 0.0. The result is a wave
form which slopes upwards to a peak, then slopes down again in a <code>
triangle_wave</code>. In earlier versions of POV-Ray there was no way to
change the wave types. You could simulate a triangle wave on a ramp wave
pattern by duplicating the map entries in reverse, however there was no way
to use a ramp wave on wood or marble.</p>
<p>
Now any pattern that takes a map can have the default wave type overridden.
For example:</p>
<pre>
pigment { wood color_map { MyMap } ramp_wave }
</pre>
<p>Also available are <code>sine_wave</code>, <code>scallop_wave</code>,
<code>cubic_wave</code> and <code>poly_wave</code> types. These types are of
most use in normal patterns as a type of built-in slope map. The <code>
sine_wave</code> takes the zig-zag of a ramp wave and turns it into a gentle
rolling wave with smooth transitions. The <code>scallop_wave</code> uses the
absolute value of the sine wave which looks like corduroy when scaled small
or like a stack of cylinders when scaled larger. The <code>cubic_wave</code>
is a gentle cubic curve from 0.0 to 1.0 with zero slope at the start and end.
The <code>poly_wave</code> is an exponential function. It is followed by an
optional float value which specifies exponent. For example <code>poly_wave
2</code> starts low and climbs rapidly at the end while <code>poly_wave
0.5</code> climbs rapidly at first and levels off at the end. If no float
value is specified, the default is 1.0 which produces a linear function
identical to <code>ramp_wave</code>.</p>
<p>
Although any of these wave types can be used for pigments, normals,
textures, or density the effect of many of the wave types are not as
noticeable on pigments, textures, or density as they are for normals.</p>
<p>
Wave type modifiers have no effect on block patterns <code>checker</code>,
<code>brick</code>, <code>object</code> and <code>hexagon</code> nor do they effect <code>
image_map</code>, <code>bump_map</code> or <code>material_map</code>. They
also have no effect in normal statements when used with <code>bumps</code>,
<code>dents</code>, <code>quilted</code>, <code>ripples</code>, <code>
waves</code>, or <code>wrinkles</code> because these normal patterns cannot
use <code>normal_map</code> or <code>slope_map</code>.</p>
</div>
<a name="r3_4_7_5_4"></a>
<div class="content-level-h5" contains="Noise Generators" id="r3_4_7_5_4">
<h5>3.4.7.5.4 Noise Generators</h5>
<p> There are three noise generators implemented. Changing the <code>noise_generator</code> will change
the appearance of noise based patterns, like bozo and granite.</p>
<ul>
<li><code>noise_generator 1</code> the noise that was used in POV_Ray 3.1</li>
<li><code>noise_generator 2</code> <em>range corrected</em> version of the old noise, it does not show
the plateaus seen with <code>noise_generator 1</code> </li>
<li><code>noise_generator 3</code> generates Perlin noise</li>
</ul>
<p>The default is <code>noise_generator 2</code></p>
<p class="Note"><strong>Note:</strong> The noise_generator can also be set in <code>global_settings</code></p></div>
<a name="r3_4_7_5_5"></a>
<div class="content-level-h5" contains="Warp" id="r3_4_7_5_5">
<h5>3.4.7.5.5 Warp</h5>
<p>The <code>warp</code> statement is a pattern modifier that is similar to
turbulence. Turbulence works by taking the pattern evaluation point and
pushing it about in a series of random steps. However warps push the point in
very well-defined, non-random, geometric ways. The <code>warp</code>
statement also overcomes some limitations of traditional turbulence and
transformations by giving the user more control over the order in which
turbulence, transformation and warp modifiers are applied to the pattern.</p>
<p>The turbulence warp provides an alternative way to
specify turbulence. The others modify the pattern in geometric ways.</p>
<p>
The syntax for using a <code>warp</code> statement is:</p>
<pre>
WARP:
warp { WARP_ITEM }
WARP_ITEM:
repeat <Direction> [REPEAT_ITEMS...] |
black_hole <Location>, Radius [BLACK_HOLE_ITEMS...] |
turbulence <Amount> [TURB_ITEMS...]
cylindrical [ orientation VECTOR | dist_exp FLOAT ]
spherical [ orientation VECTOR | dist_exp FLOAT ]
toroidal [ orientation VECTOR | dist_exp FLOAT | major_radius FLOAT ]
planar [ VECTOR , FLOAT ]
REPEAT_ITEMS:
offset <Amount> |
flip <Axis>
BLACK_HOLE_ITEMS:
strength Strength | falloff Amount | inverse |
repeat <Repeat> | turbulence <Amount>
TURB_ITEMS:
octaves Count | omega Amount | lambda Amount
</pre>
<p>You may have as many separate warp statements as you like in each pattern.
The placement of warp statements relative to other modifiers such as <code>
color_map</code> or <code>turbulence</code> is not important. However
placement of warp statements relative to each other and to transformations is
significant. Multiple warps and transformations are evaluated in the order in
which you specify them. For example if you translate, then warp or warp, then
translate, the results can be different.</p>
</div>
<a name="r3_4_7_5_5_1"></a>
<div class="content-level-h6" contains="Black Hole Warp" id="r3_4_7_5_5_1">
<h6>3.4.7.5.5.1 Black Hole Warp</h6>
<p>A <code>black_hole</code> warp is so named because of its similarity to
real black holes. Just like the real thing, you cannot actually see a black
hole. The only way to detect its presence is by the effect it has on things
that surround it.</p>
<p>
Take, for example, a wood grain. Using POV-Ray's normal turbulence and
other texture modifier functions, you can get a nice, random appearance to
the grain. But in its randomness it is regular - it is regularly random!
Adding a black hole allows you to create a localized disturbance in a wood
grain in either one or multiple locations. The black hole can have the effect
of either <em>sucking</em> the surrounding texture into itself (like the real
thing) or <em>pushing</em> it away. In the latter case, applied to a wood
grain, it would look to the viewer as if there were a knothole in the wood.
In this text we use a wood grain regularly as an example, because it is
ideally suitable to explaining black holes. However, black holes may in fact
be used with any texture or pattern. The effect that the black hole has on
the texture can be specified. By default, it <em>sucks</em> with the
strength calculated exponentially (inverse-square). You can change this if
you like.</p>
<p>
Black holes may be used anywhere a warp is permitted. The syntax is:</p>
<pre>
BLACK_HOLE_WARP:
warp {
black_hole <Location>, Radius
[BLACK_HOLE_ITEMS...]
}
BLACK_HOLE_ITEMS:
strength Strength | falloff Amount | inverse | type Type |
repeat <Repeat> | turbulence <Amount>
</pre>
<p>The minimal requirement is the <code>black_hole</code> keyword followed by
a vector <em><code><Location></code></em> followed by a comma and a
float <em><code>Radius</code></em>. Black holes effect all points within the
spherical region around the location and within the radius. This is
optionally followed by any number of other keywords which control how the
texture is warped.</p>
<p>
The <code>falloff</code> keyword may be used with a float value to specify
the power by which the effect of the black hole falls off. The default is
two. The force of the black hole at any given point, before applying the
<code>strength</code> modifier, is as follows.</p>
<p>
First, convert the distance from the point to the center to a proportion (0
to 1) that the point is from the edge of the black hole. A point on the
perimeter of the black hole will be 0.0; a point at the center will be 1.0; a
point exactly halfway will be 0.5, and so forth. Mentally you can consider
this to be a closeness factor. A closeness of 1.0 is as close as you can get
to the center (i.e. at the center), a closeness of 0.0 is as far away as you
can get from the center and still be inside the black hole and a closeness of
0.5 means the point is exactly halfway between the two.</p>
<p>
Call this value c. Raise c to the power specified in <code>falloff</code>.
By default Falloff is 2, so this is c^2 or c squared. The resulting value is
the force of the black hole at that exact location and is used, after
applying the <code>strength</code> scaling factor as described below, to
determine how much the point is perturbed in space. For example, if c is 0.5
the force is 0.5^2 or 0.25. If c is 0.25 the force is 0.125. But if c is
exactly 1.0 the force is 1.0. Recall that as c gets smaller the point is
farther from the center of the black hole. Using the default power of 2, you
can see that as c reduces, the force reduces exponentially in an
inverse-square relationship. Put in plain English, it means that the force is
much stronger (by a power of two) towards the center than it is at the
outside.</p>
<p>
By increasing <code>falloff</code>, you can increase the magnitude of the
falloff. A large value will mean points towards the perimeter will hardly be
affected at all and points towards the center will be affected strongly. A
value of 1.0 for <code>falloff</code> will mean that the effect is linear. A
point that is exactly halfway to the center of the black hole will be
affected by a force of exactly 0.5. A value of <code>falloff</code> of less
than one but greater than zero means that as you get closer to the outside,
the force increases rather than decreases. This can have some uses but there
is a side effect. Recall that the effect of a black hole ceases outside its
perimeter. This means that points just within the perimeter will be affected
strongly and those just outside not at all. This would lead to a visible
border, shaped as a sphere. A value for <code>falloff</code> of 0 would mean
that the force would be 1.0 for all points within the black hole, since any
number larger 0 raised to the power of 0 is 1.0.</p>
<p>
The <code>strength</code> keyword may be specified with a float value to
give you a bit more control over how much a point is perturbed by the black
hole. Basically, the force of the black hole (as determined above) is
multiplied by the value of <code>strength</code>, which defaults to 1.0. If
you set strength to 0.5, for example, all points within the black hole will
be moved by only half as much as they would have been. If you set it to 2.0
they will be moved twice as much.</p>
<p>
There is a rider to the latter example, though - the movement is clipped to
a maximum of the original distance from the center. That is to say, a point
that is 0.75 units from the center may only be moved by a maximum of 0.75
units either towards the center or away from it, regardless of the value of
<code>strength</code>. The result of this clipping is that you will have an
exclusion area near the center of the black hole where all points whose final
force value exceeded or equaled 1.0 were moved by a fixed amount.</p>
<p>
If the <code>inverse</code> keyword is specified then the points <em>
pushed</em> away from the center instead of being pulled in.</p>
<p>
The <code>repeat</code> keyword followed by a vector, allows you to simulate
the effect of many black holes without having to explicitly declare them.
Repeat is a vector that tells POV-Ray to use this black hole at multiple
locations. Using <code>repeat</code> logically divides your scene up into
cubes, the first being located at <0,0,0> and going to <em><code>
<Repeat></code></em>. Suppose your repeat vector was <1,5,2>. The
first cube would be from <0,0,0> to < 1,5,2>. This cube repeats,
so there would be one at < -1,-5,-2>, <1,5,2>, <2,10,4> and
so forth in all directions, ad infinitum.</p>
<p>
When you use <code>repeat</code>, the center of the black hole does not
specify an absolute location in your scene but an offset into each block. It
is only possible to use positive offsets. Negative values will produce
undefined results.</p>
<p>
Suppose your center was <0.5,1,0.25> and the repeat vector is
<2,2,2>. This gives us a block at < 0,0,0> and <2,2,2>,
etc. The centers of the black hole's for these blocks would be
<0,0,0> + < 0.5,1.0,0.25>, i. e. <0.5,1.0,0.25>, and <
2,2,2> + <0.5,1.0,0.25>, i. e. < 2,5,3.0,2.25>.</p>
<p>
Due to the way repeats are calculated internally, there is a restriction on
the values you specify for the repeat vector. Basically, each black hole must
be totally enclosed within each block (or cube), with no part crossing into a
neighboring one. This means that, for each of the x, y and z dimensions, the
offset of the center may not be less than the radius, and the repeat value
for that dimension must be >=the center plus the radius since any other
values would allow the black hole to cross a boundary. Put another way, for
each of x, y and z</p>
<p> Radius <= Offset or Center <= Repeat - Radius.</p>
<p>If the repeat vector in any dimension is too small to fit this criteria,
it will be increased and a warning message issued. If the center is less than
the radius it will also be moved but no message will be issued.</p>
<p>
Note that none of the above should be read to mean that you cannot
overlap black holes. You most certainly can and in fact this can produce some
most useful effects. The restriction only applies to elements of the <code>
same</code> black hole which is repeating. You can declare a second black
hole that also repeats and its elements can quite happily overlap the first
and causing the appropriate interactions. It is legal for the repeat value
for any dimension to be 0, meaning that POV-Ray will not repeat the black
hole in that direction.</p>
<p>
The <code>turbulence</code> can only be used in a black hole with <code>
repeat</code>. It allows an element of randomness to be inserted into the way
the black holes repeat, to cause a more natural look. A good example would be
an array of knotholes in wood - it would look rather artificial if each
knothole were an exact distance from the previous.</p>
<p>
The <code>turbulence</code> vector is a measurement that is added to each
individual black hole in an array, after each axis of the vector is multiplied
by a different random amount ranging from 0 to 1. The resulting actual
position of the black hole's center for that particular repeat element is
random (but consistent, so renders will be repeatable) and somewhere within
the above coordinates. There is a rider on the use of turbulence, which
basically is the same as that of the repeat vector. You cannot specify a
value which would cause a black hole to potentially cross outside of its
particular block.</p>
<p>
In summary: For each of x, y and z the offset of the center must be
>=radius and the value of the repeat must be >= center + radius +
turbulence. The exception being that repeat may be 0 for any dimension, which
means do not repeat in that direction.</p>
<p>
Some examples are given by</p>
<pre>
warp {
black_hole <0, 0, 0>, 0.5
}
warp {
black_hole <0.15, 0.125, 0>, 0.5
falloff 7
strength 1.0
repeat <1.25, 1.25, 0>
turbulence <0.25, 0.25, 0>
inverse
}
warp {
black_hole <0, 0, 0>, 1.0
falloff 2
strength 2
inverse
}
</pre>
</div>
<a name="r3_4_7_5_5_2"></a>
<div class="content-level-h6" contains="Repeat Warp" id="r3_4_7_5_5_2">
<h6>3.4.7.5.5.2 Repeat Warp</h6>
<p>The <code>repeat</code> warp causes a section of the pattern to be
repeated over and over. It takes a slice out of the pattern and makes
multiple copies of it side-by-side. The warp has many uses but was originally
designed to make it easy to model wood veneer textures. Veneer is made by
taking very thin slices from a log and placing them side-by-side on some
other backing material. You see side-by-side nearly identical ring patterns
but each will be a slice perhaps 1/32th of an inch deeper.</p>
<p>
The syntax for a repeat warp is</p>
<pre>
REPEAT_WARP:
warp { repeat <Direction> [REPEAT_ITEMS...] }
REPEAT_ITEMS:
offset <Amount> | flip <Axis>
</pre>
<p>The <code>repeat</code> vector specifies the direction in which the
pattern repeats and the width of the repeated area. This vector must lie
entirely along an axis. In other words, two of its three components must be
0. For example</p>
<pre>
pigment {
wood
warp { repeat 2*x }
}
</pre>
<p>which means that from x=0 to x=2 you get whatever the pattern usually is.
But from x=2 to x=4 you get the same thing exactly shifted two units over in
the x-direction. To evaluate it you simply take the x-coordinate modulo 2.
Unfortunately you get exact duplicates which is not very realistic. The
optional <code>offset</code> vector tells how much to translate the pattern
each time it repeats. For example</p>
<pre>
pigment {
wood
warp {repeat x*2 offset z*0.05}
}
</pre>
<p>means that we slice the first copy from x=0 to x=2 at z=0 but at x=2 to
x=4 we offset to z=0.05. In the 4 to 6 interval we slice at z=0.10. At the
n-th copy we slice at 0.05 n z. Thus each copy is slightly different. There
are no restrictions on the offset vector.</p>
<p>Finally the <code>flip</code> vector causes the pattern to be flipped or
mirrored every other copy of the pattern. The first copy of the pattern in
the positive direction from the axis is not flipped. The next farther is, the
next is not, etc. The flip vector is a three component x, y, z vector but
each component is treated as a boolean value that tells if you should or
should not flip along a given axis. For example</p>
<pre>
pigment {
wood
warp {repeat 2*x flip <1,1,0>}
}
</pre>
<p>means that every other copy of the pattern will be mirrored about the x-
and y- axis but not the z-axis. A non-zero value means flip and zero means do
not flip about that axis. The magnitude of the values in the flip vector
does not matter.</p>
</div>
<a name="r3_4_7_5_5_3"></a>
<div class="content-level-h6" contains="Turbulence Warp" id="r3_4_7_5_5_3">
<h6>3.4.7.5.5.3 Turbulence Warp</h6>
<p>Inside the <code>warp</code> statement, the keyword <code>turbulence</code> followed by a float or vector may be
used to stir up any <code>pigment</code>, <code>normal</code> or <code>density</code>. A number of
optional parameters may be used with turbulence to control how it is
computed. The syntax is:</p>
<pre>
TURBULENCE_ITEM:
turbulence <Amount> | octaves Count | omega Amount | lambda Amount
</pre>
<p>Typical turbulence values range from the default 0.0, which is no
turbulence, to 1.0 or more, which is very turbulent. If a vector is specified
different amounts of turbulence are applied in the x-, y- and z-direction.
For example</p>
<pre>
turbulence <1.0, 0.6, 0.1>
</pre>
<p>has much turbulence in the x-direction, a moderate amount in the
y-direction and a small amount in the z-direction.</p>
<p>
Turbulence uses a random noise function called <em>DNoise</em>. This is
similar to the noise used in the <code>bozo</code> pattern except that
instead of giving a single value it gives a direction. You can think of it as
the direction that the wind is blowing at that spot. Points close together
generate almost the same value but points far apart are randomly
different.</p>
<p>
Turbulence uses <em>DNoise</em> to push a point around in several steps
called <code>octaves</code>. We locate the point we want to evaluate, then
push it around a bit using turbulence to get to a different point then look
up the color or pattern of the new point.</p>
<p>
It says in effect <em>Do not give me the color at this spot...
take a few random steps in different directions and give me that
color</em>. Each step is typically half as long as the one before. For
example:</p>
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
<tr>
<td>
<p>The magnitude of these steps is controlled by the turbulence value. There are three additional parameters which control how turbulence is computed. They are <code>octaves</code>, <code>lambda</code> and <code>omega</code>. Each is optional, each is followed by a single float value, and each has no effect when there is no turbulence.</p>
</td>
<td>
<img class="right" width="320px" src="images/5/53/RefImgTurbrand.png">
</td>
</tr>
<tr>
<td></td>
<td>
<p class="caption">Turbulence random walk.</p>
</td>
</tr>
</table>
</div>
<a name="r3_4_7_5_5_4"></a>
<div class="content-level-h6" contains="Octaves" id="r3_4_7_5_5_4">
<h6>3.4.7.5.5.4 Octaves</h6>
<p>The <code>octaves</code> keyword may be followed by an integer value to
control the number of steps of turbulence that are computed. Legal values
range from 1 to <10. The default value of 6 is a fairly high value; you
will not see much change by setting it to a higher value because the extra
steps are too small. Float values are truncated to integer. Smaller numbers
of octaves give a gentler, wavy turbulence and computes faster. Higher
octaves create more jagged or fuzzy turbulence and takes longer to
compute.</p>
</div>
<a name="r3_4_7_5_5_5"></a>
<div class="content-level-h6" contains="Lambda" id="r3_4_7_5_5_5">
<h6>3.4.7.5.5.5 Lambda</h6>
<p>The <code>lambda</code> parameter controls how statistically different the
random move of an octave is compared to its previous octave. The default
value is 2.0 which is quite random. Values close to lambda 1.0 will
straighten out the randomness of the path in the diagram above. The zig-zag
steps in the calculation are in nearly the same direction. Higher values can
look more <em>swirly</em> under some circumstances.</p>
</div>
<a name="r3_4_7_5_5_6"></a>
<div class="content-level-h6" contains="Omega" id="r3_4_7_5_5_6">
<h6>3.4.7.5.5.6 Omega</h6>
<p>The <code>omega</code> value controls how large each successive octave
step is compared to the previous value. Each successive octave of turbulence
is multiplied by the omega value. The default <code>omega 0.5</code> means
that each octave is 1/2 the size of the previous one. Higher omega values
mean that 2nd, 3rd, 4th and up octaves contribute more turbulence giving a
sharper, <em>crinkly</em> look while smaller omegas give a fuzzy kind of
turbulence that gets blurry in places.</p>
</div>
<a name="r3_4_7_5_5_7"></a>
<div class="content-level-h6" contains="Mapping using warps" id="r3_4_7_5_5_7">
<h6>3.4.7.5.5.7 Mapping using warps</h6>
<p>With the <code>cylindrical, spherical</code> and <code>toroidal</code> warps you can wrap checkers,
bricks and other patterns around cylinders, spheres, tori and other objects. In essence, these
warps use the same mapping as the image maps use.</p>
<p>The syntax is as follows:</p>
<pre>
CYLINDRICAL_WARP:
warp { cylindrical [CYLINDRICAL_ITEMS...]}
CYLINDRICAL_ITEMS:
orientation VECTOR | dist_exp FLOAT
SPHERICAL_WARP:
warp { spherical [SPHERICAL_ITEMS...]}
SPHERICAL_ITEMS:
orientation VECTOR | dist_exp FLOAT
TOROIDAL_WARP:
warp { toroidal [TOROIDAL_ITEMS...]}
TOROIDAL_ITEMS:
orientation VECTOR | dist_exp FLOAT | major_radius FLOAT
PLANAR_WARP:
warp { planar [ VECTOR , FLOAT ]}
CUBIC_WARP:
warp { cubic }
</pre>
<p>These defaults are in affect:</p>
<pre>
orientation <0,0,1>
dist_exp 0
major_radius 1
</pre>
<p>Although these warps do 3D mapping, some concession had to be made on depth.</p>
<p>The distance exponent is controlled by using the <code>dist_exp</code> keyword. When using the default value of 0, imagine a box from <0,0> to <1,1> stretching to infinity along the orientation vector.</p>
<p>The <code>distance</code> keyword is evaluated as follows:</p>
<ul>
<li><code>sphere</code>: distance from origin</li>
<li><code>cylinder</code>: distance from y-axis</li>
<li><code>torus</code>: distance from major radius</li>
</ul>
<p>The <code>planar</code> warp was made to make a pattern act like an image_map, of infinite size and can be useful in combination with other mapping-warps. By default the pigment in the XY-plane is extruded along
the Z-axis. The pigment can be taken from an other plane, by specifying the optional vector (normal of the plane) and float (distance along the normal). The result, again, is extruded along the Z-axis.</p>
<p>The <code>cubic</code> warp requires no parameters, and maps an area in the x-y plane between <0,0> and <1,1> around the origin in the same way as uv-mapping an origin-centered cube-shaped box would. The <code>cubic</code> warp works with any object whereas the uv-mapping only works for the box object. See the section on <a href="r3_4.html#r3_4_6_7_1">box</a> uv-mapping for details.</p>
<p>The following code examples produced the images below:</p>
<pre>
torus {
1, 0.5
pigment {
hexagon
scale 0.1
warp {
toroidal
orientation y
dist_exp 1
major_radius 1
}
}
}
sphere {
0,1
pigment {
hexagon
scale <0.5/pi,0.25/pi,1>*0.1
warp {
spherical
orientation y
dist_exp 1
}
}
}
cylinder {
-y, y, 1
pigment {
hexagon
scale <0.5/pi, 1, 1>*0.1
warp {
cylindrical
orientation y
dist_exp 1
}
}
}
</pre>
<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
<td>
<img class="leftpanel" width="220px" src="images/4/46/RefImgWarpCylindrical1.png">
</td>
<td>
<img class="centerpanel" width="220px" src="images/5/5a/RefImgWarpSphere1.png">
</td>
<td>
<img class="rightpanel" width="220px" src="images/e/e7/RefImgWarpToroidal1.png">
</td>
</tr>
<tr>
<td>
<p class="caption">cylindrical warp</p>
</td>
<td>
<p class="caption">spherical warp</p>
</td>
<td>
<p class="caption">toroidal warp</p>
</td>
</tr>
</table>
</div>
<a name="r3_4_7_5_5_8"></a>
<div class="content-level-h6" contains="Turbulence versus Turbulence Warp" id="r3_4_7_5_5_8">
<h6>3.4.7.5.5.8 Turbulence versus Turbulence Warp</h6>
<p>The POV-Ray language contains an ambiguity and limitation on the way you
specify <code>turbulence</code> and transformations such as <code>
translate</code>, <code>rotate</code>, <code>scale</code>, <code>
matrix</code>, and <code>transform</code> transforms. Usually the turbulence
is done first. Then all translate, rotate, scale, matrix, and transform
operations are always done after turbulence regardless of the order in which
you specify them. For example this</p>
<pre>
pigment {
wood
scale .5
turbulence .2
}
</pre>
<p>works exactly the same as</p>
<pre>
pigment {
wood
turbulence .2
scale .5
}
</pre>
<p>The turbulence is always first. A better example of this limitation is
with uneven turbulence and rotations.</p>
<pre>
pigment {
wood
turbulence 0.5*y
rotate z*60
}
// as compared to
pigment {
wood
rotate z*60
turbulence 0.5*y
}
</pre>
<p>The results will be the same either way even though you would think it
should look different.</p>
<p>
We cannot change this basic behavior in POV-Ray now because lots of scenes
would potentially render differently if suddenly the order transformation vs.
turbulence mattered when in the past, it did not.</p>
<p>
However, by specifying our turbulence inside warp statement you tell POV-Ray
that the order in which turbulence, transformations and other warps are
applied is significant. Here is an example of a turbulence warp.</p>
<pre>
warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
</pre>
<p>The significance is that this</p>
<pre>
pigment {
wood
translate <1,2,3> rotate x*45 scale 2
warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
}
</pre>
<p>produces <em>different results</em> than this...</p>
<pre>
pigment {
wood
warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
translate <1,2,3> rotate x*45 scale 2
}
</pre>
<p>You may specify turbulence without using a warp statement. However you
cannot control the order in which they are evaluated unless you put them in a
warp.</p>
<p>
The evaluation rules are as follows:</p>
<ol>
<li>First any turbulence not inside a warp statement is applied regardless
of the order in which it appears relative to warps or transformations.</li>
<li>Next each warp statement, translate, rotate, scale or matrix one-by-one,
is applied in the order the user specifies. If you want turbulence done in a
specific order, you simply specify it inside a warp in the proper place.</li>
</ol>
</div>
<a name="r3_4_7_5_5_9"></a>
<div class="content-level-h6" contains="Turbulence" id="r3_4_7_5_5_9">
<h6>3.4.7.5.5.9 Turbulence</h6>
<p>The <code>turbulence</code> pattern modifier is still supported for compatibility
issues, but it is better nowadays to use the warp <code><a href="r3_4.html#r3_4_7_5_5_3">turbulence</a></code> feature,
which does not have turbulence's limitation in transformation order
(turbulence is always applied first, before any scale, translate or
rotate, whatever the order you specify). For a detailed discussion see
<a href="r3_4.html#r3_4_7_5_5_8">Turbulence versus Turbulence Warp</a></p>
<p> The old-style turbulence is handled slightly differently when used with the
agate, marble, spiral1, spiral2, and wood textures.</p></div>
<a name="r3_4_7_6"></a>
<div class="content-level-h4" contains="Image Map" id="r3_4_7_6">
<h4>3.4.7.6 Image Map</h4>
<p>When all else fails and none of the pigment pattern types meets your needs you can use an <code>image_map</code> to wrap a 2-D bit-mapped image around your 3-D objects.</p>
</div>
<a name="r3_4_7_6_1"></a>
<div class="content-level-h5" contains="Specifying an Image Map" id="r3_4_7_6_1">
<h5>3.4.7.6.1 Specifying an Image Map</h5>
<p>The syntax for an <code>image_map</code> is:</p>
<pre>
IMAGE_MAP:
pigment {
image_map {
[BITMAP_TYPE] "bitmap[.ext]" [gamma GAMMA] [premultiplied BOOL]
[IMAGE_MAP_MODS...]
}
[PIGMENT_MODFIERS...]
}
IMAGE_MAP:
pigment {
image_map {
FUNCTION_IMAGE
}
[PIGMENT_MODFIERS...]
}
BITMAP_TYPE:
exr | gif | hdr | iff | jpeg | pgm | png | ppm | sys | tga | tiff
IMAGE_MAP_MODS:
map_type Type | once | interpolate Type |
filter Palette, Amount | filter all Amount |
transmit Palette, Amount | transmit all Amount
FUNCTION_IMAGE:
function I_WIDTH, I_HEIGHT { FUNCTION_IMAGE_BODY }
FUNCTION_IMAGE_BODY:
PIGMENT | FN_FLOAT | pattern { PATTERN [PATTERN_MODIFIERS] }
</pre>
<p>After the optional <em>BITMAP_TYPE</em> keyword is a string expression containing the name of a bitmapped image file of the specified type. If the <em>BITMAP_TYPE</em> is not given, the same type is expected as the type set for output.</p>
<p>For example:</p>
<pre>
plane { -z,0
pigment {
image_map {png "Eggs.png"}
}
}
plane { -z,0
pigment {
image_map {"Eggs"}
}
}
</pre>
<p>The second method will look for, and use "Eggs.png" if the output file type is set to be <code>png</code> (Output_File_Type=N in INI-file or +FN on command line). It is particularly useful when the image used in the <code>image_map</code> is also rendered with POV-Ray.</p>
<p>Several optional modifiers may follow the file specification. The modifiers are described below.</p>
<p class="Note"><strong>Note:</strong> Earlier versions of POV-Ray allowed some modifiers before the <em>BITMAP_TYPE</em> but that syntax is being phased out in favor of the syntax described here.</p>
<p class="Note"><strong>Note:</strong> The <code>sys</code> format is a system-specific format. See the <a href="r3_2.html#r3_2_4_1">Output File Type</a> section for more information.</p>
<p>Filenames specified in the <code>image_map</code> statements will be searched for in the home (current) directory first and, if not found, will then be searched for in directories specified by any <code>+L</code> or <code>Library_Path</code> options active. This would facilitate keeping all your image maps files in a separate subdirectory and giving a <code>Library_Path</code> option to specify where your library of image maps are. See <a href="r3_2.html#r3_2_5_4">Library Paths</a> for details.</p>
<p>By default, the image is mapped onto the x-y-plane. The image is <em>projected</em> onto the object as though there were a slide projector somewhere in the -z-direction. The image exactly fills the square area from (x,y) coordinates (0,0) to (1,1) regardless of the image's original size in pixels. If you would like to change this default you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired.</p>
<p>In the section <a href="r3_4.html#r3_4_7_2_2">Checker</a>, the <code>checker</code> pigment pattern is explained. The checks are described as solid cubes of colored clay from which objects are carved. With image maps you should imagine that each pixel is a long, thin, square, colored rod that extends parallel to the z-axis. The image is made from rows and columns of these rods bundled together and the object is then carved from the bundle.</p>
<p>If you would like to change this default orientation you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired.</p>
<p>The file name is optionally followed by one or more <em>BITMAP_MODIFIERS</em>. The <code> filter</code>, <code>filter all</code>, <code>transmit</code>, and <code> transmit all</code> modifiers are specific to image maps and are discussed in the following sections. An <code>image_map</code> may also use generic bitmap modifiers <code>map_type</code>,
<code>once</code> and <code> interpolate</code> described in Bitmap Modifiers</p>
</div>
<a name="r3_4_7_6_2"></a>
<div class="content-level-h5" contains="The Gamma Option" id="r3_4_7_6_2">
<h5>3.4.7.6.2 The Gamma Option</h5>
<p>The default gamma handling rules for any image input file can be overridden by specifying <code>gamma</code> GAMMA immediately after the file name. For example:</p>
<pre>
image_map {
jpeg "foobar.jpg" gamma 1.8
interpolate 2
}
</pre>
<p>Alternatively to a numerical value, <code>srgb</code> may be specified to denote that the file is encoded or pre-corrected using the <em>sRGB transfer function</em> instead of a power-law gamma function.</p>
<p>
See section <a href="t2_3.html#t2_3_4">Gamma Handling</a> for more information on gamma.</p>
</div>
<a name="r3_4_7_6_3"></a>
<div class="content-level-h5" contains="The Filter and Transmit Bitmap Modifiers" id="r3_4_7_6_3">
<h5>3.4.7.6.3 The Filter and Transmit Bitmap Modifiers</h5>
<p>To make all or part of an image map transparent you can specify <code>filter</code> and/or <code>transmit</code> values for the color palette/registers of PNG, GIF or IFF pictures (at least for the modes that use palettes). You can do this by adding the keyword <code>filter</code> or <code>transmit</code> following the filename. The keyword is followed by two numbers. The first number is the palette number value and the second is the amount of transparency. The values should be separated by a comma. For
example:</p>
<pre>
image_map {
gif "mypic.gif"
filter 0, 0.5 // Make color 0 50% filtered transparent
filter 5, 1.0 // Make color 5 100% filtered transparent
transmit 8, 0.3 // Make color 8 30% non-filtered transparent
}
</pre>
<p>You can give the entire image a <code>filter</code> or <code>transmit</code> value using <code>filter all</code> <em><code>Amount</code></em> or <code>transmit all</code> <em><code>Amount</code></em>. For example:</p>
<pre>
image_map {
gif "stnglass.gif"
filter all 0.9
}
</pre>
<p class="Note"><strong>Note:</strong> Early versions of POV-Ray used the keyword <code>alpha</code> to specify filtered transparency however that word is often used to describe non-filtered transparency. For this reason <code>alpha</code> is no longer
used.</p>
<p>See the section <a href="r3_3.html#r3_3_1_7">Color Expressions</a> for details on the differences between filtered and non-filtered transparency.</p>
</div>
<a name="r3_4_7_6_4"></a>
<div class="content-level-h5" contains="Using the Alpha Channel" id="r3_4_7_6_4">
<h5>3.4.7.6.4 Using the Alpha Channel</h5>
<p>Another way to specify non-filtered transmit transparency in an image map is by using the<em> alpha channel</em>. POV-Ray will automatically use the alpha channel for transmittance when one is stored in the image. PNG file format allows you to store a
different transparency for each color index in the PNG file, if desired. If your paint programs support this feature of PNG you can do the transparency editing within your paint program rather than specifying transmit values for each color in the POV file. Since PNG and TGA image formats can also store full alpha channel (transparency) information you can generate image maps that have transparency which is not dependent on the color of a pixel but rather its location in the image.</p>
<p>Although POV uses <code>transmit 0.0</code> to specify no transparency and <code> 1.0</code> to specify full transparency, the alpha data ranges from 0 to 255 in the opposite direction. Alpha data 0 means the same as <code>transmit 1.0</code> and alpha data 255 produces <code>transmit 0.0</code>.</p>
<p class="Note"><strong>Note:</strong> In version 3.7 alpha handling for image file output has changed. Effectively, the background <em>now requires</em> a <code>filter</code> or <code>transmit</code> value in order for alpha transparency to work properly.</p>
<p>Previous versions of POV-Ray always expected straight alpha for file input, this has been changed on a per-file-format basis as follows:</p>
<ul>
<li> PNG will use straight alpha as per specification.</li>
<li> OpenEXR and TIFF will use associated alpha as per specifications.</li>
<li> TGA and BMP 32-bit RGBA will use straight alpha, retaining file input compatibility for now, until a final decision has been made on these formats.</li>
</ul>
<p>Additionally the <code>premultiplied</code> parameter may be used to specify the input image alpha handling. This boolean parameter specifies whether the file is stored in premultiplied <em>associated</em> or non-premultiplied <em>straight</em> alpha format, overriding the file format specific default. This keyword has no effect on files without an alpha channel. Like the <code>gamma</code>, it <em>MUST</em> immediately follow the filename, though the order does not matter.</p>
<p class="Note"><strong>Note:</strong> The following mechanism has some limitations with colored highlights.</p>
<p>When generating non-premultiplied alpha output to a classic low-dynamic-range file format (e.g. PNG), transparency of particularly bright areas will now be reduced, in order to better preserve highlights on transparent objects.</p>
<p class="Note"><strong>Note:</strong> When using an input image in a <code>material_map</code>, <code>bump_map</code>, or <code>image_pattern</code> definition, the following conditions apply.</p>
<ul>
<li> For material maps, <em>no</em> alpha premultiplication handling is done whatsoever, instead the data as stored in the file is used.</li>
<li> For bump maps and image patterns, images with an alpha channel are treated as if they had a black background, unless the alpha channel itself is used.</li>
</ul>
<p class="Note"><strong>Note:</strong> See also <code><a href="r3_4.html#r3_4_3_2">background</a></code> and <code><a href="r3_4.html#r3_4_3_4">sky_sphere</a></code> for additional information.</p>
<p>Activating alpha output via <code>Output_Alpha=on</code> or <code>+UA</code>, when used with unsupported file formats generates a warning.</p></div>
<a name="r3_4_7_7"></a>
<div class="content-level-h4" contains="Bitmap Modifiers" id="r3_4_7_7">
<h4>3.4.7.7 Bitmap Modifiers</h4>
<p>A bitmap modifier is a modifier used inside an <code>image_map</code>,
<code>bump_map</code> or <code>material_map</code> to specify how the 2-D
bitmap is to be applied to the 3-D surface. Several bitmap modifiers apply to
specific kinds of maps and they are covered in the appropriate sections. The
bitmap modifiers discussed in the following sections are applicable to all
three types of bitmaps.</p>
</div>
<a name="r3_4_7_7_1"></a>
<div class="content-level-h5" contains="The once Option" id="r3_4_7_7_1">
<h5>3.4.7.7.1 The once Option</h5>
<p>Normally there are an infinite number of repeating image maps, bump maps
or material maps created over every unit square of the x-y-plane like tiles.
By adding the <code>once</code> keyword after a file name you can eliminate
all other copies of the map except the one at (0,0) to (1,1). In image maps,
areas outside this unit square are treated as fully transparent. In bump
maps, areas outside this unit square are left flat with no normal
modification. In material maps, areas outside this unit square are textured
with the first texture of the texture list.</p>
<p>
For example:</p>
<pre>
image_map {
gif "mypic.gif"
once
}
</pre>
</div>
<a name="r3_4_7_7_2"></a>
<div class="content-level-h5" contains="The map_type Option" id="r3_4_7_7_2">
<h5>3.4.7.7.2 The map_type Option</h5>
<p>The default projection of the image onto the x-y-plane is called a <em>
planar map type</em>. This option may be changed by adding the <code>
map_type</code> keyword followed by an integer number specifying the way to
wrap the image around the object.</p>
<p>
A <code>map_type 0</code> gives the default planar mapping already
described.</p>
<p>
A <code>map_type 1</code> gives a spherical mapping. It assumes that the
object is a sphere of any size sitting at the origin. The y-axis is the
north/south pole of the spherical mapping. The top and bottom edges of the
image just touch the pole regardless of any scaling. The left edge of the
image begins at the positive x-axis and wraps the image around the sphere
from west to east in a -y-rotation. The image covers the sphere exactly once.
The <code>once</code> keyword has no meaning for this mapping type.</p>
<p>
With <code>map_type 2</code> you get a cylindrical mapping. It assumes that
a cylinder of any diameter lies along the y-axis. The image wraps around the
cylinder just like the spherical map but the image remains one unit tall from
y=0 to y=1. This band of color is repeated at all heights unless the <code>
once</code> keyword is applied.</p>
<p>
Finally <code>map_type 5</code> is a torus or donut shaped mapping. It
assumes that a torus of major radius one sits at the origin in the x-z-plane.
The image is wrapped around similar to spherical or cylindrical maps. However
the top and bottom edges of the map wrap over and under the torus where they
meet each other on the inner rim.</p>
<p>
Types 3 and 4 are still under development.</p>
<p class="Note"><strong>Note:</strong> The <code>map_type</code> option may also be applied to <code>
bump_map</code> and <code>material_map</code> statements.</p>
<p>
For example:</p>
<pre>
sphere{<0,0,0>,1
pigment{
image_map {
gif "world.gif"
map_type 1
}
}
}
</pre>
</div>
<a name="r3_4_7_7_3"></a>
<div class="content-level-h5" contains="The interpolate Option" id="r3_4_7_7_3">
<h5>3.4.7.7.3 The interpolate Option</h5>
<p>Adding the <code>interpolate</code> keyword can smooth the jagged look of a bitmap. When POV-Ray checks a color for an image map or a bump amount for a bump map, it often checks a point that is not directly on top of one pixel but sort of between several differently colored pixels. Interpolations return an in-between value so that the steps between the pixels in the map will look smoother.</p>
<p>
Although <code>interpolate</code> is legal in material maps, the color index is interpolated before the texture is chosen. It does not interpolate the final color as you might hope it would. In general, interpolation of material maps serves no useful purpose but this may be fixed in future versions.</p>
<p>
There are currently three types of interpolation: <code>interpolate 2</code> gives bilinear interpolation, <code>interpolate 3</code> gives bicubic, and <code>interpolate 4</code> gives normalized distance.</p>
<p>For example:</p>
<pre>
image_map {
gif "mypic.gif"
interpolate 2
}
</pre>
<p>The default is no interpolation. Normalized distance is the slowest, bilinear does a better job of picking the between color, and arguably, bicubic interpolation is a slight improvement, however it is subject to over-sharpening at some color borders. Normally bilinear is used.</p>
<p>
If your map looks jagged, try using interpolation instead of going to a higher resolution image. The results can be very good.</p></div>
<a name="r3_4_8"></a>
<div class="content-level-h3" contains="Media" id="r3_4_8">
<h3>3.4.8 Media</h3>
<p>The <code>media</code> statement is used to specify particulate matter suspended in a medium such air or water. It can be used to specify smoke, haze, fog, gas, fire, dust etc. Previous versions of POV-Ray had two incompatible systems for generating such effects. One was <code>halo</code> for effects enclosed in a transparent or semi-transparent object. The other was <code>atmosphere</code> for effects that permeate the entire scene. This duplication of systems was complex and unnecessary. Both <code>halo</code>
and <code>atmosphere</code> have been eliminated. See <a href="r3_4.html#r3_4_8_1_1">Why are Interior and Media Necessary?</a> for further details on this change. See <a href="r3_4.html#r3_4_8_1_8">Object Media</a>
for details on how to use <code>media</code> with objects. See <a href="r3_4.html#r3_4_3_1">Atmospheric Media</a> for details on using <code>media</code> for atmospheric effects outside of objects. This section and the sub-sections which follow explains the details of the various <code>media</code> options which are useful for either object media or atmospheric media.</p>
<p>Media works by sampling the density of particles at some specified number of points along the ray's path. Sub-samples are also taken until the results reach a specified confidence level. POV-Ray provides three methods of sampling. When used in an object's <code>interior</code> statement, sampling only occurs inside the object. When used for atmospheric media, the samples run from
the camera location until the ray strikes an object. Therefore for localized effects, it is best to use an enclosing object even though the density pattern might only produce results in a small area whether the media was enclosed or not.</p>
<p>The complete syntax for a <code>media</code> statement is as follows:</p>
<pre>
MEDIA:
media { [MEDIA_IDENTIFIER] [MEDIA_ITEMS...] }
MEDIA_ITEMS:
method Number | intervals Number | samples Min, Max |
confidence Value | variance Value | ratio Value | jitter Value
absorption COLOR | emission COLOR | aa_threshold Value |
aa_level Value |
scattering {
Type, COLOR [ eccentricity Value ] [ extinction Value ]
} |
density {
[DENSITY_IDENTIFIER] [PATTERN_TYPE] [DENSITY_MODIFIER...]
} |
TRANSFORMATIONS
DENSITY_MODIFIER:
PATTERN_MODIFIER | DENSITY_LIST | COLOR_LIST |
color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
density_map { DENSITY_MAP_BODY }
</pre>
<p>Media default values:</p>
<pre>
aa_level : 3
aa_threshold : 0.1
absorption : <0,0,0>
confidence : 0.9
emission : <0,0,0>
intervals : 1
jitter : 0.0
method : 3
ratio : 0.9
samples : Min 1, Max 1
variance : 1/128
SCATTERING
COLOR : <0,0,0>
eccentricity : 0.0
extinction : 1.0
</pre>
<p>If a media identifier is specified, it must be the first item. All other media items may be specified in any order. All are optional. You may have multiple <code>density</code> statements in a single <code>media</code> statement. See <a href="r3_4.html#r3_4_8_4_4">Multiple Density vs. Multiple Media</a> for details. Transformations apply only to the <code>density</code> statements which have been already specified. Any <code>density</code> after a transformation is not affected. If the <code>media</code> has no <code>density</code> statements and none was specified in any media identifier, then the transformation has no effect. All other media items except for <code>density</code> and transformations override default values or any previously set values for this <code>media</code> statement.</p>
<p class="Note"><strong>Note:</strong> Some media effects depend upon light sources. However the participation of a light source depends upon the <code>media_interaction</code> and <code>media_attenuation</code> keywords. See <a href="r3_4.html#r3_4_4_1_10">Atmospheric Media Interaction</a> and <a href="r3_4.html#r3_4_4_1_11">Atmospheric Attenuation</a> for details.</p>
<p class="Note"><strong>Note:</strong> If you specify <code><a href="r3_3.html#r3_3_1_7_3">transmit</a></code> or <code><a href="r3_3.html#r3_3_1_7_3">filter</a></code> to create a transparent container object, <code>absorption</code> media will always cast a shadow. The same applies to <code>scattering</code> media unless <code>extinction</code> is set to zero, so if a shadow is not desired, use the <code>no_shadow</code> keyword for the container object. This does not apply to <code>emission</code> media as it never casts a shadow.</p>
</div>
<a name="r3_4_8_2"></a>
<div class="content-level-h4" contains="Media Types" id="r3_4_8_2">
<h4>3.4.8.2 Media Types</h4>
<p>There are three types of particle interaction in <code>media</code>: absorbing, emitting, and scattering. All three activities may occur in a single media. Each of these three specifications requires a color. Only the red, green, and blue components of the color are used. The filter and transmit values are ignored. For this reason it is permissible to use one float value to specify an intensity of white color. For example, the following two lines are legal and produce the same results:</p>
<pre>
emission 0.75
emission rgb <0.75,0.75,0.75>
</pre>
</div>
<a name="r3_4_8_2_1"></a>
<div class="content-level-h5" contains="Absorption" id="r3_4_8_2_1">
<h5>3.4.8.2.1 Absorption</h5>
<p>The <code>absorption</code> keyword specifies a color of light which is absorbed when looking through the media. For example, <code>absorption rgb<0,1,0></code> blocks the green light but permits red and blue to get through. Therefore a white object behind the media will appear magenta. The default value is <code>rgb<0,0,0></code> which means no light is absorbed, meaning all light passes through normally.</p>
</div>
<a name="r3_4_8_2_2"></a>
<div class="content-level-h5" contains="Emission" id="r3_4_8_2_2">
<h5>3.4.8.2.2 Emission</h5>
<p>The <code>emission</code> keyword specifies the color of the light emitted from the particles. Particles which emit light are visible without requiring additional illumination. However, they will only illuminate other objects if radiosity is used with media on. This is similar to an object with high <code>ambient</code> values. The default value is <code>rgb<0,0,0></code> which means no light is emitted.</p>
</div>
<a name="r3_4_8_2_3"></a>
<div class="content-level-h5" contains="Scattering" id="r3_4_8_2_3">
<h5>3.4.8.2.3 Scattering</h5>
<p>The syntax of a <code>scattering</code> statement is:</p>
<pre>
SCATTERING:
scattering {
Type, COLOR [ eccentricity Value ] [ extinction Value ]
}
</pre>
<p>The first float value specifies the type of scattering. This is followed by the color of the scattered light. The default value if no <code>scattering</code> statement is given is <code>rgb <0,0,0></code> which means no scattering occurs.</p>
<p>The scattering effect is only visible when light is shining on the media from a light source. This is similar to <code>diffuse</code> reflection off of an object. In addition to reflecting light, scattering media also absorbs light like an <code>absorption</code> media. The balance between how much absorption occurs for a given amount of scattering is controlled by the optional <code>extinction</code> keyword and a single float value. The default value of 1.0 gives an extinction effect that matches the scattering. Values such as <code>extinction 0.25</code> give 25% the normal amount. Using <code>extinction 0.0</code> turns it off completely. Any value other than the 1.0 default is contrary to the real physical model but decreasing extinction can give you more artistic flexibility.</p>
<p>The integer value <em><code>Type</code></em> specifies one of five different scattering phase functions representing the different models: isotropic, Mie (haze and murky atmosphere), Rayleigh, and Henyey-Greenstein.</p>
<p>Type 1, <em>isotropic scattering</em> is the simplest form of scattering because it is independent of direction. The amount of light scattered by particles in the atmosphere does not depend on the angle between the viewing direction and the incoming light.</p>
<p>Types 2 and 3 are <em>Mie haze</em> and <em>Mie murky</em> scattering which are used for relatively small particles such as minuscule water droplets of fog, cloud particles, and particles responsible for the polluted sky. In this model the scattering is extremely directional in the forward direction, i.e. the amount of scattered light is largest when the incident light is anti-parallel to the viewing direction (the light goes directly to the viewer). It is smallest when the incident light is parallel to the viewing direction. The haze and murky atmosphere models differ in their scattering characteristics. The murky model is much more directional than the haze model.</p>
<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
<td><img class="center" width="640px" src="images/7/7d/RefImgMiehaze.gif"></td>
</tr>
<tr>
<td>
<p class="caption">The Mie haze scattering function</p>
</td>
</tr>
</table>
<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
<td><img class="center" width="640px" src="images/1/15/RefImgMiemurky.gif"></td>
</tr>
<tr>
<td>
<p class="caption">The Mie murky scattering function</p>
</td>
</tr>
</table>
<p>Type 4 <em>Rayleigh scattering</em> models the scattering for extremely small particles such as molecules of the air. The amount of scattered light depends on the incident light angle. It is largest when the incident light is parallel or anti-parallel to the viewing direction and smallest when the incident light is perpendicular to the viewing direction. You should note that the Rayleigh model used in POV-Ray does not take the dependency of scattering on the wavelength into account.</p>
<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
<td><img class="center" width="640px" src="images/9/95/RefImgRaylscat.gif"></td>
</tr>
<tr>
<td>
<p class="caption">The Rayleigh scattering function</p>
</td>
</tr>
</table>
<p>Type 5 is the <em>Henyey-Greenstein scattering</em> model. It is based on an analytical function and can be used to model a large variety of different scattering types. The function models an ellipse with a given eccentricity e. This eccentricity is specified by the optional keyword <code>eccentricity</code> which is only used for scattering type five. The default eccentricity value of zero defines isotropic scattering while positive values lead to scattering in the direction of the light and negative values lead to scattering in the opposite direction of the light. Larger values of e (or smaller values in the negative case) increase the directional property of the scattering.</p>
<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
<td><img class="center" width="640px" src="images/2/2c/RefImgHgscatt.gif"></td>
</tr>
<tr>
<td>
<p class="caption">The Henyey-Greenstein scattering function for different eccentricity values</p>
</td>
</tr>
</table>
<p class="Note"><strong>Note:</strong> See the section on <a href="r3_4.html#r3_4_4_2">Light Groups</a> for additional information when using scattering media in a light group.</p>
</div>
<a name="r3_4_8_3"></a>
<div class="content-level-h4" contains="Sampling Parameters & Methods" id="r3_4_8_3">
<h4>3.4.8.3 Sampling Parameters & Methods</h4>
<p>Media effects are calculated by sampling the media along the path of the ray. It uses a process called <em>Monte Carlo integration.</em> POV-Ray provides three different types of media sampling. The <code>method</code> keyword lets you specify what sampling type is used.</p>
<p class="Note"><strong>Note:</strong> As of version 3.5 the default sampling <code>method</code> is 3, and it's default for <code>intervals</code> is 1. Sampling methods 1 and 2 have been retained for legacy purposes.</p>
<p>Sample <code>method 3</code> uses adaptive sampling (similar to adaptive anti-aliasing) which is very much like the sampling method used in POV-Ray 3.0 atmosphere. This code was written from the ground-up to work with media. However, adaptive sampling works by taking another sample between two existing samples if there is too much variance in the original two samples. This leads to fewer samples being taken in areas where the effect from the media remains constant. The adaptive sampling is only performed if the minimum samples are set to 3 or more.</p>
<p>You can specify the anti-aliasing recursion depth using the <code>aa_level</code> keyword followed by an integer. You can specify the anti-aliasing threshold by using the <code>aa_threshold</code> followed by a float. The default for <code>aa_level</code> is 4 and the default <code>aa_threshold</code> is 0.1. <code>jitter</code> also works with method 3.</p>
<p class="Note"><strong>Note:</strong> It is usually best to only use one interval with method 3. Too many intervals can lead to artifacts, and POV will create more intervals if it needs them.</p>
<p>Sample <code>method 1</code> used the <code>intervals</code> keyword to specify the integer number of intervals used to sample the ray. For object media, the intervals are spread between the entry and exit points as the ray passes through the container object. For atmospheric media, the intervals spans the entire length of the ray from its start until it hits an object. For media types which interact with spotlights or cylinder lights, the intervals which are not illuminated by these light types are weighted differently than the illuminated intervals when distributing samples.</p>
<p>The <code>ratio</code> keyword distributes intervals differently between lit and unlit areas. The default value of <code>ratio 0.9</code> means that lit intervals get more samples than unlit intervals. Note that the total number of intervals must exceed the number of illuminated intervals. If a ray passes in and out of 8 spotlights but you have only specified 5 intervals then an error occurs.</p>
<p>The <code>samples</code> <em><code>Min</code></em>, <em><code>Max</code></em> keyword specifies the minimum and maximum number of samples taken per interval. The default values are <code>samples 1,1</code>. The value for Max may be omitted, in which case the range Min = Max will be used.</p>
<p>As each interval is sampled, the variance is computed. If the variance is below a threshold value, then no more samples are needed. The <code>variance</code> and <code>confidence</code> keywords specify the permitted variance allowed and the confidence that you are within that variance. The exact calculations are quite complex and involve chi-squared tests and other statistical principles too messy to describe here. The default values are <code>variance 1.0/128</code> and <code>confidence
0.9</code>. For slower more accurate results, decrease the variance and increase the confidence.</p>
<p class="Note"><strong>Note:</strong> The maximum number of samples limits the calculations even if the proper variance and confidence are never reached.</p>
<p>Sample <code>method 2</code> distributed samples evenly along the viewing ray or light ray. The latter can make things look smoother sometimes. If you specify a maximum number of samples higher than the minimum number of samples, POV will take additional samples, but they will be random, just like in method 1. Therefore, it is suggested you set the max samples equal to the minimum samples.
<code>jitter</code> will cause method 2 to look similar to method 1. It should be followed by a float, and a value of 1 will stagger the samples in the full range between samples.</p>
</div>
<a name="r3_4_8_4"></a>
<div class="content-level-h4" contains="Density" id="r3_4_8_4">
<h4>3.4.8.4 Density</h4>
<p>Particles of media are normally distributed in constant density throughout the media. However, the <code>density</code> statement allows you to vary the density across space using any of POV-Ray's pattern functions such as those used in textures. If no <code>density</code> statement is given then the density remains a constant value of 1.0 throughout the media. More than one <code>density</code> may be specified per <code>media</code> statement. See <a href="r3_4.html#r3_4_8_4_4">Multiple Density vs. Multiple Media</a>.</p>
<p>The syntax for <code>density</code> is:</p>
<pre>
DENSITY:
density {
[DENSITY_IDENTIFIER]
[DENSITY_TYPE]
[DENSITY_MODIFIER...]
}
DENSITY_TYPE:
PATTERN_TYPE | COLOR
DENSITY_MODIFIER:
PATTERN_MODIFIER | DENSITY_LIST | color_map { COLOR_MAP_BODY } |
colour_map { COLOR_MAP_BODY } | density_map { DENSITY_MAP_BODY }
</pre>
<p>The <code>density</code> statement may begin with an optional density identifier. All subsequent values modify the defaults or the values in the identifier. The next item is a pattern type. This is any one of POV-Ray's pattern functions such as <code><a href="r3_4.html#r3_4_7_1_3">bozo</a></code>, <code><a href="r3_4.html#r3_4_7_1_30">wood</a></code>, <code><a href="r3_4.html#r3_4_7_1_13">gradient</a></code>, <code><a href="r3_4.html#r3_4_7_1_29">waves</a></code>, etc. Of particular usefulness are the <code><a href="r3_4.html#r3_4_7_1_24">spherical</a></code>, <code><a href="r3_4.html#r3_4_7_1_20">planar</a></code>, <code><a href="r3_4.html#r3_4_7_1_7">cylindrical</a></code>, and <code><a href="r3_4.html#r3_4_7_1_2">boxed</a></code> patterns which were previously available only for use with our discontinued <code>halo</code> feature. All patterns return a value from 0.0 to 1.0. This value is interpreted as the density of the media at that particular point. See the section <a href="r3_4.html#r3_4_7">Pattern</a> for details on particular pattern types. Although a solid <em>COLOR</em> pattern is legal, in general it is used only when the <code>density</code> statement is inside a <code>density_map</code>.</p>
</div>
<a name="r3_4_8_4_1"></a>
<div class="content-level-h5" contains="General Density Modifiers" id="r3_4_8_4_1">
<h5>3.4.8.4.1 General Density Modifiers</h5>
<p>A <code>density</code> statement may be modified by any of the general pattern modifiers such as transformations, <code>turbulence</code> and <code>warp</code>. See <a href="r3_4.html#r3_4_7_5">Pattern Modifiers</a> for details. In addition, there are several density-specific modifiers which can be used.</p>
</div>
<a name="r3_4_8_4_2"></a>
<div class="content-level-h5" contains="Density with color_map" id="r3_4_8_4_2">
<h5>3.4.8.4.2 Density with color_map</h5>
<p>Typically, a <code>media</code> uses just one constant color throughout. Even if you vary the density, it is usually just one color which is specified by the <code>absorption</code>, <code>emission</code>, or <code>scattering</code> keywords. However, when using <code>emission</code> to simulate fire or explosions, the center of the flame (high density area) is typically brighter and white or yellow. The outer edge of the flame (less density) fades to orange, red, or in some cases deep blue. To model the density-dependent change in color which is visible, you may specify a <code>color_map</code>. The pattern function returns a value from 0.0 to 1.0 and the value is passed to the color map to compute what color or blend of colors is used. See <a href="r3_4.html#r3_4_6_1_2">Color Maps</a> for details on how pattern values work with <code>color_map</code>. This resulting color is multiplied by the <code>absorption</code>, <code>emission</code> and <code>scattering</code> color. Currently there is no way to specify different color maps for each media type within the same <code>media</code> statement.</p>
<p>Consider this example:</p>
<pre>
media {
emission 0.75
scattering {1, 0.5}
density {
spherical
color_map {
[0.0 rgb <0,0,0.5>]
[0.5 rgb <0.8, 0.8, 0.4>]
[1.0 rgb <1,1,1>]
}
}
}
</pre>
<p>The color map ranges from white at density 1.0 to bright yellow at density 0.5 to deep blue at density 0. Assume we sample a point at density 0.5. The emission is 0.75*<0.8,0.8,0.4> or <0.6,0.6,0.3>. Similarly the scattering color is 0.5*<0.8,0.8,0.4> or <0.4,0.4,0.2>.</p>
<p>For block pattern types <code>checker</code>, <code>hexagon</code>, and <code>brick</code> you may specify a color list such as this:</p>
<pre>
density {
checker
density {rgb<1,0,0>}
density {rgb<0,0,0>}
}
</pre>
<p>See <a href="r3_4.html#r3_4_6_1_4">Color List Pigments</a> which describes how <code>pigment</code> uses a color list. The same principles apply when using them with <code>density</code>.</p>
</div>
<a name="r3_4_8_4_3"></a>
<div class="content-level-h5" contains="Density Maps and Density Lists" id="r3_4_8_4_3">
<h5>3.4.8.4.3 Density Maps and Density Lists</h5>
<p>In addition to specifying blended colors with a color map you may create a blend of densities using a <code>density_map</code>. The syntax for a density map is identical to a color map except you specify a density in each map entry (and not a color).</p>
<p>The syntax for <code>density_map</code> is as follows:</p>
<pre>
DENSITY_MAP:
density_map { DENSITY_MAP_BODY }
DENSITY_MAP_BODY:
DENSITY_MAP_IDENTIFIER | DENSITY_MAP_ENTRY...
DENSITY_MAP_ENTRY:
[ Value DENSITY_BODY ]
</pre>
<p>Where <em><code>Value</code></em> is a float value between 0.0 and 1.0 inclusive and each <em>DENSITY_BODY</em> is anything which can be inside a <code>density{...}</code> statement. The <code>density</code> keyword and <code>{}</code> braces need not be specified.</p>
<p class="Note"><strong>Note:</strong> The <code>[]</code> brackets are part of the actual <em>DENSITY_MAP_ENTRY</em>. They are not notational symbols denoting optional parts. The brackets surround each entry in the density map.</p>
<p>There may be from 2 to 256 entries in the map.</p>
<p>Density maps may be nested to any level of complexity you desire. The densities in a map may have color maps or density maps or any type of density you want.</p>
<p>Density lists may also be used with block patterns such as <code>checker</code>, <code>hexagon</code> and <code>brick</code>, as well as the object pattern <code>object</code>.</p>
<p>For example:</p>
<pre>
density {
checker
density { Flame scale .8 }
density { Fire scale .5 }
}
</pre>
<p class="Note"><strong>Note:</strong> In the case of block patterns the <code>density</code> wrapping is required around the density information.</p>
<p>A density map is also used with the <code>average</code> density type. See <a href="r3_4.html#r3_4_7_4_1">Average</a> for details.</p>
<p>You may declare and use density map identifiers but the only way to declare a density block pattern list is to declare a density identifier for the entire density.</p>
</div>
<a name="r3_4_8_4_4"></a>
<div class="content-level-h5" contains="Multiple Density vs. Multiple Media" id="r3_4_8_4_4">
<h5>3.4.8.4.4 Multiple Density vs. Multiple Media</h5>
<p>It is possible to have more than one <code>media</code> specified per object and it is legal to have more than one <code>density</code> per <code>media</code>. The effects are quite different.</p>
<p>Consider this example:</p>
<pre>
object {
MyObject
pigment { rgbf 1 }
interior {
media {
density { Some_Density }
density { Another_Density }
}
}
}
</pre>
<p>As the media is sampled, calculations are performed for each density pattern at each sample point. The resulting samples are multiplied together. Suppose one density returned <code>rgb<.8,.8,.4></code> and the other returned <code>rgb<.25,.25,0></code>. The resulting color is <code>rgb<.2,.2,0></code>.</p>
<p class="Note"><strong>Note:</strong> In areas where one density returns zero, it will wipe out the other density. The end result is that only density areas which overlap will be visible. This is similar to a CSG intersection operation. Now consider:</p>
<pre>
object {
MyObject
pigment { rgbf 1 }
interior {
media {
density { Some_Density }
}
media {
density { Another_Density }
}
}
}
</pre>
<p>In this case each media is computed independently. The resulting colors are added together. Suppose one density and media returned <code>rgb<.8,.8,.4></code> and the other returned <code>rgb<.25,.25,0></code>. The resulting color is <code>rgb<1.05,1.05,.4></code>. The end result is that density areas which overlap will be especially bright and all areas will be visible. This is similar to a <a href="r3_4.html#r3_4_5_4">CSG</a> <a href="r3_4.html#r3_4_5_4_2">union</a> operation. See the sample scene <code>~scenes\interior\media\media4.pov</code> for an example which illustrates this.</p></div>
<a name="r3_4_8_1"></a>
<div class="content-level-h4" contains="Interior" id="r3_4_8_1">
<h4>3.4.8.1 Interior</h4>
<p>Introduced in POV-Ray 3.1 is an object modifier statement called <code>
interior</code>. The syntax is:</p>
<pre>
INTERIOR:
interior { [INTERIOR_IDENTIFIER] [INTERIOR_ITEMS...] }
INTERIOR_ITEM:
ior Value | caustics Value | dispersion Value |
dispersion_samples Samples | fade_distance Distance |
fade_power Power | fade_color <Color>
MEDIA...
</pre>
<p>Interior default values:</p>
<pre>
ior : 1.0
caustics : 0.0
dispersion : 1.0
dispersion_samples : 7
fade_distance : 0.0
fade_power : 0.0
fade_color : <0,0,0>
</pre>
<p>The <code>interior</code> contains items which describe the properties of the interior of the object. This is in contrast to the <code>texture</code> and <code>interior_texture</code> which describe the surface properties only. The interior of an object is only of interest if it has a transparent texture which allows you to see inside the object. It also applies only to solid objects which have a well-defined inside/outside distinction.</p>
<p class="Note"><strong>Note:</strong> The <code>open</code> keyword, or <code>clipped_by</code> modifier also allows you to see inside but interior features may not render properly. They should be avoided if accurate interiors are required.</p>
<p>
Interior identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.</p>
<pre>
INTERIOR_DECLARATION:
#declare IDENTIFIER = INTERIOR |
#local IDENTIFIER = INTERIOR
</pre>
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40 characters long and <em>INTERIOR</em> is any valid <code>interior</code> statement. See <a href="r3_3.html#r3_3_2_2_2">#declare vs. #local</a> for information on identifier scope.</p>
</div>
<a name="r3_4_8_1_1"></a>
<div class="content-level-h5" contains="Why are Interior and Media Necessary?" id="r3_4_8_1_1">
<h5>3.4.8.1.1 Why are Interior and Media Necessary?</h5>
<p>In previous versions of POV-Ray, most of the items in the <code>interior</code> statement were previously part of the <code><a href="r3_4.html#r3_4_6_3">finish</a></code> statement. Also the <code>halo</code> statement which was once part of the <code><a href="r3_4.html#r3_4_6_4">texture</a></code> statement has been discontinued and has been replaced by the <code><a href="r3_4.html#r3_4_8">media</a></code> statement which is part of <code>interior</code>.</p>
<p>
You are probably asking <strong>WHY?</strong> As explained earlier, the <code>interior</code> contains items which describe the properties of the interior of the object. This is in contrast to the <code>texture</code> which describes the surface properties only. However this is not just a philosophical change. There were serious inconsistencies in the old model.</p>
<p>
The main problem arises when a <code><a href="r3_4.html#r3_4_6_5_1">texture_map</a></code> or other patterned texture is used. These features allow you to create
textures that are a blend of two textures and which vary the entire texture from one point to another. It does its blending by fully evaluating the apparent color as though only one texture was applied and then fully reevaluating it with the other texture. The two final results are blended.</p>
<p> It is totally illogical to have a ray enter an object with one index or refraction and then recalculate with another index. The result is not an average of the two ior values. Similarly it makes no sense to have a ray enter at one ior and exit at a different ior without transitioning between them along the way. POV-Ray only calculates refraction as the ray enters or leaves. It cannot incrementally compute a changing ior through the interior of an object. Real world objects such as optical fibers or no-line bifocal eyeglasses can have variable iors but POV-Ray cannot simulate them.</p>
<p>
Similarly the <code>halo</code> calculations were not performed as the
syntax implied. Using a <code>halo</code> in such multi-textured objects did
not vary the <code>halo</code> through the interior of the object. Rather,
it computed two separate halos through the whole object and averaged the
results. The new design for <code>media</code> which replaces <code>
halo</code> makes it possible to have media that varies throughout the
interior of the object according to a pattern but it does so independently of
the surface texture. Because there are other changes in the design of this
feature which make it significantly different, it was not only moved to the
<code>interior</code> but the name was changed.</p>
<p>
During our development, someone asked if we will create patterned interiors
or a hypothetical <code>interior_map</code> feature. We will not. That would
defeat the whole purpose of moving these features in the first place. They
cannot be patterned and have logical or self-consistent results.</p>
</div>
<a name="r3_4_8_1_2"></a>
<div class="content-level-h5" contains="Empty and Solid Objects" id="r3_4_8_1_2">
<h5>3.4.8.1.2 Empty and Solid Objects</h5>
<p>It is very important that you know the basic concept behind empty and
solid objects in POV-Ray to fully understand how features like interior and
translucency are used. Objects in POV-Ray can either be solid, empty or
filled with (small) particles.</p>
<p>
A solid object is made from the material specified by its pigment and finish
statements (and to some degree its normal statement). By default all objects
are assumed to be solid. If you assign a stone texture to a sphere you will
get a ball made completely of stone. It is like you had cut this ball from
a block of stone. A glass ball is a massive sphere made of glass. You should
be aware that solid objects are conceptual things. If you clip away parts of
the sphere you will clearly see that the interior is empty and it just has
a very thin surface.</p>
<p>
This is not contrary to the concept of a solid object used in POV-Ray. It is
assumed that all space inside the sphere is covered by the sphere's
<code>interior</code>. Light passing through the object is affected by
attenuation and refraction properties. However there is no room for any other
particles like those used by fog or interior media.</p>
<p>
Empty objects are created by adding the <code>hollow</code> keyword (see
<a href="r3_4.html#r3_4_5_5_4">Hollow</a>) to the object statement. An empty (or hollow) object is
assumed to be made of a very thin surface which is of the material specified
by the pigment, finish and normal statements. The object's interior is
empty, it normally contains air molecules.</p>
<p>
An empty object can be filled with particles by adding fog or atmospheric
media to the scene or by adding an interior media to the object. It is very
important to understand that in order to fill an object with any kind of
particles it first has to be made hollow.</p>
<p>
There is a pitfall in the empty/solid object implementation that you have to
be aware of.</p>
<p>
In order to be able to put solid objects inside a media or fog, a test has
to be made for every ray that passes through the media. If this ray travels
through a solid object the media will not be calculated. This is what anyone
will expect. A solid glass sphere in a fog bank does not contain fog.</p>
<p>
The problem arises when the camera ray is inside any non-hollow object. In
this case the ray is already traveling through a solid object and even if the
media's container object is hit and it is hollow, the media will not be
calculated. There is no way of telling between these two cases.</p>
<p>
POV-Ray has to determine whether the camera is inside any object prior to
tracing a camera ray in order to be able to correctly render medias when the
camera is inside the container object. There is no way around doing
this.</p>
<p>
The solution to this problem (that will often happen with infinite objects
like planes) is to make those objects hollow too. Thus the ray will travel
through a hollow object, will hit the container object and the media will be
calculated.</p>
</div>
<a name="r3_4_8_1_3"></a>
<div class="content-level-h5" contains="Scaling objects with an interior" id="r3_4_8_1_3">
<h5>3.4.8.1.3 Scaling objects with an interior</h5>
<p>All the statements that can be put in an interior represent aspects of
the matter that an object is made of. Scaling an object, changing its size, does not change
its matter. Two pieces of the same quality steel, one twice as big as
the other, both have the same density. The bigger piece is quite a bit
heavier though.</p>
<p> So, in POV-Ray, if you design a lens from a glass with an ior of 1.5
and you scale it bigger, the focal distance of the lens will get longer
as the ior stays the same. For light attenuation it means that an object will be
<em>darker</em> after being scaled up. The light intensity decreases a certain
amount per pov-unit. The object has become bigger, more pov-units, so more light is faded.
The <code>fade_distance, fade_power</code> themselves have not been changed.</p>
<p> The same applies to media. Imagine media as a density of particles,
you specify 100 particles per cubic pov-unit. If we scale a 1 cubic
pov-unit object to be twice as big in every direction, we will have a
total of 800 particles in the object. The object will look different,
as we have more particles to look through. Yet the objects density is
still 100 particles per cubic pov-unit. In media this <em>particle
density</em> is set by the color after <code>emission</code>, <code>absorption</code>, or in
the <code>scattering</code> statement</p>
<pre>
#version 3.5;
global_settings {
assumed_gamma 1.0
}
camera {location <0, 0,-12.0> look_at 0 angle 30 }
#declare Container_T =
texture {
pigment {rgbt <1,1,1,1>}
finish {ambient 0 diffuse 0}
}
#declare Scale=2;
box { //The reference
<-1,-1,0>,<1,1,.3>
hollow
texture {Container_T}
interior {
media {
intervals 1
samples 1,1
emission 1
}
}
translate <-2.1,0,0>
}
box { //Object scaled twice as big
<-1,-1,0>,<1,1,.3> //looks different but same
hollow //particle density
texture {Container_T}
interior {
media {
intervals 1
samples 1,1
emission 1
}
}
scale Scale
translate<0,0,12>
}
box { //Object scaled twice as big
<-1,-1,0>,<1,1,.3> //looks the same but particle
hollow //density scaled down
texture {Container_T}
interior {
media {
intervals 1
samples 1,1
emission 1/Scale
}
}
scale Scale
translate<0,0,12>
translate<4.2,0,0>
}
</pre>
<p>The third object in the scene above, shows what to do, if you want to scale
the object <em>and</em> want it to keep the same look as before. The interior
feature has to be divided by the same amount, that the object was scaled by.
This is only possible when the object is scaled uniform.</p>
<p>In general, the correct approach is to scale the media density proportionally to
the change in container volume. For non-uniform scaling to get an unambiguous result,
that can be explained in physical terms, we need to do:</p>
<pre>
Density*sqrt(3)/vlength(Scale)
</pre>
<p>where Density is your original media density and Scale is the scaling
vector applied to the container.</p>
<p class="Note"><strong>Note:</strong> The density modifiers inside the <code>density{}</code>
statement are scaled along with the object.</p>
</div>
<a name="r3_4_8_1_4"></a>
<div class="content-level-h5" contains="Refraction" id="r3_4_8_1_4">
<h5>3.4.8.1.4 Refraction</h5>
<p>When light passes through a surface either into or out of a dense medium
the path of the ray of light is bent. Such bending is called <em>
refraction</em>. The amount of bending or refracting of light depends upon
the density of the material. Air, water, crystal and diamonds all have
different densities and thus refract differently. The <em>index of
refraction</em> or <em>ior</em> value is used by scientists to describe the
relative density of substances. The <code>ior</code> keyword is used in
POV-Ray in the <code>interior</code> to turn on refraction and to specify the
ior value. For example:</p>
<pre>
object { MyObject pigment {Clear } interior { ior 1.5 } }
</pre>
<p>The default ior value of 1.0 will give no refraction. The index of
refraction for air is 1.0, water is 1.33, glass is 1.5 and diamond is
2.4.</p>
<p>
Normally transparent or semi-transparent surfaces in POV-Ray do not refract
light. Earlier versions of POV-Ray required you to use the <code>
refraction</code> keyword in the <code>finish</code> statement to turn on
refraction. This is no longer necessary. Any non-zero <code>ior</code> value
now turns refraction on.</p>
<p>
In addition to turning refraction on or off, the old <code>refraction</code>
keyword was followed by a float value from 0.0 to 1.0. Values in between 0.0
and 1.0 would darken the refracted light in ways that do not correspond to
any physical property. Many POV-Ray scenes were created with intermediate
refraction values before this bug was discovered so the feature has been
maintained. A more appropriate way to reduce the brightness of refracted
light is to change the <code><a href="r3_3.html#r3_3_1_7_3">filter</a></code> or
<code><a href="r3_3.html#r3_3_1_7_3">transmit</a></code> value in the colors
specified in the pigment statement or to use the <code><a href="r3_4.html#r3_4_8_1">fade_power</a></code>
and <code><a href="r3_4.html#r3_4_8_1">fade_distance</a></code> keywords.
See <a href="r3_4.html#r3_4_8_1_6">Attenuation</a>.</p>
<p class="Note"><strong>Note:</strong> Neither the <code>ior</code> nor <code>refraction</code> keywords cause the
object to be transparent. Transparency only occurs if there is a non-zero
<code>filter</code> or <code>transmit</code> value in the color.</p>
<p>
The <code>refraction</code> and <code>ior</code> keywords were originally
specified in <code>finish</code> but are now properly specified in <code>
interior</code>. They are accepted in <code><a href="r3_4.html#r3_4_6_3">finish</a></code>
for backward compatibility and generate a warning message.</p>
</div>
<a name="r3_4_8_1_5"></a>
<div class="content-level-h5" contains="Dispersion" id="r3_4_8_1_5">
<h5>3.4.8.1.5 Dispersion</h5>
<p>For all materials with a ior different from 1.0 the refractive index is not
constant throughout the spectrum. It changes as a function of wavelength.
Generally the refractive index decreases as the wavelength increases. Therefore
light passing through a material will be separated according to wavelength.
This is known as chromatic dispersion.</p>
<p>By default POV-Ray does not calculate dispersion as light travels through a
transparent object. In order to get a more realistic effect the <code>dispersion
</code> and <code>dispersion_samples</code> keywords can be added to the
<code>interior{}</code> block. They will simulate dispersion by creating a
prismatic color effect in the object.</p>
<p>The <code>dispersion</code> value is the ratio of refractive indices for violet to
red. It controls the strength of dispersion (how much the colors are spread out) used.
A DISPERSION_VALUE of 1 will give no dispersion, good values are 1.01 to 1.1.</p>
<p class="Note"><strong>Note:</strong> There will be no dispersion, unless the <code>ior</code> keyword has
been specified in <code>interior{ }</code>. An ior of 1 is legal. The ior has no
influence on the dispersion strength, only on the angle of refraction.</p>
<p>As POV-Ray does not use wavelengths for raytracing, a spectrum is simulated.
The <code>dispersion_samples</code> value controls the amount of color-steps and
smoothness in the spectrum. The default value is 7, the minimum is 2. Values up to
100 or higher may be needed to get a very smooth result.</p>
</div>
<a name="r3_4_8_1_5_1"></a>
<div class="content-level-h6" contains="Dispersion & Caustics" id="r3_4_8_1_5_1">
<h6>3.4.8.1.5.1 Dispersion & Caustics</h6>
<p>Dispersion only affects the interior of an object and has no effect on faked
caustics (See <a href="r3_4.html#r3_4_8_1_7">Faked Caustics</a>).
<br>To see the effects of dispersion in caustics, photon mapping is needed. See the sections
<a href="r3_4.html#r3_4_4_4_2">Photons</a> and <a href="r3_4.html#r3_4_4_4_9_3">Photons and Dispersion</a>.
</p>
</div>
<a name="r3_4_8_1_6"></a>
<div class="content-level-h5" contains="Attenuation" id="r3_4_8_1_6">
<h5>3.4.8.1.6 Attenuation</h5>
<p>Light attenuation is used to model the decrease in light intensity as
the light travels through a transparent object. The keywords <code>fade_power</code>, <code>fade_distance</code> and <code>fade_color</code> are specified in the <code>interior</code> statement.</p>
<p>The <code>fade_distance</code> value determines the distance the light has to travel to reach half intensity while the <code>fade_power</code> value determines how fast the light will fall off. <code>fade_color</code> colorizes the attenuation. For realistic effects a fade power of 1 to 2 should be used. Default values for <code>fade_power</code> and <code>fade_distance</code> is 0.0 which turns this feature off. Default for <code>fade_color</code> is <code><0,0,0></code>, if <code>fade_color</code> is <code><1,1,1></code> there is no attenuation. The actual colors give colored attenuation. <code><1,0,0></code> looks red, not cyan as in media.</p>
<p>The attenuation is calculated by a formula similar to that used for light
source attenuation.</p>
<table class="centered" width="415x" cellpadding="0" cellspacing="10">
<tr>
<td>
<!--<img src="ref_tex/medatten.tex" alt="">---><img class="center" width="395px" src="images/8/81/RefImgMedatten.png">
</td>
</tr>
<tr>
<td>
<p class="caption">Media Attenuation</p>
</td>
</tr>
</table>
<p>If you set fade_power in the interior of an object at 1000 or above,
a realistic exponential attenuation function will be used:</p>
<pre> Attenuation = exp(-depth/fade_dist)</pre>
<p>The <code>fade_power</code> and <code>fade_distance</code> keywords were
originally specified in <code>finish</code> but are now properly specified in
<code>interior</code>. They are accepted in <code>finish</code> for backward
compatibility and generate a warning message.</p>
</div>
<a name="r3_4_8_1_7"></a>
<div class="content-level-h5" contains="Simulated Caustics" id="r3_4_8_1_7">
<h5>3.4.8.1.7 Simulated Caustics</h5>
<p>Caustics are light effects that occur if light is reflected or refracted
by specular reflective or refractive surfaces. Imagine a glass of water
standing on a table. If sunlight falls onto the glass you will see spots of
light on the table. Some of the spots are caused by light being reflected by
the glass while some of them are caused by light being refracted by the water
in the glass.</p>
<p>
Since it is a very difficult and time-consuming process to actually calculate those effects (though it is not impossible), see the sections <a href="r3_4.html#r3_4_4_4_2">Photons</a>. POV-Ray uses a quite simple method to simulate caustics caused by refraction. The method calculates the angle between the incoming light ray and the surface normal. Where they are nearly parallel it makes the shadow brighter. Where the angle is greater, the effect is diminished. Unlike real-world caustics, the effect does not vary based on distance. This caustic effect is limited to areas that are shaded by the transparent object. You will get no caustic effects from reflective surfaces nor in parts that are not shaded by the object.</p>
<p>
The <code>caustics</code> <em><code>Power</code></em> keyword controls the
effect. Values typically range from 0.0 to 1.0 or higher. Zero is the default
which is no caustics. Low, non-zero values give broad hot-spots while higher
values give tighter, smaller simulated focal points.</p>
<p>
The <code>caustics</code> keyword was originally specified in <code>
finish</code> but is now properly specified in <code>interior</code>. It is
accepted in <code>finish</code> for backward compatibility and generates a
warning message.</p>
</div>
<a name="r3_4_8_1_8"></a>
<div class="content-level-h5" contains="Object-Media" id="r3_4_8_1_8">
<h5>3.4.8.1.8 Object-Media</h5>
<p>The <code>interior</code> statement may contain one or more <code>media</code>
statements. Media is used to simulate suspended particles such as smoke,
haze, or dust. Or visible gasses such as steam or fire and explosions. When
used with an object interior, the effect is constrained by the object's
shape. The calculations begin when the ray enters an object and ends when
it leaves the object. This section only discusses media when used with
object interior. The complete syntax and an explanation of all of the
parameters and options for <code>media</code> is given in the section
<a href="r3_4.html#r3_4_8">Media</a>.</p>
<p>
Typically the object itself is given a fully transparent texture however
media also works in partially transparent objects. The texture pattern itself
does not effect the interior media except perhaps to create shadows on it.
The texture pattern of an object applies only to the surface shell. Any
interior media patterns are totally independent of the texture.</p>
<p>
In previous versions of POV-Ray, this feature was called <code>halo</code>
and was part of the <code>texture</code> specification along with <code>
pigment</code>, <code>normal</code>, and <code>finish</code>. See the section: <a href="r3_4.html#r3_4_8_1_1">Why are Interior and Media Necessary?</a> for an explanation of the reasons for the change.</p>
<p>Media may also be specified outside an object to simulate atmospheric
media. There is no constraining object in this case. If you only want media
effects in a particular area, you should use object media rather than only
relying upon the media pattern. In general it will be faster and more
accurate because it only calculates inside the constraining object. See
<a href="r3_4.html#r3_4_3_1">Atmospheric Media</a> for
details on unconstrained uses of media.</p>
<p>
You may specify more than one <code>media</code> statement per <code>
interior</code> statement. In that case, all of the media participate and
where they overlap, they add together.</p>
<p>
Any object which is supposed to have media effects inside it, whether those
effects are object media or atmospheric media, must have the <code>hollow on</code>
keyword applied. Otherwise the media is blocked. See the section: <a href="r3_4.html#r3_4_8_1_2">Empty and Solid Objects</a>
for details.</p></div>
<a name="r3_4_9"></a>
<div class="content-level-h3" contains="Include Files" id="r3_4_9">
<h3>3.4.9 Include Files</h3>
<p>This section covers the <em>include files</em> that come with every distribution of POV-Ray. File location varies, so see your platform specific documentation for more information.</p></div>
<a name="r3_4_9_1"></a>
<div class="content-level-h4" contains="Main Files" id="r3_4_9_1">
<h4>3.4.9.1 Main Files</h4>
<p>The <em>main</em> include files in alphabetical order:</p></div>
<a name="r3_4_9_1_1"></a>
<div class="content-level-h5" contains="Arrays.inc" id="r3_4_9_1_1">
<h5>3.4.9.1.1 Arrays.inc</h5>
<p>This file contains macros for manipulating arrays.</p>
<p><code>ARRAYS_WriteDF3(Array, FileName, BitDepth)</code>: Write an array to a df3 file.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array that contains the data.</li>
<li><code>FileName</code> = The name of the file to be written.</li>
<li><code>BitDepth</code> = The size of the binary word.</li>
</ul>
<p class="Note"><strong>Note:</strong> See the <a href="r3_3.html#r3_3_2_3_4">#write</a> directive for more information.</p>
<p><code>Rand_Array_Item(Array, Stream)</code>: Randomly Picks an item from a 1D array.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array from which to choose the item.</li>
<li><code>Stream</code> = A random number stream.</li>
</ul>
<p><code>Resize_Array(Array, NewSize)</code>: Resize a 1D array, retaining its contents.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array to be resized.</li>
<li><code>NewSize</code> = The desired new size of the array.</li>
</ul>
<p><code>Reverse_Array(Array)</code>: Reverses the order of items in a 1D array.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array to be reversed.</li>
</ul>
<p><code>Sort_Compare(Array, IdxA, IdxB)</code>: This macro is used by the <code>Sort_Array()</code>
and <code>Sort_Partial_Array()</code> macros. The given macro works for 1D arrays of floats, but
you can redefine it in your scene file for more complex situations, arrays of vectors or
multidimensional arrays for example. Just make sure your macro returns true if the item at IdxA <
the item at IdxB, and otherwise returns false.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array containing the data being sorted.</li>
<li><code>IdxA, IdxB</code> = The array offsets of the data elements being compared.</li>
</ul>
<p><code>Sort_Swap_Data(Array, IdxA, IdxB)</code>: This macro is used by the <code>Sort_Array()</code>
and <code>Sort_Partial_Array()</code> macros. The given macro works for 1D arrays only,
but you can redefine it in your scene file to handle multidimensional arrays if needed.
The only requirement is that your macro swaps the data at IdxA with that at IdxB.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array containing the data being sorted.</li>
<li><code>IdxA, IdxB</code> = The array offsets of the data elements being swapped.</li>
</ul>
<p><code>Sort_Array(Array)</code>: This macro sorts a 1D array of floats, though you can
redefine the <code>Sort_Compare()</code> and <code>Sort_Swap_Data()</code> macros to
handle multidimensional arrays and other data types.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array to be sorted.</li>
</ul>
<p><code>Sort_Partial_Array(Array, FirstInd, LastInd)</code>: This macro is like
<code>Sort_Array()</code>, but sorts a specific range of an array instead of the whole array.</p>
<p>Parameters:</p>
<ul>
<li><code>Array</code> = The array to be sorted.</li>
<li><code>FirstInd, LastInd</code> = The start and end indices of the range being sorted.</li>
</ul></div>
<a name="r3_4_9_1_2"></a>
<div class="content-level-h5" contains="Chars.inc" id="r3_4_9_1_2">
<h5>3.4.9.1.2 Chars.inc</h5>
<p>
This file includes 26 upper-case letter and other characters defined as objects.
The size of all characters is 4 * 5 * 1. The center of the bottom side of a character
face is set to the origin, so you may need to translate a character appropriately
before rotating it about the x or z axes.
</p>
<p>
Letters:<br>
<code>
char_A, char_B, char_C,<br>
char_D, char_E, char_F,<br>
char_G, char_H, char_I,<br>
char_J, char_K, char_L,<br>
char_M, char_N, char_O,<br>
char_P, char_Q, char_R,<br>
char_S, char_T, char_U,<br>
char_V, char_W, char_X,<br>
char_Y, char_Z<br>
</code>
</p>
<p>
Numerals:<br>
<code>
char_0, char_1,<br>
char_2, char_3,<br>
char_4, char_5,<br>
char_6, char_7,<br>
char_8, char_9<br>
</code>
</p>
<p>
Symbols:<br>
<code>
char_Dash, char_Plus, char_ExclPt,<br>
char_Amps, char_Num, char_Dol,<br>
char_Perc, char_Astr, char_Hat, <br>
char_LPar, char_RPar, char_AtSign,<br>
char_LSqu, char_RSqu<br>
</code>
</p>
<p>
Usage:</p>
<pre>
#include "chars.inc"
.
.
object {char_A ...}
</pre></div>
<a name="r3_4_9_1_3"></a>
<div class="content-level-h5" contains="Colors.inc" id="r3_4_9_1_3">
<h5>3.4.9.1.3 Colors.inc</h5>
<p>This file is mainly a list of predefined colors, but also has a few color
manipulation macros.</p>
</div>
<a name="r3_4_9_1_3_1"></a>
<div class="content-level-h6" contains="Predefined colors" id="r3_4_9_1_3_1">
<h6>3.4.9.1.3.1 Predefined colors</h6>
<p>This file contains 127 predefined colors that you can use in your scenes. Simply <code>#include</code> them in your scene file to use them:</p>
<pre>
#include "colors.inc"
</pre>
<p>These basic colors:</p>
<ul>
<li>Red</li>
<li>Green</li>
<li>Blue</li>
<li>Yellow</li>
<li>Cyan</li>
<li>Magenta</li>
<li>Clear</li>
<li>White</li>
<li>Black</li>
</ul>
<p>A series of <em>percentage</em> grays that are useful for fine-tuning lighting color values and for other areas where subtle variations of grays are needed, and a palette 99 additional color definitions are available. See the distribution file <code>~include/colors.inc</code> for more details.</p>
</div>
<a name="r3_4_9_1_3_2"></a>
<div class="content-level-h6" contains="Color macros" id="r3_4_9_1_3_2">
<h6>3.4.9.1.3.2 Color macros</h6>
<p>In POV-Ray all colors are handled in RGB color space with a component for
the amount of red, green and blue light. However, not everybody thinks this
is the most intuitive way to specify colors. For your convenience there are
macros included in colors.inc that converts between a few different types of
color spaces.</p>
<p>The three supported color spaces:</p>
<ul>
<li><code>RGB</code> = < Red, Green, Blue, Filter, Transmit ></li>
<li><code>HSL</code> = < Hue, Saturation, Lightness, Filter, Transmit ></li>
<li><code>HSV</code> = < Hue, Saturation, Value, Filter, Transmit ></li>
</ul>
<p class="Note"><strong>Note:</strong> The Hue parameter is given in degrees.</p>
<p><code>CHSL2RGB(Color)</code>: Converts a color given in <code>HSL</code> space to one in <code>RGB</code> space.</p>
<p>Parameters:</p>
<ul>
<li><code>Color</code> = <code>HSL</code> color to be converted.</li>
</ul>
<p><code>CRGB2HSL(Color)</code>: Converts a color given in <code>RGB</code> space to one in <code>HSL</code> space.</p>
<p>Parameters:</p>
<ul>
<li><code>Color</code> = <code>RGB</code> color to be converted.</li>
</ul>
<p><code>CHSV2RGB(Color)</code>: Converts a color given in <code>HSV</code> space to one in <code>RGB</code> space.</p>
<p>Parameters:</p>
<ul>
<li><code>Color</code> = <code>HSV</code> color to be converted.</li>
</ul>
<p><code>CRGB2HSV(Color)</code>: Converts a color given in <code>RGB</code> space to one in <code>HSV</code> space.</p>
<p>Parameters:</p>
<ul>
<li><code>Color</code> = <code>RGB</code> color to be converted.</li>
</ul>
<p><code>Convert_Color(SourceType, DestType, Color)</code>: Converts a color from one color space to another. Color spaces available are: <code>RGB</code>, <code>HSL</code>, and <code>HSV</code>:</p>
<p>Parameters:</p>
<ul>
<li><code>SourceType</code> = Color space of input color.</li>
<li><code>DestType</code> = Desired output color space.</li>
<li><code>Color</code> = Color to be converted, in SourceType color space.</li>
</ul></div>
<a name="r3_4_9_1_4"></a>
<div class="content-level-h5" contains="Consts.inc" id="r3_4_9_1_4">
<h5>3.4.9.1.4 Consts.inc</h5>
<p>This file defines a number of constants, including things such as mapping types and ior definitions.</p>
</div>
<a name="r3_4_9_1_4_1"></a>
<div class="content-level-h6" contains="Vector constants" id="r3_4_9_1_4_1">
<h6>3.4.9.1.4.1 Vector constants</h6>
<dl>
<dt><code>o</code> = < 0, 0, 0> (origin)</dt>
<dt><code>xy</code> = < 1, 1, 0></dt>
<dt><code>yz</code> = < 0, 1, 1></dt>
<dt><code>xz</code> = < 1, 0, 1></dt>
</dl>
</div>
<a name="r3_4_9_1_4_2"></a>
<div class="content-level-h6" contains="Map type constants" id="r3_4_9_1_4_2">
<h6>3.4.9.1.4.2 Map type constants</h6>
<dl>
<dt><code>Plane_Map</code> = 0</dt>
<dt><code>Sphere_Map</code> = 1</dt>
<dt><code>Cylinder_Map</code> = 2</dt>
<dt><code>Torus_Map</code> = 5</dt>
</dl>
</div>
<a name="r3_4_9_1_4_3"></a>
<div class="content-level-h6" contains="Interpolation type constants" id="r3_4_9_1_4_3">
<h6>3.4.9.1.4.3 Interpolation type constants</h6>
<dl>
<dt><code>Bi</code> = 2</dt>
<dt><code>Norm</code> = 4</dt>
</dl>
</div>
<a name="r3_4_9_1_4_4"></a>
<div class="content-level-h6" contains="Fog type constants" id="r3_4_9_1_4_4">
<h6>3.4.9.1.4.4 Fog type constants</h6>
<dl>
<dt><code>Uniform_Fog</code> = 1</dt>
<dt><code>Ground_Fog</code> = 2</dt>
</dl>
</div>
<a name="r3_4_9_1_4_5"></a>
<div class="content-level-h6" contains="Focal blur hexgrid constants" id="r3_4_9_1_4_5">
<h6>3.4.9.1.4.5 Focal blur hexgrid constants</h6>
<dl>
<dt><code>Hex_Blur1</code> = 7</dt>
<dt><code>Hex_Blur2</code> = 19</dt>
<dt><code>Hex_Blur3</code> = 37</dt>
</dl>
</div>
<a name="r3_4_9_1_4_6"></a>
<div class="content-level-h6" contains="IORs" id="r3_4_9_1_4_6">
<h6>3.4.9.1.4.6 IORs</h6>
<dl>
<dt><code>Air_Ior</code> = 1.000292</dt>
<dt><code>Amethyst_Ior</code> = 1.550</dt>
<dt><code>Apatite_Ior</code> = 1.635</dt>
<dt><code>Aquamarine_Ior</code> = 1.575</dt>
<dt><code>Beryl_Ior</code> = 1.575</dt>
<dt><code>Citrine_Ior</code> = 1.550</dt>
<dt><code>Crown_Glass_Ior</code> = 1.51</dt>
<dt><code>Corundum_Ior</code> = 1.765</dt>
<dt><code>Diamond_Ior</code> = 2.47</dt>
<dt><code>Emerald_Ior</code> = 1.575 </dt>
<dt><code>Flint_Glass_Ior</code> = 1.71</dt>
<dt><code>Flint_Glass_Heavy_Ior</code> = 1.8</dt>
<dt><code>Flint_Glass_Medium_Ior</code> = 1.63</dt>
<dt><code>Flint_Glass_Light_Ior</code> = 1.6</dt>
<dt><code>Fluorite_Ior</code> = 1.434</dt>
<dt><code>Gypsum_Ior</code> = 1.525</dt>
<dt><code>Ice_Ior</code> = 1.31</dt>
<dt><code>Plexiglas_Ior</code> = 1.5</dt>
<dt><code>Quartz_Ior</code> = 1.550</dt>
<dt><code>Quartz_Glass_Ior </code>= 1.458</dt>
<dt><code>Ruby_Ior</code> = 1.765</dt>
<dt><code>Salt_Ior</code> = 1.544</dt>
<dt><code>Sapphire_Ior</code> = 1.765</dt>
<dt><code>Topaz_Ior</code> = 1.620</dt>
<dt><code>Tourmaline_Ior</code> = 1.650</dt>
<dt><code>Water_Ior</code> = 1.33</dt>
</dl>
</div>
<a name="r3_4_9_1_4_7"></a>
<div class="content-level-h6" contains="Dispersion amounts" id="r3_4_9_1_4_7">
<h6>3.4.9.1.4.7 Dispersion amounts</h6>
<dl>
<dt><code>Quartz_Glass_Dispersion</code> = 1.012</dt>
<dt><code>Water_Dispersion</code> = 1.007</dt>
<dt><code>Diamond_Dispersion</code> = 1.035</dt>
<dt><code>Sapphire_Dispersion</code> = 1.015</dt>
</dl>
</div>
<a name="r3_4_9_1_4_8"></a>
<div class="content-level-h6" contains="Scattering media type constants" id="r3_4_9_1_4_8">
<h6>3.4.9.1.4.8 Scattering media type constants</h6>
<dl>
<dt><code>ISOTROPIC_SCATTERING</code> = 1;</dt>
<dt><code>MIE_HAZY_SCATTERING</code> = 2;</dt>
<dt><code>MIE_MURKY_SCATTERING</code> = 3;</dt>
<dt><code>RAYLEIGH_SCATTERING</code> = 4;</dt>
<dt><code>HENYEY_GREENSTEIN_SCATTERING</code> = 5;</dt>
</dl></div>
<a name="r3_4_9_1_5"></a>
<div class="content-level-h5" contains="Debug.inc" id="r3_4_9_1_5">
<h5>3.4.9.1.5 Debug.inc</h5>
<p>This file contains a set of macros designed to make debugging easier. It also functions like the old debug.inc, with the exception that you have to call the <code>Debug_Inc_Stack()</code> macro to get the include stack output.</p>
<p><code>Debug_Inc_Stack()</code>: Activates include file tracking, each included file will send a debug message when it is included.</p>
<p>Parameters:</p>
<ul>
<li>None.</li>
</ul>
<p><code>Set_Debug(Bool)</code>: Activate or deactivate the debugging macros.</p>
<p>Parameters:</p>
<ul>
<li><code>Bool</code> = A boolean (true/false) value.</li>
</ul>
<p><code>Debug_Message(Str)</code>: If debugging, sends the message to the debug stream.</p>
<p>Parameters:</p>
<ul>
<li><code>Str</code> = The desired message.</li>
</ul>
<p><code>Debug(Condition, Message)</code>: Sends a message to the <code>#debug</code> stream depending on a given condition.</p>
<p>Parameters:</p>
<ul>
<li><code>Condition</code> = Any boolean expression.</li>
<li><code>Message</code> = The message to be sent if Condition evaluates as <em>true</em>.</li>
</ul>
<p><code>Warning(Condition, Message)</code>: Sends a message to the <code>#warning</code> stream depending on a given condition.</p>
<p>Parameters:</p>
<ul>
<li><code>Condition</code> = Any boolean expression.</li>
<li><code>Message</code> = The message to be sent if Condition evaluates as <em>true</em>.</li>
</ul>
<p><code>Error(Condition, Message)</code>: Sends a message to the <code>#error</code> stream depending on a given condition.</p>
<p>Parameters:</p>
<ul>
<li><code>Condition</code> = Any boolean expression.</li>
<li><code>Message</code> = The message to be sent if Condition evaluates as <em>true</em>.</li>
</ul></div>
<a name="r3_4_9_1_6"></a>
<div class="content-level-h5" contains="Finish.inc" id="r3_4_9_1_6">
<h5>3.4.9.1.6 Finish.inc</h5>
<p>This file contains some predefined finishes.</p>
<dl>
<dt><code>Dull</code></dt>
<dd>Dull, with a large, soft specular highlight.</dd>
<dt><code>Shiny</code></dt>
<dd>Shiny, with a small, tight specular highlight.</dd>
<dt><code>Glossy</code></dt>
<dd>Very shiny with very tight specular highlights and a fair amount of reflection.</dd>
<dt><code>Phong_Dull</code></dt>
<dd>Dull, with a large, soft phong highlight.</dd>
<dt><code>Phong_Shiny</code></dt>
<dd>Shiny, with a small, tight phong highlight.</dd>
<dt><code>Phong_Glossy</code></dt>
<dd>Very shiny with very tight phong highlights and a fair amount of reflection.</dd>
<dt><code>Luminous</code></dt>
<dd>A glowing surface, unaffected by light_sources.</dd>
<dt><code>Mirror</code></dt>
<dd>A perfectly reflective surface, no highlights or shading.</dd>
</dl></div>
<a name="r3_4_9_1_7"></a>
<div class="content-level-h5" contains="Functions.inc" id="r3_4_9_1_7">
<h5>3.4.9.1.7 Functions.inc</h5>
<p>
This include file contains interfaces to internal functions as well as several predefined functions. The ID's used to access the internal
functions through calls to <em>internal(XX)</em>, are not guaranteed to stay the same between POV-Ray versions, so users are encouraged to
use the functions declared here.
</p>
<p>
The number of required parameters and what they control are also given in the include file, this chapter gives more information. For starter
values of the parameters, see the <code>~scenes/incdemo/i_internal.pov</code> demo file.
</p>
<p>Syntax to be used:</p>
<pre>
#include "functions.inc"
isosurface {
function { f_torus_gumdrop(x,y,z, P0) }
...
}
pigment {
function { f_cross_ellipsoids(x,y,z, P0, P1, P2, P3) }
COLOR_MAP ...
}
</pre>
<p>Some special parameters are found in several of these functions. These are described in the next section and later referred to as
<em>Cross section type</em>, <em>Field Strength</em>, <em>Field Limit</em>, <em>SOR</em> parameters.</p>
</div>
<a name="r3_4_9_1_7_1"></a>
<div class="content-level-h6" contains="Common Parameters" id="r3_4_9_1_7_1">
<h6>3.4.9.1.7.1 Common Parameters</h6>
</div>
<a name="r3_4_9_1_7_2"></a>
<div class="content-level-h6" contains="Cross Section Type" id="r3_4_9_1_7_2">
<h6>3.4.9.1.7.2 Cross Section Type</h6>
<p>In the helixes and spiral functions, the 9th parameter is the cross section type.</p>
<p>Some shapes are:</p>
<ul>
<li><code>0</code>: square</li>
<li><code>0.0 to 1.0</code>: rounded squares</li>
<li><code>1</code>: circle</li>
<li><code>1.0 to 2.0</code>: rounded diamonds</li>
<li><code>2</code>: diamond</li>
<li><code>2.0 to 3.0</code>: partially concave diamonds</li>
<li><code>3</code>: concave diamond</li>
</ul>
</div>
<a name="r3_4_9_1_7_3"></a>
<div class="content-level-h6" contains="Field Strength" id="r3_4_9_1_7_3">
<h6>3.4.9.1.7.3 Field Strength</h6>
<p>The numerical value at a point in space generated by the function is multiplied by the Field Strength. The set of points where the
function evaluates to zero are unaffected by any positive value of this parameter, so if you are just using the function on its own with
threshold = 0, the generated surface is still the same.</p>
<p>In some cases, the field strength has a considerable effect on the speed and accuracy of rendering the surface. In general, increasing
the field strength speeds up the rendering, but if you set the value too high the surface starts to break up and may disappear
completely.</p>
<p>Setting the field strength to a negative value produces the inverse of the surface, like making the function negative.</p>
</div>
<a name="r3_4_9_1_7_4"></a>
<div class="content-level-h6" contains="Field Limit" id="r3_4_9_1_7_4">
<h6>3.4.9.1.7.4 Field Limit</h6>
<p>This will not make any difference to the generated surface if you are using threshold that is within the field limit (and will kill the
surface completely if the threshold is greater than the field limit). However, it may make a huge difference to the rendering times.</p>
<p>If you use the function to generate a pigment, then all points that are a long way from the surface will have the same color, the color
that corresponds to the numerical value of the field limit.</p>
</div>
<a name="r3_4_9_1_7_5"></a>
<div class="content-level-h6" contains="SOR Switch" id="r3_4_9_1_7_5">
<h6>3.4.9.1.7.5 SOR Switch</h6>
<p>If greater than zero, the curve is swept out as a surface of revolution (SOR). If the value is zero or negative, the curve is extruded
linearly in the Z direction.</p>
</div>
<a name="r3_4_9_1_7_6"></a>
<div class="content-level-h6" contains="SOR Offset" id="r3_4_9_1_7_6">
<h6>3.4.9.1.7.6 SOR Offset</h6>
<p>If the SOR switch is on, then the curve is shifted this distance in the X direction before being swept out.</p>
</div>
<a name="r3_4_9_1_7_7"></a>
<div class="content-level-h6" contains="SOR Angle" id="r3_4_9_1_7_7">
<h6>3.4.9.1.7.7 SOR Angle</h6>
<p>If the SOR switch is on, then the curve is rotated this number of degrees about the Z axis before being swept out.</p>
</div>
<a name="r3_4_9_1_7_8"></a>
<div class="content-level-h6" contains="Invert Isosurface" id="r3_4_9_1_7_8">
<h6>3.4.9.1.7.8 Invert Isosurface</h6>
<p>Sometimes, when you render a surface, you may find that you get only the shape of the container. This could be caused by the fact that
some of the build in functions are defined inside out.</p>
<p>We can invert the isosurface by negating the whole function: <code>-(function) - threshold</code></p>
</div>
<a name="r3_4_9_1_7_9"></a>
<div class="content-level-h6" contains="Internal Functions" id="r3_4_9_1_7_9">
<h6>3.4.9.1.7.9 Internal Functions</h6>
<p>Here is a list of the internal functions in the order they appear in the <em>functions.inc</em> include file</p>
<p><code>f_algbr_cyl1(x,y,z, P0, P1, P2, P3, P4)</code>: An algebraic cylinder is what you get if you take any 2d curve and plot it in 3d.
The 2d curve is simply extruded along the third axis, in this case the z axis. With the SOR Switch switched on, the figure-of-eight curve
will be rotated around the Y axis instead of being extruded along the Z axis.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a></li>
<li><code>P1</code> : <a href="r3_4.html#r3_4_9_1_7_4">Field Limit</a></li>
<li><code>P2</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_algbr_cyl2(x,y,z, P0, P1, P2, P3, P4)</code>: An algebraic cylinder is what you
get if you take any 2d curve and plot it in 3d.
The 2d curve is simply extruded along the third axis, in this case the z axis.With the SOR Switch switched on, the cross section curve will
be rotated around the Y axis instead of being extruded along the Z axis.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : <a href="r3_4.html#r3_4_9_1_7_4">Field Limit</a></li>
<li><code>P2</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_algbr_cyl3(x,y,z, P0, P1, P2, P3, P4)</code>: An algebraic cylinder is what you get
if you take any 2d curve and plot it in 3d. The 2d curve
is simply extruded along the third axis, in this case the Z axis. With the SOR Switch switched on, the cross section curve will be rotated
around the Y axis instead of being extruded along the Z axis.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : <a href="r3_4.html#r3_4_9_1_7_4">Field Limit</a></li>
<li><code>P2</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_algbr_cyl4(x,y,z, P0, P1, P2, P3, P4)</code>: An algebraic cylinder is what you get
if you take any 2d curve and plot it in 3d. The 2d curve
is simply extruded along the third axis, in this case the z axis. With the SOR Switch switched on, the cross section curve will be rotated
around the Y axis instead of being extruded along the Z axis.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : <a href="r3_4.html#r3_4_9_1_7_4">Field Limit</a></li>
<li><code>P2</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_bicorn(x,y,z, P0, P1)</code>: The surface is a surface of revolution.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Scale. The mathematics of this surface suggest that the shape should be different
for different values of this parameter. In practice the difference in shape is hard to spot.
Setting the scale to 3 gives a surface with a radius of about 1 unit</li>
</ul>
<p><code>f_bifolia(x,y,z, P0, P1)</code>: The bifolia surface looks something like the top part of
a a paraboloid bounded below by another paraboloid.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Scale. The surface is always the same shape. Changing this parameter has the
same effect as adding a scale modifier. Setting the scale to 1 gives a surface with a radius
of about 1 unit</li>
</ul>
<p><code>f_blob(x,y,z, P0, P1, P2, P3, P4)</code>: This function generates blobs that are
similar to a CSG blob with two spherical components. This function only seems to work
with negative threshold settings.</p>
<ul>
<li><code>P0</code> : X distance between the two components</li>
<li><code>P1</code> : Blob strength of component 1</li>
<li><code>P2</code> : Inverse blob radius of component 1</li>
<li><code>P3</code> : Blob strength of component 2</li>
<li><code>P4</code> : Inverse blob radius of component 2</li>
</ul>
<p><code>f_blob2(x,y,z, P0, P1, P2, P3)</code>: The surface is similar to a CSG blob
with two spherical components.</p>
<ul>
<li><code>P0</code> : Separation. One blob component is at the origin, and the other is this distance away on the X axis</li>
<li><code>P1</code> : Inverse size. Increase this to decrease the size of the surface</li>
<li><code>P2</code> : Blob strength</li>
<li><code>P3</code> : Threshold. Setting this parameter to 1 and the threshold to zero has exactly the same effect as setting this parameter to zero and the threshold to -1</li>
</ul>
<p><code>f_boy_surface(x,y,z, P0, P1)</code>: For this surface, it helps if the field strength
is set low, otherwise the surface has a tendency to break up or disappear entirely. This has
the side effect of making the rendering times extremely long.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Scale. The surface is always the same shape. Changing this parameter has the
same effect as adding a scale modifier</li>
</ul>
<p><code>f_comma(x,y,z, P0)</code>: The <em>comma</em> surface is very much like a comma-shape.</p>
<ul>
<li><code>P0</code> : Scale</li></ul>
<p><code>f_cross_ellipsoids(x,y,z, P0, P1, P2, P3)</code>: The <em>cross ellipsoids</em> surface is
like the union of three crossed ellipsoids, one oriented along each axis.</p>
<ul>
<li><code>P0</code> : Eccentricity. When less than 1, the ellipsoids are oblate, when greater than 1 the
ellipsoids are prolate, when zero the ellipsoids are spherical (and hence the whole surface is a sphere)</li>
<li><code>P1</code> : Inverse size. Increase this to decrease the size of the surface</li>
<li><code>P2</code> : Diameter. Increase this to increase the size of the ellipsoids</li>
<li><code>P3</code> : Threshold. Setting this parameter to 1 and the threshold to zero has exactly the same
effect as setting this parameter to zero and the threshold to -1</li>
</ul>
<p><code>f_crossed_trough(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_cubic_saddle(x,y,z, P0)</code>: For this surface, it helps if the field strength is set quite low, otherwise the surface has a
tendency to break up or disappear entirely.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_cushion(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_devils_curve(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : Field Strength (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_devils_curve_2d(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The <code>f_devils_curve_2d</code> curve can be
extruded along the z axis, or using the SOR parameters it can be made into a surface of revolution.
The X and Y factors control the size of the central feature.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : X factor</li>
<li><code>P2</code> : Y factor</li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_dupin_cyclid(x,y,z, P0, P1, P2, P3, P4, P5)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Major radius of torus</li>
<li><code>P2</code> : Minor radius of torus</li>
<li><code>P3</code> : X displacement of torus</li>
<li><code>P4</code> : Y displacement of torus</li>
<li><code>P5</code> : Radius of inversion</li>
</ul>
<p><code>f_ellipsoid(x,y,z, P0, P1, P2)</code>: <code>f_ellipsoid</code> generates spheres and ellipsoids. Needs <code>threshold 1</code>.
Setting these scaling parameters to 1/n gives exactly the same effect as performing a scale operation to increase the scaling by <em>n</em>
in the corresponding direction.</p>
<ul>
<li><code>P0</code> : X scale (inverse)</li>
<li><code>P1</code> : Y scale (inverse)</li>
<li><code>P2</code> : Z scale (inverse)</li>
</ul>
<p><code>f_enneper(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_flange_cover(x,y,z, P0, P1, P2, P3)</code>:</p>
<ul>
<li><code>P0</code> : Spikiness. Set this to very low values to increase the spikes. Set it to 1 and you get a sphere</li>
<li><code>P1</code> : Inverse size. Increase this to decrease the size of the surface. (The other parameters
also drastically affect the size, but this parameter has no other effects)</li>
<li><code>P2</code> : Flange. Increase this to increase the flanges that appear between the spikes. Set it to 1 for no flanges</li>
<li><code>P3</code> : Threshold. Setting this parameter to 1 and the threshold to zero has exactly the
same effect as setting this parameter to zero and the threshold to -1</li>
</ul>
<p><code>f_folium_surface(x,y,z, P0, P1, P2)</code>: A <em>folium surface</em> looks something like a paraboloid glued to a plane.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Neck width factor - the larger you set this, the narrower the neck where the
paraboloid meets the plane</li>
<li><code>P2</code> : Divergence - the higher you set this value, the wider the paraboloid gets</li>
</ul>
<p><code>f_folium_surface_2d(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The <code>f_folium_surface_2d</code> curve can be
rotated around the X axis to generate the same 3d surface as the <code>f_folium_surface</code>, or it can be extruded
in the Z direction (by switching the SOR switch off) </p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Neck width factor - same as the 3d surface if you are revolving it around the Y axis</li>
<li><code>P2</code> : Divergence - same as the 3d surface if you are revolving it around the Y axis</li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_glob(x,y,z, P0)</code>: One part of this surface would actually go off to
infinity if it were not restricted by the contained_by shape.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_heart(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_helical_torus(x,y,z, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9)</code>: With some sets of parameters, it looks like a torus with a
helical winding around it. The
winding optionally has grooves around the outside.</p>
<ul>
<li><code>P0</code> : Major radius</li>
<li><code>P1</code> : Number of winding loops</li>
<li><code>P2</code> : Twistiness of winding. When zero, each winding loop is separate. When set to one,
each loop twists into the next one. When set to two, each loop twists into the one after next</li>
<li><code>P3</code> : Fatness of winding?</li>
<li><code>P4</code> : Threshold. Setting this parameter to 1 and the threshold to zero has s similar effect
as setting this parameter to zero and the threshold to 1</li>
<li><code>P5</code> : Negative minor radius? Reducing this parameter increases the minor radius of the
central torus. Increasing it can make the torus disappear and be replaced by a vertical column.
The value at which the surface switches from one form to the other depends on several other parameters</li>
<li><code>P6</code> : Another fatness of winding control?</li>
<li><code>P7</code> : Groove period. Increase this for more grooves</li>
<li><code>P8</code> : Groove amplitude. Increase this for deeper grooves</li>
<li><code>P9</code> : Groove phase. Set this to zero for symmetrical grooves</li>
</ul>
<p><code>f_helix1(x,y,z, P0, P1, P2, P3, P4, P5, P6)</code>:</p>
<ul>
<li><code>P0</code> : Number of helixes - e.g. 2 for a double helix</li>
<li><code>P1</code> : Period - is related to the number of turns per unit length</li>
<li><code>P2</code> : Minor radius (major radius > minor radius)</li>
<li><code>P3</code> : Major radius</li>
<li><code>P4</code> : Shape parameter. If this is greater than 1 then the tube becomes fatter in the y direction</li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_2">Cross section type</a></li>
<li><code>P6</code> : Cross section rotation angle (degrees)</li>
</ul>
<p><code>f_helix2(x,y,z, P0, P1, P2, P3, P4, P5, P6)</code>: Needs a negated function</p>
<ul>
<li><code>P0</code> : Not used</li>
<li><code>P1</code> : Period - is related to the number of turns per unit length</li>
<li><code>P2</code> : Minor radius (minor radius > major radius)</li>
<li><code>P3</code> : Major radius</li>
<li><code>P4</code> : Not used</li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_2">Cross section type</a></li>
<li><code>P6</code> : Cross section rotation angle (degrees)</li>
</ul>
<p><code>f_hex_x(x,y,z, P0)</code>: This creates a grid of hexagonal cylinders stretching along
the z-axis. The fatness is controlled
by the threshold value. When this value equals 0.8660254 or cos(30) the sides will touch, because
this is the distance between centers. Negating the function will inverse the surface and create a
honey-comb structure. This function is also useful as pigment function.</p>
<ul>
<li><code>P0</code> : No effect (but the syntax requires at least one parameter)</li>
</ul>
<p><code>f_hex_y(x,y,z, P0)</code>: This is function forms a lattice of infinite boxes
stretching along the z-axis. The fatness is
controlled by the threshold value. These boxes are rotated 60 degrees around centers, which
are 0.8660254 or cos(30) away from each other. This function is also useful as pigment function.</p>
<ul>
<li><code>P0</code> : No effect (but the syntax requires at least one parameter)</li>
</ul>
<p><code>f_hetero_mf(x,y,z, P0, P1, P2, P3, P4, P5)</code>: <code>f_hetero_mf (x,0,z)</code> makes multifractal height fields and patterns
of <em>1/f</em> noise. <em>Multifractal</em> refers to their characteristic of having a fractal dimension which varies with
altitude. Built from summing noise of a number of frequencies, the hetero_mf parameters determine how many, and which frequencies are to be
summed. An advantage to using these instead of a height_field {} from an image (a number of height field programs output multifractal types
of images) is that the hetero_mf function domain extends arbitrarily far in the x and z directions so huge landscapes can be made without
losing resolution or having to tile a height field. Other functions of interest are <code>f_ridged_mf</code> and <code>f_ridge</code>.</p>
<ul>
<li><code>P0</code> : H is the negative of the exponent of the basis noise frequencies used in building these functions (each frequency
<em>f's</em> amplitude is weighted by the factor <em>f - H</em> ). In landscapes, and many natural forms, the amplitude of high frequency
contributions are usually less than the lower frequencies. When H is 1, the fractalization is relatively smooth (<em>1/f noise</em>). As H
nears 0, the high frequencies contribute equally with low frequencies as in <em>white noise</em>.</li>
<li><code>P1</code> : <em>Lacunarity</em> is the multiplier used to get from one <em>octave</em> to the next. This parameter affects the
size of the frequency gaps in the pattern. Make this greater than 1.0</li>
<li><code>P2</code> : Octaves is the number of different frequencies added to the fractal. Each <em>Octave</em> frequency is the previous
one multiplied by <em>Lacunarity</em>, so that using a large number of octaves can get into very high frequencies very quickly.</li>
<li><code>P3</code> : Offset is the <em>base altitude</em> (sea level) used for the heterogeneous scaling</li>
<li><code>P4</code> : T scales the <em>heterogeneity</em> of the fractal. T=0 gives <em>straight 1/f</em> (no heterogeneous
scaling). T=1 suppresses higher frequencies at lower altitudes</li>
<li><code>P5</code> : Generator type used to generate the noise3d. 0, 1, 2 and 3 are legal values.</li>
</ul>
<p><code>f_hunt_surface(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_hyperbolic_torus(x,y,z, P0, P1, P2)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Major radius: separation between the centers of the tubes at the closest point</li>
<li><code>P2</code> : Minor radius: thickness of the tubes at the closest point</li>
</ul>
<p><code>f_isect_ellipsoids(x,y,z, P0, P1, P2, P3)</code>: The <em>isect ellipsoids</em> surface is like the
intersection of three crossed ellipsoids, one oriented along each axis.</p>
<ul>
<li><code>P0</code> : Eccentricity. When less than 1, the ellipsoids are oblate, when greater than 1 the
ellipsoids are prolate, when zero the ellipsoids are spherical (and hence the whole surface is a sphere)</li>
<li><code>P1</code> : Inverse size. Increase this to decrease the size of the surface</li>
<li><code>P2</code> : Diameter. Increase this to increase the size of the ellipsoids</li>
<li><code>P3</code> : Threshold. Setting this parameter to 1 and the threshold to zero has exactly
the same effect as setting this parameter to zero and the threshold to -1</li>
</ul>
<p><code>f_kampyle_of_eudoxus(x,y,z, P0, P1, P2)</code>: The <em>kampyle of eudoxus</em> is like two infinite planes with a dimple at the
center.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Dimple: When zero, the two dimples punch right through and meet at the center.
Non-zero values give less dimpling</li>
<li><code>P2</code> : Closeness: Higher values make the two planes become closer</li>
</ul>
<p><code>f_kampyle_of_eudoxus_2d(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The 2d curve that generates the above surface can be extruded in the
Z direction or rotated about various axes by using the SOR parameters.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Dimple: When zero, the two dimples punch right through and meet at the center.
Non-zero values give less dimpling</li>
<li><code>P2</code> : Closeness: Higher values make the two planes become closer</li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_klein_bottle(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_kummer_surface_v1(x,y,z, P0)</code>: The Kummer surface consists of a collection of radiating rods.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_kummer_surface_v2(x,y,z, P0, P1, P2, P3)</code>: Version 2 of the kummer surface only looks like radiating rods when the
parameters are set to particular negative values. For positive values it tends to look rather like a superellipsoid.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Rod width (negative): Setting this parameter to larger negative values increases the diameter of the rods</li>
<li><code>P2</code> : Divergence (negative): Setting this number to -1 causes the rods to become
approximately cylindrical. Larger negative values cause the rods to become fatter further
from the origin. Smaller negative numbers cause the rods to become narrower away from
the origin, and have a finite length</li>
<li><code>P3</code> : Influences the length of half of the rods.Changing the sign affects the other half of the rods. 0 has no effect</li>
</ul>
<p><code>f_lemniscate_of_gerono(x,y,z, P0)</code>: The <em>Lemniscate of Gerono</em> surface is an hourglass shape, or two teardrops with
their ends connected.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_lemniscate_of_gerono_2d(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The 2d version of the Lemniscate can be extruded in the Z
direction, or used as a surface of revolution to generate the equivalent of the 3d version, or revolved in different ways.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Size: increasing this makes the 2d curve larger and less rounded</li>
<li><code>P2</code> : Width: increasing this makes the 2d curve fatter</li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_mesh1(x,y,z, P0, P1, P2, P3, P4)</code>: The overall thickness of the threads is controlled by the isosurface threshold, not
by a parameter. If you render a mesh1 with zero threshold, the threads have zero thickness and are therefore invisible. Parameters P2 and P4
control the shape of the thread relative to this threshold parameter.</p>
<ul>
<li><code>P0</code> : Distance between neighboring threads in the x direction</li>
<li><code>P1</code> : Distance between neighboring threads in the z direction</li>
<li><code>P2</code> : Relative thickness in the x and z directions</li>
<li><code>P3</code> : Amplitude of the weaving effect. Set to zero for a flat grid</li>
<li><code>P4</code> : Relative thickness in the y direction</li>
</ul>
<p><code>f_mitre(x,y,z, P0)</code>: The <em>Mitre</em> surface looks a bit like an ellipsoid which has been nipped at each end with a pair
of sharp nosed pliers.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_nodal_cubic(x,y,z, P0)</code>: The <em>Nodal Cubic</em> is something like what you would get if you were to extrude the Stophid2D
curve along the X axis and then lean it over.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_noise3d(x,y,z)</code>:</p>
<p><code>f_noise_generator(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : Noise generator number</li>
</ul>
<p><code>f_odd(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_ovals_of_cassini(x,y,z, P0, P1, P2, P3)</code>: The Ovals of Cassini are a generalization of the torus shape.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Major radius - like the major radius of a torus</li>
<li><code>P2</code> : Filling. Set this to zero, and you get a torus. Set this to a higher value and the hole in the middle starts to heal
up. Set it even higher and you get an ellipsoid with a dimple</li>
<li><code>P3</code> : Thickness. The higher you set this value, the plumper is the result</li>
</ul>
<p><code>f_paraboloid(x,y,z, P0)</code>: This paraboloid is the surface of revolution that you get if you rotate a parabola about the Y
axis.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_parabolic_torus(x,y,z, P0, P1, P2)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Major radius</li>
<li><code>P2</code> : Minor radius</li>
</ul>
<p><code>f_ph(x,y,z)</code>: When used alone, the <em>PH</em> function gives a surface that consists of all points that are at a particular
latitude, i.e. a cone. If you use a threshold of zero (the default) this gives a cone of width zero, which is invisible. Also look at
<code>f_th</code> and <code>f_r</code>
</p>
<p><code>f_pillow(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a></li>
</ul>
<p><code>f_piriform(x,y,z, P0)</code>: The piriform surface looks rather like half a lemniscate.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a></li>
</ul>
<p><code>f_piriform_2d(x,y,z, P0, P1, P2, P3, P4, P5, P6)</code>: The 2d version of the <em>Piriform</em> can be extruded in the Z
direction, or used as a surface of revolution to generate the equivalent of the 3d version.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Size factor 1: increasing this makes the curve larger</li>
<li><code>P2</code> : Size factor 2: making this less negative makes the curve larger but also thinner</li>
<li><code>P3</code> : Fatness: increasing this makes the curve fatter</li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P6</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_poly4(x,y,z, P0, P1, P2, P3, P4)</code>: This <code>f_poly4</code> can be used to generate the surface of revolution of any
polynomial up to degree 4. To put it another way: If we call the parameters A, B, C, D, E; then this function generates the surface of
revolution formed by revolving <code>x = A + By + Cy2 + Dy3 + Ey4</code> around the Y axis.</p>
<ul>
<li><code>P0</code> : Constant</li>
<li><code>P1</code> : Y coefficient</li>
<li><code>P2</code> : Y2 coefficient</li>
<li><code>P3</code> : Y3 coefficient</li>
<li><code>P4</code> : Y4 coefficient</li>
</ul>
<p><code>f_polytubes(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The <em>Polytubes</em> surface consists of a number of tubes. Each tube follows
a 2d curve which is specified by a polynomial of degree 4 or less. If we look at the parameters, then this function generates <em>P0</em>
tubes which all follow the equation <code>x = P1 + P2y + P3y2 + P4y3 + P5y4</code> arranged around the Y axis. This function needs a
positive threshold (fatness of the tubes).</p>
<ul>
<li><code>P0</code> : Number of tubes</li>
<li><code>P1</code> : Constant</li>
<li><code>P2</code> : Y coefficient</li>
<li><code>P3</code> : Y2 coefficient</li>
<li><code>P4</code> : Y3 coefficient</li>
<li><code>P5</code> : Y4 coefficient</li>
</ul>
<p><code>f_quantum(x,y,z, P0)</code>: It resembles the shape of the electron density cloud for one of the d orbitals.</p>
<ul>
<li><code>P0</code> : Not used, but required</li>
</ul>
<p><code>f_quartic_paraboloid(x,y,z, P0)</code>: The <em>Quartic Paraboloid</em> is similar to a paraboloid, but has a squarer shape.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_quartic_saddle(x,y,z, P0)</code>: The <em>Quartic saddle</em> is similar to a saddle, but has a squarer shape.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a></li>
</ul>
<p><code>f_quartic_cylinder(x,y,z, P0, P1, P2)</code>: The <em>Quartic cylinder</em> looks a bit like a cylinder that is swallowed an
egg.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Diameter of the <em>egg</em></li>
<li><code>P2</code> : Controls the width of the tube and the vertical scale of the <em>egg</em></li>
</ul>
<p><code>f_r(x,y,z)</code>: When used alone, the <em>R</em> function gives a surface that consists of all the points that are a specific
distance (threshold value) from the origin, i.e. a sphere. Also look at <code>f_ph</code> and <code>f_th</code></p>
<p><code>f_ridge(x,y,z, P0, P1, P2, P3, P4, P5)</code>: This function is mainly intended for modifying other surfaces as you might use a
height field or to use as pigment function. Other functions of interest are <code>f_hetero_mf</code> and <code>f_ridged_mf</code>.</p>
<ul>
<li><code>P0</code> : Lambda</li>
<li><code>P1</code> : Octaves</li>
<li><code>P2</code> : Omega</li>
<li><code>P3</code> : Offset</li>
<li><code>P4</code> : Ridge</li>
<li><code>P5</code> : Generator type used to generate the noise3d. 0, 1, 2 and 3 are legal values.</li>
</ul>
<p><code>f_ridged_mf(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The <em>Ridged Multifractal</em> surface can be used to create multifractal
height fields and patterns. <em>Multifractal</em> refers to their characteristic of having a fractal dimension which varies with altitude.
They are built from summing noise of a number of frequencies. The f_ridged_mf parameters determine how many, and which frequencies are to be
summed, and how the different frequencies are weighted in the sum.</p>
<p>An advantage to using these instead of a <code>height_field{}</code> from an image is that the ridged_mf function domain extends
arbitrarily far in the x and z directions so huge landscapes can be made without losing resolution or having to tile a height field. Other
functions of interest are <code>f_hetero_mf</code> and <code>f_ridge</code>.</p>
<ul>
<li><code>P0</code> : H is the negative of the exponent of the basis noise frequencies used in building these
functions (each frequency f's amplitude is weighted by the factor fE- H ). When H is 1, the
fractalization is relatively smooth. As H nears 0, the high frequencies contribute equally with
low frequencies</li>
<li><code>P1</code> : Lacunarity is the multiplier used to get from one <em>octave</em> to the next in the <em>fractalization</em>. This
parameter affects the size of the frequency gaps in the pattern. (Use values greater than 1.0)</li>
<li><code>P2</code> : Octaves is the number of different frequencies added to the fractal. Each octave
frequency is the previous one multiplied by <em>Lacunarity</em>. So, using a large number of octaves can
get into very high frequencies very quickly</li>
<li><code>P3</code> : Offset gives a fractal whose fractal dimension changes from altitude to altitude. The high
frequencies at low altitudes are more damped than at higher altitudes, so that lower altitudes are
smoother than higher areas</li>
<li><code>P4</code> : Gain weights the successive contributions to the accumulated fractal result to make
creases stick up as ridges</li>
<li><code>P5</code> : Generator type used to generate the noise3d. 0, 1, 2 and 3 are legal values.</li>
</ul>
<p><code>f_rounded_box(x,y,z, P0, P1, P2, P3)</code>: The Rounded Box is defined in a cube from <-1, -1, -1> to <1, 1, 1>. By
changing the <em>Scale</em> parameters, the size can be adjusted, without affecting the Radius of curvature.</p>
<ul>
<li><code>P0</code> : Radius of curvature. Zero gives square corners, 0.1 gives corners that match <code>sphere {0, 0.1}</code></li>
<li><code>P1</code> : Scale x</li>
<li><code>P2</code> : Scale y</li>
<li><code>P3</code> : Scale z</li>
</ul>
<p><code>f_sphere(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code>: radius of the sphere</li>
</ul>
<p><code>f_spikes(x,y,z, P0, P1, P2, P3, P4)</code>:</p>
<ul>
<li><code>P0</code> : Spikiness. Set this to very low values to increase the spikes. Set it to 1 and you get a sphere</li>
<li><code>P1</code> : Hollowness. Increasing this causes the sides to bend in more</li>
<li><code>P2</code> : Size. Increasing this increases the size of the object</li>
<li><code>P3</code> : Roundness. This parameter has a subtle effect on the roundness of the spikes</li>
<li><code>P4</code> : Fatness. Increasing this makes the spikes fatter</li>
</ul>
<p><code>f_spikes_2d(x,y,z, P0, P1, P2, P3)</code>:</p>
<ul>
<li><code>P0</code> : Height of central spike</li>
<li><code>P1</code> : Frequency of spikes in the X direction</li>
<li><code>P2</code> : Frequency of spikes in the Z direction</li>
<li><code>P3</code> : Rate at which the spikes reduce as you move away from the center</li>
</ul>
<p><code>f_spiral(x,y,z, P0, P1, P2, P3, P4, P5)</code>:</p>
<ul>
<li><code>P0</code> : Distance between windings</li>
<li><code>P1</code> : Thickness</li>
<li><code>P2</code> : Outer radius of the spiral. The surface behaves as if it is contained_by a sphere of this diameter</li>
<li><code>P3</code> : Not used</li>
<li><code>P4</code> : Not used</li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_2">Cross section type</a></li>
</ul>
<p><code>f_steiners_roman(x,y,z, P0)</code>: The <em>Steiners Roman</em> is composed of four identical triangular pads which together make
up a sort of rounded tetrahedron. There are creases along the X, Y and Z axes where the pads meet.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_strophoid(x,y,z, P0, P1, P2, P3)</code>: The <em>Strophoid</em> is like an infinite plane with a bulb sticking out of it.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Size of bulb. Larger values give larger bulbs. Negative values give a bulb on the other side of the plane</li>
<li><code>P2</code> : Sharpness. When zero, the bulb is like a sphere that just touches the plane. When
positive, there is a crossover point. When negative the bulb simply bulges out of the plane like a pimple</li>
<li><code>P3</code> : Flatness. Higher values make the top end of the bulb fatter</li>
</ul>
<p><code>f_strophoid_2d(x,y,z, P0, P1, P2, P3, P4, P5, P6)</code>: The 2d strophoid curve can be extruded in the Z direction or rotated
about various axes by using the SOR parameters.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a></li>
<li><code>P1</code> : Size of bulb. Larger values give larger bulbs. Negative values give a bulb on the other side of the plane</li>
<li><code>P2</code> : Sharpness. When zero, the bulb is like a sphere that just touches the plane. When positive, there is a crossover
point. When negative the bulb simply bulges out of the plane like a pimple</li>
<li><code>P3</code> : Fatness. Higher values make the top end of the bulb fatter</li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P6</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
<p><code>f_superellipsoid(x,y,z, P0, P1)</code>: Needs a negative field strength or a negated function.</p>
<ul>
<li><code>P0</code> : east-west exponentx</li>
<li><code>P1</code> : north-south exponent</li>
</ul>
<p><code>f_th(x,y,z)</code>: <code>f_th()</code> is a function that is only useful when combined with other surfaces. It produces a value
which is equal to the <em>theta</em> angle, in radians, at any point. The theta angle is like the longitude coordinate on the Earth. It
stays the same as you move north or south, but varies from east to west. Also look at <code>f_ph</code> and <code>f_r</code>
</p>
<p><code>f_torus(x,y,z, P0, P1)</code>:</p>
<ul>
<li><code>P0</code> : Major radius</li>
<li><code>P1</code> : Minor radius</li>
</ul>
<p><code>f_torus2(x,y,z, P0, P1, P2)</code>: This is different from the f_torus function which just has the major and minor radii as
parameters.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a
negated function)</li>
<li><code>P1</code> : Major radius</li>
<li><code>P2</code> : Minor radius</li>
</ul>
<p><code>f_torus_gumdrop(x,y,z, P0)</code>: The <em>Torus Gumdrop</em> surface is something like a torus with a couple of gumdrops hanging
off the end.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_umbrella(x,y,z, P0)</code>:</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
</ul>
<p><code>f_witch_of_agnesi(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The <em>Witch of Agnesi</em> surface looks something like a witches
hat.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Controls the width of the spike. The height of the spike is always about 1 unit</li>
</ul>
<p><code>f_witch_of_agnesi_2d(x,y,z, P0, P1, P2, P3, P4, P5)</code>: The 2d version of the <em>Witch of Agnesi</em> curve can be extruded in
the Z direction or rotated about various axes by use of the SOR parameters.</p>
<ul>
<li><code>P0</code> : <a href="r3_4.html#r3_4_9_1_7_3">Field Strength</a> (Needs a negative field strength or a negated function)</li>
<li><code>P1</code> : Controls the size of the spike</li>
<li><code>P2</code> : Controls the height of the spike</li>
<li><code>P3</code> : <a href="r3_4.html#r3_4_9_1_7_5">SOR Switch</a></li>
<li><code>P4</code> : <a href="r3_4.html#r3_4_9_1_7_6">SOR Offset</a></li>
<li><code>P5</code> : <a href="r3_4.html#r3_4_9_1_7_7">SOR Angle</a></li>
</ul>
</div>
<a name="r3_4_9_1_7_10"></a>
<div class="content-level-h6" contains="Pre defined functions" id="r3_4_9_1_7_10">
<h6>3.4.9.1.7.10 Pre defined functions</h6>
<p><code>eval_pigment(Pigm, Vect)</code>: This macro evaluates the color of a pigment at a specific point. Some pigments require more
information than simply a point, slope pattern based pigments for example, and will not work with this macro. However, most pigments will
work fine.</p>
<p>Parameters:</p>
<ul>
<li><code>Vect</code> = The point at which to evaluate the pigment.</li>
<li><code>Pigm</code> = The pigment to evaluate.</li>
</ul>
<p><code>f_snoise3d(x, y, z)</code>: Just like f_noise3d(), but returns values in the range [-1, 1].</p>
<p><code>f_sine_wave(val, amplitude, frequency)</code>: Turns a ramping waveform into a sine waveform.</p>
<p><code>f_scallop_wave(val, amplitude, frequency)</code>: Turns a ramping waveform into a <em>scallop wave</em> waveform.
</p>
</div>
<a name="r3_4_9_1_7_11"></a>
<div class="content-level-h6" contains="Pattern functions" id="r3_4_9_1_7_11">
<h6>3.4.9.1.7.11 Pattern functions</h6>
<p>Predefined pattern functions, useful for building custom function patterns or performing <em>displacement mapping</em> on isosurfaces.
Many of them are not really useful for these purposes, they are simply included for completeness.</p>
<p>Some are not implemented at all because they require special parameters that must be specified in the definition, or information that is
not available to pattern functions. For this reason, you probably would want to define your own versions of these functions.
</p>
<p>All of these functions take three parameters, the XYZ coordinates of the point to evaluate the pattern at.</p>
<dl>
<dt><code>f_agate(x, y, z)</code></dt>
<dt><code>f_boxed(x, y, z)</code></dt>
<dt><code>f_bozo(x, y, z)</code></dt>
<dt><code>f_brick(x, y, z)</code></dt>
<dt><code>f_bumps(x, y, z)</code></dt>
<dt><code>f_checker(x, y, z)</code></dt>
<dt><code>f_crackle(x, y, z)</code></dt>
<dd> This pattern has many more options, this function uses the defaults.</dd>
<dt><code>f_cylindrical(x, y, z)</code></dt>
<dt><code>f_dents(x, y, z)</code></dt>
<dt><code>f_gradientX(x, y, z)</code></dt>
<dt><code>f_gradientY(x, y, z)</code></dt>
<dt><code>f_gradientZ(x, y, z)</code></dt>
<dt><code>f_granite(x, y, z)</code></dt>
<dt><code>f_hexagon(x, y, z)</code></dt>
<dt><code>f_leopard(x, y, z)</code></dt>
<dt><code>f_mandel(x, y, z)</code></dt>
<dd> Only the basic mandel pattern is implemented, its variants
and the other fractal patterns are not implemented.</dd>
<dt><code>f_marble(x, y, z)</code></dt>
<dt><code>f_onion(x, y, z)</code></dt>
<dt><code>f_planar(x, y, z)</code></dt>
<dt><code>f_radial(x, y, z)</code></dt>
<dt><code>f_ripples(x, y, z)</code></dt>
<dt><code>f_spherical(x, y, z)</code></dt>
<dt><code>f_spiral1(x, y, z)</code></dt>
<dt><code>f_spiral2(x, y, z)</code></dt>
<dt><code>f_spotted(x, y, z)</code></dt>
<dt><code>f_waves(x, y, z)</code></dt>
<dt><code>f_wood(x, y, z)</code></dt>
<dt><code>f_wrinkles(x, y, z)</code></dt>
</dl></div>
<a name="r3_4_9_1_8"></a>
<div class="content-level-h5" contains="Glass.inc" id="r3_4_9_1_8">
<h5>3.4.9.1.8 Glass.inc</h5>
<p>This file contains glass materials using new features introduced in POV 3.1 and 3.5. The old glass.inc
file is still included for backwards compatibility (it is named glass_old.inc, and is included
by glass.inc, so you do not need to change any scenes), but these materials will give more
realistic results.</p>
</div>
<a name="r3_4_9_1_8_1"></a>
<div class="content-level-h6" contains="Glass colors (with transparency)" id="r3_4_9_1_8_1">
<h6>3.4.9.1.8.1 Glass colors (with transparency)</h6>
<table summary="glass.inc glass colors with transparency" cellspacing="5" cellpadding="5" width="100%">
<tr valign="top">
<td width="33%">
<code>
Col_Glass_Beerbottle<br>
Col_Glass_Bluish<br>
Col_Glass_Clear<br>
Col_Glass_Dark_Green<br>
</code>
</td>
<td width="33%">
<code>
Col_Glass_General<br>
Col_Glass_Green<br>
Col_Glass_Old<br>
Col_Glass_Orange<br>
</code>
</td>
<td width="33%">
<code>
Col_Glass_Ruby<br>
Col_Glass_Vicksbottle<br>
Col_Glass_Winebottle<br>
Col_Glass_Yellow<br>
</code>
</td>
</tr>
</table>
</div>
<a name="r3_4_9_1_8_2"></a>
<div class="content-level-h6" contains="Glass colors (without transparency, for fade_color)" id="r3_4_9_1_8_2">
<h6>3.4.9.1.8.2 Glass colors (without transparency, for fade_color)</h6>
<table summary="glass.inc glass colors without transparency for fade_color" cellspacing="5" cellpadding="5" width="100%">
<tr valign="top">
<td width="33%">
<code>
Col_Amber_01<br>
Col_Amber_02<br>
Col_Amber_03<br>
Col_Amber_04<br>
Col_Amber_05<br>
</code>
</td>
<td width="33%">
<code>
Col_Amber_06<br>
Col_Amber_07<br>
Col_Amber_08<br>
Col_Amber_09<br>
Col_Amethyst_01<br>
</code>
</td>
<td width="33%">
<code>
Col_Amethyst_02<br>
Col_Amethyst_03<br>
Col_Amethyst_04<br>
Col_Amethyst_05<br>
Col_Amethyst_06<br>
</code>
</td>
</tr>
<tr valign="top">
<td>
<code>
Col_Apatite_01<br>
Col_Apatite_02<br>
Col_Apatite_03<br>
Col_Apatite_04<br>
Col_Apatite_05<br>
</code>
</td>
<td>
<code>
Col_Aquamarine_01<br>
Col_Aquamarine_02<br>
Col_Aquamarine_03<br>
Col_Aquamarine_04<br>
Col_Aquamarine_05<br>
</code>
</td>
<td>
<code>
Col_Aquamarine_06<br>
Col_Azurite_01<br>
Col_Azurite_02<br>
Col_Azurite_03<br>
Col_Azurite_04<br>
</code>
</td>
</tr>
<tr valign="top">
<td>
<code>
Col_Beerbottle<br>
Col_Blue_01<br>
Col_Blue_02<br>
Col_Blue_03<br>
Col_Blue_04<br>
</code>
</td>
<td>
<code>
Col_Citrine_01<br>
Col_Dark_Green<br>
Col_Emerald_01<br>
Col_Emerald_02<br>
Col_Emerald_03<br>
</code>
</td>
<td>
<code>
Col_Emerald_04<br>
Col_Emerald_05<br>
Col_Emerald_06<br>
Col_Emerald_07<br>
Col_Fluorite_01<br>
</code>
</td>
</tr>
<tr valign="top">
<td>
<code>
Col_Fluorite_02<br>
Col_Fluorite_03<br>
Col_Fluorite_04<br>
Col_Fluorite_05<br>
Col_Fluorite_06<br>
</code>
</td>
<td>
<code>
Col_Fluorite_07<br>
Col_Fluorite_08<br>
Col_Fluorite_09<br>
Col_Green<br>
Col_Green_01<br>
</code>
</td>
<td>
<code>
Col_Green_02<br>
Col_Green_03<br>
Col_Green_04<br>
Col_Gypsum_01<br>
Col_Gypsum_02<br>
</code>
</td>
</tr>
<tr valign="top">
<td>
<code>
Col_Gypsum_03<br>
Col_Gypsum_04<br>
Col_Gypsum_05<br>
Col_Gypsum_06<br>
Col_Orange<br>
</code>
</td>
<td>
<code>
Col_Red_01<br>
Col_Red_02<br>
Col_Red_03<br>
Col_Red_04<br>
Col_Ruby<br>
</code>
</td>
<td>
<code>
Col_Ruby_01<br>
Col_Ruby_02<br>
Col_Ruby_03<br>
Col_Ruby_04<br>
Col_Ruby_05<br>
</code>
</td>
</tr>
<tr valign="top">
<td>
<code>
Col_Sapphire_01<br>
Col_Sapphire_02<br>
Col_Sapphire_03<br>
Col_Topaz_01<br>
Col_Topaz_02<br>
</code>
</td>
<td>
<code>
Col_Topaz_03<br>
Col_Tourmaline_01<br>
Col_Tourmaline_02<br>
Col_Tourmaline_03<br>
Col_Tourmaline_04<br>
</code>
</td>
<td>
<code>
Col_Tourmaline_05<br>
Col_Tourmaline_06<br>
Col_Vicksbottle<br>
Col_Winebottle<br>
Col_Yellow<br>
</code>
</td>
</tr>
<tr valign="top">
<td>
<code>
Col_Yellow_01<br>
Col_Yellow_02<br>
Col_Yellow_03<br>
Col_Yellow_04<br>
</code>
</td>
<td>
</td>
<td>
</td>
</tr>
</table>
</div>
<a name="r3_4_9_1_8_3"></a>
<div class="content-level-h6" contains="Glass finishes" id="r3_4_9_1_8_3">
<h6>3.4.9.1.8.3 Glass finishes</h6>
<code>F_Glass5, ..., F_Glass10</code>
</div>
<a name="r3_4_9_1_8_4"></a>
<div class="content-level-h6" contains="Glass interiors" id="r3_4_9_1_8_4">
<h6>3.4.9.1.8.4 Glass interiors</h6>
<dl>
<dt><code>I_Glass1, ..., I_Glass4</code></dt>
<dd><code>I_Glass_Fade_Sqr1</code> (identical to <code>I_Glass1</code>)</dd>
<dd><code>I_Glass_Fade_Exp1</code> (identical to <code>I_Glass2</code>)</dd>
<dd><code>I_Glass_Fade_Exp2</code> (identical to <code>I_Glass3</code>)</dd>
<dd><code>I_Glass_Fade_Exp3</code> (identical to <code>I_Glass4</code>)</dd>
<dd>Glass interiors with various fade_power settings.</dd>
<dt><code>I_Glass_Dispersion1, I_Glass_Dispersion2</code></dt>
<dd>Glass interiors with dispersion. <code>I_Glass_Dispersion1</code> has
an approximately natural glass dispersion. <code>I_Glass_Dispersion2</code> is exaggerated.</dd>
<dt><code>I_Glass_Caustics1, I_Glass_Caustics2</code></dt>
<dd>Glass interiors with caustics. </dd>
</dl>
</div>
<a name="r3_4_9_1_8_5"></a>
<div class="content-level-h6" contains="Glass interior macros" id="r3_4_9_1_8_5">
<h6>3.4.9.1.8.5 Glass interior macros</h6>
<p><code>I_Glass_Exp(Distance)</code> and <code>I_Glass_Sqr(Distance)</code>: These macros return an interior with either exponential or fade_power 2 falloff, and a fade_distance of Distance.</p></div>
<a name="r3_4_9_1_9"></a>
<div class="content-level-h5" contains="Golds.inc" id="r3_4_9_1_9">
<h5>3.4.9.1.9 Golds.inc</h5>
<p>This file has its own versions of <code>F_MetalA</code> through <code>F_MetalB</code>. The gold textures themselves are <code>T_Gold_1A</code> through <code>T_Gold_5E</code>.</p></div>
<a name="r3_4_9_1_10"></a>
<div class="content-level-h5" contains="Logo.inc" id="r3_4_9_1_10">
<h5>3.4.9.1.10 Logo.inc</h5>
<p>The official POV-Ray logo designed by Chris Colefax, in two versions</p>
<dl>
<dt><code>Povray_Logo</code></dt>
<dd> The POV-Ray logo object</dd>
<dt><code>Povray_Logo_Prism</code></dt>
<dd> The POV-Ray logo as a prism</dd>
<dt><code>Povray_Logo_Bevel</code></dt>
<dd>The POV-Ray logo as a beveled prism</dd>
</dl></div>
<a name="r3_4_9_1_11"></a>
<div class="content-level-h5" contains="Makegrass.inc" id="r3_4_9_1_11">
<h5>3.4.9.1.11 Makegrass.inc</h5>
<p>makegrass.inc - grass and prairie building macros.</p>
<dl>
<dt><code>MakeBlade()</code></dt>
<dd>creates an individual blade of grass as mesh.</dd>
<dt><code>MakeGrassPatch()</code></dt>
<dd>creates a patch of grass (mesh)<br>
optional with saving the mesh in a text file.</dd>
<dt><code>MakePrairie()</code></dt>
<dd>creates a prairie of grass patches.</dd>
</dl></div>
<a name="r3_4_9_1_12"></a>
<div class="content-level-h5" contains="Math.inc" id="r3_4_9_1_12">
<h5>3.4.9.1.12 Math.inc</h5>
<p>This file contains many general math functions and macros.</p>
</div>
<a name="r3_4_9_1_12_1"></a>
<div class="content-level-h6" contains="Float functions and macros" id="r3_4_9_1_12_1">
<h6>3.4.9.1.12.1 Float functions and macros</h6>
<p><code>even(N)</code>: A function to test whether N is even, returns 1 when true, 0 when false.</p>
<p>Parameters:</p>
<ul>
<li><code>N</code> = Input value</li>
</ul>
<p><code>odd(N)</code>: A function to test whether N is odd, returns 1 when true, 0 when false.</p>
<p>Parameters:</p>
<ul>
<li><code>N</code> = Input value</li>
</ul>
<p><code>Interpolate(GC, GS, GE, TS, TE, Method)</code>: Interpolation macro, interpolates between the float values <code>TS</code> and <code>TE</code>. The method of interpolation is cosine, linear or exponential. The position where to evaluate the interpolation is determined by the position of <code>GC</code> in the range <code>GS</code> - <code>GE</code>. See the example below.</p>
<p>Parameters:</p>
<ul>
<li><code>GC</code> = global current, float value within the range GS - GE</li>
<li><code>GS</code> = global start</li>
<li><code>GE</code> = global end</li>
<li><code>TS</code> = target start</li>
<li><code>TE</code> = target end</li>
<li><code>Method</code> = interpolation method, float value:
<ul>
<li><code>Method</code> < 0 : exponential, using the value of Method as exponent.</li>
<li><code>Method</code> = 0 : cosine interpolation.</li>
<li><code>Method</code> > 0 : exponential, using the value of Method as exponent.
<ul>
<li><code>Method</code> = 1 : linear interpolation,</li>
</ul></li>
</ul></li>
</ul>
<p>
Example:
</p>
<pre>
#declare A = Interpolate(0.5, 0, 1, 0, 10, 1);
#debug str(A,0,2)
// result A = 5.00
#declare A = Interpolate(0.0,-2, 2, 0, 10, 1);
#debug str(A,0,2)
// result A = 5.00
#declare A = Interpolate(0.5, 0, 1, 0, 10, 2);
#debug str(A,0,2)
// result A = 2.50
</pre>
<p><code>Mean(A)</code>: A macro to compute the average of an array of values.</p>
<p>Parameters:</p>
<ul>
<li><code>A</code> = An array of float or vector values.</li>
</ul>
<p><code>Std_Dev(A, M)</code>: A macro to compute the standard deviation.</p>
<p>Parameters:</p>
<ul>
<li><code>A</code> = An array of float values.</li>
<li><code>M</code> = Mean of the floats in the array.</li>
</ul>
<p><code>GetStats(A)</code>: This macro declares a global array named <code>StatisticsArray</code> containing: N, Mean, Min, Max, and Standard Deviation</p>
<p>Parameters:</p>
<ul>
<li><code>A</code> = An array of float values.</li>
</ul>
<p><code>Histogram(ValArr, Intervals)</code>: This macro declares a global, 2D array named <code>HistogramArray</code>. The first value in the array is the center of the interval/bin, the second the number of values in that interval.</p>
<p>Parameters:</p>
<ul>
<li><code>ValArr</code> = An array with values.</li>
<li><code>Intervals</code> = The desired number of intervals/bins.</li>
</ul>
<p><code>sind(v), cosd(v), tand(v), asind(v), acosd(v), atand(v), atan2d(a, b)</code>: These functions are versions of the
trigonometric functions using degrees, instead of radians, as the angle unit.</p>
<p>Parameters:</p>
<ul>
<li>The same as for the analogous built-in trig function.</li>
</ul>
<p><code>max3(a, b, c)</code>: A function to find the largest of three numbers.</p>
<p>Parameters:</p>
<ul>
<li><code>a, b, c</code> = Input values.</li>
</ul>
<p><code>min3(a, b, c)</code>: A function to find the smallest of three numbers.</p>
<p>Parameters:</p>
<ul>
<li><code>a, b, c</code> = Input values.</li>
</ul>
<p><code>f_sqr(v)</code>: A function to square a number.</p>
<p>Parameters:</p>
<ul>
<li><code>v</code> = Input value.</li>
</ul>
<p><code>sgn(v)</code>: A function to show the sign of the number. Returns -1 or 1 depending on the sign of v.</p>
<p>Parameters:</p>
<ul>
<li><code>v</code> = Input value.</li>
</ul>
<p><code>clip(V, Min, Max)</code>: A function that limits a value to a specific range, if it goes outside that range it is <em>clipped</em>. Input values larger than <code>Max</code> will return <code>Max</code>, those less than <code>Min</code> will return <code>Min</code>.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input value.</li>
<li><code>Min</code> = Minimum of output range.</li>
<li><code>Max</code> = Maximum of output range.</li>
</ul>
<p><code>clamp(V, Min, Max)</code>: A function that limits a value to a specific range, if it goes outside that range it is <em>clamped</em> to this range, wrapping around. As the input increases or decreases outside the given range, the output will
repeatedly sweep through that range, making a <em>sawtooth</em> waveform.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input value.</li>
<li><code>Min</code> = Minimum of output range.</li>
<li><code>Max</code> = Maximum of output range.</li>
</ul>
<p><code>adj_range(V, Min, Max)</code>: A function that adjusts input values in the range [0, 1] to a given range. An input value of 0 will return <code>Min</code>, 1 will return <code>Max</code>, and values outside the [0, 1] range will be linearly extrapolated (the graph will continue in a straight line).</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input value.</li>
<li><code>Min</code> = Minimum of output range.</li>
<li><code>Max</code> = Maximum of output range.</li>
</ul>
<p><code>adj_range2(V, InMin, InMax, OutMin, OutMax)</code>: Like <code>f_range()</code>, but adjusts input values in the range <code>[InMin, InMax]</code> to the range <code>[OutMin, OutMax]</code>.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input value.</li>
<li><code>InMin</code> = Minimum of input range.</li>
<li><code>InMax</code> = Maximum of input range.</li>
<li><code>OutMin</code> = Minimum of output range.</li>
<li><code>OutMax</code> = Maximum of output range.</li>
</ul>
</div>
<a name="r3_4_9_1_12_2"></a>
<div class="content-level-h6" contains="Vector functions and macros" id="r3_4_9_1_12_2">
<h6>3.4.9.1.12.2 Vector functions and macros</h6>
<p>These are all macros in the current version because functions can not take vector parameters, but this may change in the future.</p>
<p><code>VSqr(V)</code>: Square each individual component of a vector, equivalent to <code>V*V</code>.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Vector to be squared.</li>
</ul>
<p><code>VPow(V, P), VPow5D(V, P)</code>: Raise each individual component of a vector to a given power.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
<li><code>P</code> = Power.</li>
</ul>
<p><code>VEq(V1, V2)</code>: Tests for equal vectors, returns true if all three components of <code>V1</code>equal the respective components of <code>V2</code>.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, V2</code> = The vectors to be compared.</li>
</ul>
<p><code>VEq5D(V1, V2)</code>: A 5D version of <code>VEq()</code>. Tests for equal vectors, returns true if all 5 components of <code>V1 </code>equal the respective components of <code>V2</code>.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, V2</code> = The vectors to be compared.</li>
</ul>
<p><code>VZero(V)</code>: Tests for a < 0, 0, 0> vector.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
</ul>
<p><code>VZero5D(V)</code>: Tests for a < 0, 0, 0, 0, 0> vector.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
</ul>
<p><code>VLength5D(V)</code>: Computes the length of a 5D vector.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
</ul>
<p><code>VNormalize5D(V)</code>: Normalizes a 5D vector.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
</ul>
<p><code>VDot5D(V1, V2)</code>: Computes the dot product of two 5D vectors. See vdot() for more information on dot products.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
</ul>
<p><code>VCos_Angle(V1, V2)</code>: Compute the cosine of the angle between two vectors.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, V2</code> = Input vectors.</li>
</ul>
<p><code>VAngle(V1, V2), VAngleD(V1, V2)</code>: Compute the angle between two vectors. <code>VAngle()</code> returns the angle in radians, <code>VAngleD()</code> in degrees.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, V2</code> = Input vectors.</li>
</ul>
<p><code>VRotation(V1, V2, Axis)</code> and <code>VRotationD(V1, V2, Axis)</code>: Compute the rotation angle from V1 to V2 around Axis. Axis should be perpendicular to both V1 and V2. The output will be in the range between -pi and pi radians or between -180 degrees and 180 degrees if you are using the degree version. However, if Axis is set to <0,0,0> the output will always be positive or zero, the same result you will get with the VAngle() macros.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, V2</code> = Input vectors.</li>
</ul>
<p><code>VDist(V1, V2)</code>: Compute the distance between two points.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, V2</code> = Input vectors.</li>
</ul>
<p><code>VPerp_To_Vector(V)</code>: Find a vector perpendicular to the given vector.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
</ul>
<p><code>VPerp_To_Plane(V1, V2)</code>: Find a vector perpendicular to both given vectors. In other words, perpendicular to the plane defined by the two input vectors.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, V2</code> = Input vectors.</li>
</ul>
<p><code>VPerp_Adjust(V1, Axis)</code>: Find a vector perpendicular to Axis and in the plane of V1 and Axis. In other words, the new vector is a version of V1 adjusted to be perpendicular to Axis.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, Axis</code> = Input vectors.</li>
</ul>
<p><code>VProject_Plane(V1, Axis)</code>: Project vector V1 onto the plane defined by Axis.</p>
<p>Parameters:</p>
<ul>
<li><code>V1</code> = Input vectors.</li>
<li><code>Axis</code> = Normal of the plane.</li>
</ul>
<p><code>VProject_Axis(V1, Axis)</code>: Project vector V1 onto the axis defined by Axis.</p>
<p>Parameters:</p>
<ul>
<li><code>V1, Axis</code> = Input vectors.</li>
</ul>
<p><code>VMin(V), VMax(V)</code>: Find the smallest or largest component of a vector.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Input vector.</li>
</ul>
<p><code>VWith_Len(V, Len)</code>: Create a vector parallel to a given vector but with a given length.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = Direction vector.</li>
<li><code>Len</code> = Length of desired vector.</li>
</ul>
</div>
<a name="r3_4_9_1_12_3"></a>
<div class="content-level-h6" contains="Vector Analysis" id="r3_4_9_1_12_3">
<h6>3.4.9.1.12.3 Vector Analysis</h6>
<p><code>SetGradientAccuracy(Value)</code>: All the macros below make use of a constant named <em>__Gradient_Fn_Accuracy_</em> for numerical approximation of the derivatives. This constant can be changed with the macro, the default value is 0.001.</p>
<p><code>fn_Gradient(Fn)</code>: A macro calculating the gradient of a function as a function.</p>
<p>Parameters:</p>
<ul>
<li><code>Fn</code> = function to calculate the gradient from.</li>
</ul>
<p>
Output: the length of the gradient as a function.
</p>
<p><code>fn_Gradient_Directional(Fn, Dir)</code>: A macro calculating the gradient of a function in one direction as a function.</p>
<p>Parameters:</p>
<ul>
<li><code>Fn</code> = function to calculate the gradient from.</li>
<li><code>Dir</code> = direction to calculate the gradient.</li>
</ul>
<p>
Output: the gradient in that direction as a function.
</p>
<p><code>fn_Divergence(Fnx, Fny, Fnz)</code>: A macro calculating the divergence of a (vector) function as a function.</p>
<p>Parameters:</p>
<ul>
<li><code>Fnx, Fny, Fnz</code>= x, y and z components of a vector function.</li>
</ul>
<p>
Output: the divergence as a function.
</p>
<p><code>vGradient(Fn, p0)</code>: A macro calculating the gradient of a function as a vector expression.</p>
<p>Parameters:</p>
<ul>
<li><code>Fn</code> = function to calculate the gradient from.</li>
<li><code>p0</code> = point where to calculate the gradient.</li>
</ul>
<p>
Output: the gradient as a vector expression.
</p>
<p><code>vCurl(Fnx, Fny, Fnz, p0)</code>: A macro calculating the curl of a (vector) function as a vector expression.</p>
<p>Parameters:</p>
<ul>
<li><code>Fnx, Fny, Fnz</code> = x, y and z components of a vector function.</li>
<li><code>p0</code> = point where to calculate the gradient.</li>
</ul>
<p>
Output: the curl as a vector expression
</p>
<p><code>Divergence(Fnx, Fny, Fnz, p0)</code>: A macro calculating the divergence of a (vector) function as a float expression.</p>
<p>Parameters:</p>
<ul>
<li><code>Fnx, Fny, Fnz</code> = x, y and z components of a vector function.</li>
<li><code>p0</code> = point where to calculate the gradient.</li>
</ul>
<p>
Output: the divergence as a float expression.
</p>
<p><code>Gradient_Length(Fn, p0)</code>: A macro calculating the length of the gradient of a function as a float expression.</p>
<p>Parameters:</p>
<ul>
<li><code>Fn</code> = function to calculate the gradient from.</li>
<li><code>p0</code> = point where to calculate the gradient.</li>
</ul>
<p>
Output: the length of the gradient as a float expression.
</p>
<p><code>Gradient_Directional(Fn, p0, Dir)</code>: A macro calculating the gradient of a function in one direction as a float expression.</p>
<p>Parameters:</p>
<ul>
<li><code>Fn</code> = function to calculate the gradient from.
<li><code>p0</code> = point where to calculate the gradient.
<li><code>Dir</code> = direction to calculate the gradient.
</ul>
<p>
Output: the gradient in that direction as a float expression
</p></div>
<a name="r3_4_9_1_13"></a>
<div class="content-level-h5" contains="Meshmaker.inc" id="r3_4_9_1_13">
<h5>3.4.9.1.13 Meshmaker.inc</h5>
<p>meshmaker.inc - various mesh2 objects by splines.</p>
<dl>
<dt><code>MSM(SplineArray, SplRes, Interp_type, InterpRes, FileName)</code></dt>
<dd>Generates a mesh2 from an array of splines and optionally writes the mesh2 object as a file of the given <code>FileName</code>.<br>
The uv_coordinates come from the square <0,0> - <1,1>.<br>
The spline is evaluated from t=0 to t=1. <br>
For the normal calculation, it is required that all splines (also linear_spline) have one extra
point before t=0 and after t=1.</dt>
<dt><code>BuildWriteMesh2(VecArr, NormArr, UVArr, U, V, FileName)</code></dt>
<dd>Generates and optionally writes a mesh2 object based on 3 input arrays,
the number of quads in U and V direction and a filename.<br>
<code>VecArr</code> : The array that contains the vertices of the triangles in the mesh.<br>
<code>NormArr</code> : The array with the normal vectors that go with the vertices.<br>
<code>UVArr</code> : The array containing the uv_vectors.<br>
<code>U</code> : The amount of subdivisions of the surface in the u-direction.<br>
<code>V</code> : The amount of subdivisions in the v-direction.<br>
Based on the U and V values the face_indices of the triangles in the mesh are calculated.<br>
<code>FileName</code> : The name of the file to which the mesh will be written.
If is an empty string (""), no file will be written.<br>
If the file extension is 'obj' a Wavefront objectfile will be written.<br>
If the extension is 'pcm' a compressed mesh file is written.<br>
If a file name is given, the macro will first check if it already exists.<br>
If that is so, it will try to parse the existing file unless it's a '*.obj', '*.pcm' or '*.arr' file as POV-Ray
can not read them directly. In this case a new mesh will be generated,
but the existing files will _not_ be over-written.</dd>
<dt><code>BuildSpline(Arr, SplType)</code></dt>
<dd>A helper macro for MSM()<br>
Generates from a array <code>Arr</code> a spline of the given spline type <code>SplType</code>.</dd>
<dt><code>CheckFileName(FileName)</code></dt>
<dd>A helper macro for MSM()<br>
If Return has a value of 0 the mesh will not be build,
but it will be parsed from file.</dd>
<dt><code>LInterpolate(Val, Min, Max)</code></dt>
<dd>A helper macro for MSM()<br>
Linear interpolation of a vector or float between <code>Min</code> and <code>Max</code>.<br>
<code>Min</code> : minimal float value or vector.<br>
<code>Max</code> : Maximal float value or vector.<br>
<code>Val</code> : A float in the range 0 - 1.</dd>
<dt><code>RangeMM() = function(Val,Rmin,Rmax,Min,Max)</code></dt>
<dd>A helper function for MSM()<br>
Adjusts input values in the range [<code>RMin, RMax</code>] to fit in the range [Min, Max].
<code>Val</code>: A float value in the range [Rmin, Rmax].</dd>
<dt><code>Parametric(__F1__, __F2__, __F3__, UVmin, UVmax, Iter_U, Iter_V, FileName)</code></dt>
<dd>Generates a mesh2 object from the parametric uv functions <code>__F1__, __F2__, __F3__</code>
in the ranges between <code>UVmin</code> and <code>UVmax</code> with the iteration steps
<code>Iter_U</code> and <code>Iter_V</code> and optionally saves the mesh2 object as a file with the name <code>FileName</code>.</dd>
<dt><code>Paramcalc(UVmin, UVmax, Iter_U, Iter_V, FileName)</code></dt>
<dd>The kernel of the macro Parametric(). See <code>Parametric()</code>.</dd>
<dt><code> Prism1(Spl, ResSpl, PSpl, PRes, FileName)</code></dt>
<dd>Generates a mesh2 object by extruding the spline <code>Spl</code> along the y-axis with the resolution spline <code>ResSpl</code>.
In every step the spline is scaled by the 'relative' distance from the
y-axis of the second spline (PSpl).<br>
The uv_coordinates come from the square <0,0> - <1,1>.<br>
<code>Spl</code> : The spline to be extruded.<br>
The spline is evaluated from t=0 to t=1. For the normal calculation,<br>
it is required that all splines (also linear_spline) have one extra<br>
point before t=0 and after t=1.
<code>ResSpl</code> : The amount of triangles to be used along the spline.
<code>PSpl</code> : The spline that determines by what amount the extrusion<br>
is scaled in each step. The scaling is based on the relative distance from the y-axis.<br>
That is, at t=0 the scale is always 1, so that the start of the shape is<br>
identical to the spline <code>Spl</code>.<br>
PSpl also sets the height of the resulting shape (its y-value at t=1).<br>
The spline is evaluated from t=0 to t=1. For the normal calculation,<br>
it is required that all splines (also linear_spline) have one extra <br>
point before t=0 and after t=1. <br>
<code>FileName</code> : The name of the file to which the mesh will be written.<br>
If is an empty string (""), no file will be written. If a file name is given, the macro <br>
will first check if it already exists. If that is so, it will expect a <br>
mesh2 with the name "Surface" and try to parse the existing file.<br>
<dt><code>Lathe(Spl, ResSpl, Rot, ResRot, FileName)</code></dt>
<dd>This macro generates a mesh2 object by rotating a two-dimensional curve about the y-axis.<br>
The uv_coordinates come from the square <0,0> - <1,1>.<br>
<code>Spl</code> : The spline to be rotated.
The spline is evaluated from t=0 to t=1. For the normal calculation,
it is required that all splines (also linear_spline) have one extra
point before t=0 and after t=1.
<code>ResSpl</code> : The amount of triangles to be used along the spline.
<code>Rot</code> : The angle the spline has to be rotated.<br>
<code>ResRot</code> : The amount of triangles to be used in the circumference.<br>
<code>FileName</code> : The name of the file to which the mesh will be written.<br>
If is an empty string (""), no file will be written.<br>
If the file extension is 'obj' a Wavefront objectfile will be written.<br>
If the extension is 'pcm' a compressed mesh file is written.<br>
If a file name is given, the macro will first check if it already exists.<br>
If that is so, it will try to parse the existing file unless it's a '*.obj', <br>
'*.pcm' or '*.arr' file as POV-Ray can not read them directly. In this case a new <br>
mesh will be generated, but the existing files will _not_ be over-written. </dd>
<dt><code>Coons(Spl1, Spl2, Spl3, Spl4, Iter_U, Iter_V, FileName)</code></dt>
<dd>Generates a mesh2 'coons surface' defined by four splines, all attached head to tail to the previous / next one.<br>
The uv_coordinates come from the square <0,0> - <1,1>.<br>
<code>Spl1 - 4</code> : The four spline that define the surface.<br>
The splines are evaluated from t=0 to t=1. <br>
<code>Iter_U</code> : The resolution for the splines 1 and 3.<br>
<code>Iter_V</code> : The resolution for the splines 2 and 4.<br>
<code>FileName</code> : The name of the file to which the mesh will be written.<br>
If is an empty string (""), no file will be written.<br>
If the file extension is 'obj' a Wavefront objectfile will be written.<br>
If the extension is 'pcm' a compressed mesh file is written.<br>
If a file name is given, the macro will first check if it already exists.<br>
If that is so, it will try to parse the existing file unless it's a '*.obj',<br>
'*.pcm' or '*.arr' file as POV-Ray can not read them directly. In this case a new<br>
mesh will be generated, but the existing files will _not_ be over-written.</dd>
<dt><code>TwoVarSurf(__Fuv, Urange, Vrange, Iter_U, Iter_V, FileName)</code></dt>
<dd>Generates a mesh2 object by extruding an uv-function.
<code>Urange</code> : The range in x direction.<br>
<code>Vrange</code> : The range in y direction.<br>
<code>Iter_U</code> : The resolution in x direction.<br>
<code>Iter_V</code> : The resolution in y direction.<br>
<code>FileName</code> : The name of the file to which the mesh will be written.<br>
If is an empty string (""), no file will be written. If a file name is given, the macro <br>
will first check if it already exists. If that is so, it will expect a <br>
mesh2 with the name "Surface" and try to parse the existing file.</dd>
<dt><code>SweepSpline1(Track,Shape,Waist,U,V,Filename)</code></dt>
<dd>Generates a mesh2 object by extruding a spline <code>Shape</code> along <code>Track</code>
and optionally writes it as a file with method 1.<br>
<code>FileName</code> : The name of the file to which the mesh will be written.
If is an empty string (""), no file will be written. If a file name is given, the macro <br>
will first check if it already exists. If that is so, it will expect a <br>
mesh2 with the name "Surface" and try to parse the existing file.</dd>
<dt><code>SweepSpline2(Track,Shape,Waist,U,V,Filename)</code></dt>
<dd>Generates a mesh2 object by extruding a spline <code>Shape</code> along <code>Track</code>
and optionally writes it as a file with method 2.<br>
<code>FileName</code> : The name of the file to which the mesh will be written.
If is an empty string (""), no file will be written. If a file name is given, the macro <br>
will first check if it already exists. If that is so, it will expect a <br>
mesh2 with the name "Surface" and try to parse the existing file.</dd>
<br>
</dl></div>
<a name="r3_4_9_1_14"></a>
<div class="content-level-h5" contains="Metals.inc" id="r3_4_9_1_14">
<h5>3.4.9.1.14 Metals.inc</h5>
<p>These files define several metal textures. The file metals.inc contains copper, silver, chrome, and brass textures, and golds.inc contains the gold textures. Rendering the demo files will come in useful in using these textures.</p>
<p><strong>Pigments:</strong></p>
<dl>
<dt><code>P_Brass1</code></dt>
<dd>Dark brown bronze.</dd>
<dt><code>P_Brass2</code></dt>
<dd>Somewhat lighter brown than Brass4. Old penny, in soft finishes.</dd>
<dt><code>P_Brass3</code></dt>
<dd>Used by Steve Anger's Polished_Brass. Slightly coppery.</dd>
<dt><code>P_Brass4</code></dt>
<dd>A little yellower than Brass1.</dd>
<dt><code>P_Brass5</code></dt>
<dd>Very light bronze, ranges from med tan to almost white.</dd>
</dl>
<dl>
<dt><code>P_Copper1</code></dt>
<dd>Bronze-like. Best in finish #C.</dd>
<dt><code>P_Copper2</code></dt>
<dd>Slightly brownish copper/bronze. Best in finishes #B-#D.</dd>
<dt><code>P_Copper3</code></dt>
<dd>Reddish-brown copper. Best in finishes #C-#E.</dd>
<dt><code>P_Copper4</code></dt>
<dd>Pink copper, like new tubing. Best in finishes #C-#E.</dd>
<dt><code>P_Copper5</code></dt>
<dd>Bronze in softer finishes, gold in harder finishes.</dd>
</dl>
<dl>
<dt><code>P_Chrome1</code></dt>
<dd>20% Gray. Used in Steve Anger's Polished_Chrome.</dd>
<dt><code>P_Chrome2</code></dt>
<dd>Slightly blueish 60% gray. Good steel w/finish #A.</dd>
<dt><code>P_Chrome3</code></dt>
<dd>50% neutral gray.</dd>
<dt><code>P_Chrome4</code></dt>
<dd>75% neutral gray.</dd>
<dt><code>P_Chrome5</code></dt>
<dd>95% neutral gray.</dd>
</dl>
<dl>
<dt><code>P_Silver1</code></dt>
<dd>Yellowish silverplate. Somewhat tarnished looking.</dd>
<dt><code>P_Silver2</code></dt>
<dd>Not quite as yellowish as Silver1 but more so than Silver3.</dd>
<dt><code>P_Silver3</code></dt>
<dd>Reasonably neutral silver.</dd>
<dt><code>P_Silver4</code></dt>
<dt><code>P_Silver5</code></dt>
</dl>
<p><strong>Finishes:</strong></p>
<dl>
<dt><code>F_MetalA</code></dt>
<dd>Very soft and dull.</dd>
<dt><code>F_MetalB</code></dt>
<dd>Fairly soft and dull.</dd>
<dt><code>F_MetalC</code></dt>
<dd>Medium reflectivity. Holds color well.</dd>
<dt><code>F_MetalD</code></dt>
<dd>Very hard and highly polished. High reflectivity.</dd>
<dt><code>F_MetalE</code></dt>
<dd>Very highly polished and reflective.</dd>
</dl>
<p><strong>Textures:</strong></p>
<dl>
<dt><code>T_Brass_1A to T_Brass_5E</code></dt>
<dt><code>T_Copper_1A to T_Copper_5E</code></dt>
<dt><code>T_Chrome_1A to T_Chrome_5E</code></dt>
<dt><code>T_Silver_1A to T_Silver_5E</code></dt>
</dl></div>
<a name="r3_4_9_1_15"></a>
<div class="content-level-h5" contains="Rad_def.inc" id="r3_4_9_1_15">
<h5>3.4.9.1.15 Rad_def.inc</h5>
<p>This file defines a macro that sets some common radiosity settings. These settings are extremely general and are intended for ease of use, and do not necessarily give the best results.</p>
<p>Usage:</p>
<pre>
#include "rad_def.inc"
global_settings {
...
radiosity {
Rad_Settings(Setting, Normal, Media)
}
}
</pre>
<p>Parameters:</p>
<ul>
<li>Setting = Quality setting. Use one of the predefined constants:</li>
<ul>
<li>Radiosity_Default</li>
<li>Radiosity_Debug</li>
<li>Radiosity_Fast</li>
<li>Radiosity_Normal</li>
<li>Radiosity_2Bounce</li>
<li>Radiosity_Final</li>
<li>Radiosity_OutdoorLQ</li>
<li>Radiosity_OutdoorHQ</li>
<li>Radiosity_OutdoorLight</li>
<li>Radiosity_IndoorLQ</li>
<li>Radiosity_IndoorHQ</li>
</ul>
<li>Normal = Boolean value, whether or not to use surface normal modifiers for radiosity samples.</li>
<li>Media = Boolean value, whether or not to calculate media for radiosity samples.</li>
</ul></div>
<a name="r3_4_9_1_16"></a>
<div class="content-level-h5" contains="Rand.inc" id="r3_4_9_1_16">
<h5>3.4.9.1.16 Rand.inc</h5>
<p>A collection of macros for generating random numbers, as well as 4 predefined random number streams: <code>RdmA, RdmB, RdmC,</code> and <code>RdmD</code>. There are macros for creating random numbers in a flat distribution (all numbers equally likely) in various ranges, and a variety of other distributions.</p>
</div>
<a name="r3_4_9_1_16_1"></a>
<div class="content-level-h6" contains="Flat Distributions" id="r3_4_9_1_16_1">
<h6>3.4.9.1.16.1 Flat Distributions</h6>
<p><code>SRand(Stream)</code>: <em>Signed rand()</em>, returns random numbers in the range [-1, 1].</p>
<p>Parameters:</p>
<ul>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>RRand(Min, Max, Stream)</code>: Returns random numbers in the range [Min, Max].</p>
<p>Parameters:</p>
<ul>
<li><code>Min</code> = The lower end of the output range.</li>
<li><code>Max</code> = The upper end of the output range.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>VRand(Stream)</code>: Returns random vectors in a box from < 0, 0, 0> to < 1, 1, 1></p>
<p>Parameters:</p>
<ul>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>VRand_In_Box(PtA, PtB, Stream)</code>: Like VRand(), this macro returns a random vector in a box, but this version lets you specify the two corners of the box.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA</code> = Lower-left-bottom corner of box.</li>
<li><code>PtB</code> = Upper-right-top corner of box.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>VRand_In_Sphere(Stream)</code>: Returns a random vector in a unit-radius sphere located at the origin.</p>
<p>Parameters:</p>
<ul>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>VRand_On_Sphere(Stream)</code>: Returns a random vector on the surface of a unit-radius sphere located at the origin.</p>
<p>Parameters:</p>
<ul>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>VRand_In_Obj(Object, Stream)</code>: This macro takes a solid object and returns a random point that is inside it. It does this by randomly sampling the bounding box of the object, and can be quite slow if the object occupies a small percentage of the volume of its bounding box (because it will take more attempts to find a point inside the object). This macro is best used on finite, solid objects (non-solid objects, such as meshes and bezier patches, do not have a defined <em>inside</em>, and will not work).</p>
<p>Parameters:</p>
<ul>
<li><code>Object</code> = The object the macro chooses the points from.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
</div>
<a name="r3_4_9_1_16_2"></a>
<div class="content-level-h6" contains="Other Distributions" id="r3_4_9_1_16_2">
<h6>3.4.9.1.16.2 Other Distributions</h6>
</div>
<a name="r3_4_9_1_16_3"></a>
<div class="content-level-h6" contains="Continuous Symmetric Distributions" id="r3_4_9_1_16_3">
<h6>3.4.9.1.16.3 Continuous Symmetric Distributions</h6>
<p><code>Rand_Cauchy(Mu, Sigma, Stream)</code>: Cauchy distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Mu</code> = Mean.</li>
<li><code>Sigma</code> = Standard deviation.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Student(N, Stream)</code>: Student's distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>N</code> = degrees of freedom.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Normal(Mu, Sigma, Stream)</code>: Normal distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Mu</code> = Mean.</li>
<li><code>Sigma</code> = Standard deviation.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Gauss(Mu, Sigma, Stream)</code>: Gaussian distribution. Like Rand_Normal(), but a bit faster.</p>
<p>Parameters:</p>
<ul>
<li><code>Mu</code> = Mean.</li>
<li><code>Sigma</code> = Standard deviation.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
</div>
<a name="r3_4_9_1_16_4"></a>
<div class="content-level-h6" contains="Continuous Skewed Distributions" id="r3_4_9_1_16_4">
<h6>3.4.9.1.16.4 Continuous Skewed Distributions</h6>
<p><code>Rand_Spline(Spline, Stream)</code>: This macro takes a spline describing the desired distribution. The T value of the spline is the output value, and the .y value its chance of occuring.</p>
<p>Parameters:</p>
<ul>
<li><code>Spline</code> = A spline determining the distribution.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Gamma(Alpha, Beta, Stream)</code>: Gamma distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Alpha</code> = Shape parameter > 0.</li>
<li><code>Beta</code> = Scale parameter > 0.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Beta(Alpha, Beta, Stream)</code>: Beta variate.</p>
<p>Parameters:</p>
<ul>
<li><code>Alpha</code> = Shape Gamma1.</li>
<li><code>Beta</code> = Scale Gamma2.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Chi_Square(N, Stream)</code>: Chi Square random variate.</p>
<p>Parameters:</p>
<ul>
<li><code>N</code> = Degrees of freedom (integer).</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_F_Dist(N, M, Stream)</code>: F-distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>N, M</code> = Degrees of freedom.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Tri(Min, Max, Mode, Stream)</code>: Triangular distribution </p>
<p>Parameters:</p>
<ul>
<li><code>Min, Max, Mode</code>: Min < Mode < Max.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Erlang(Mu, K, Stream)</code>: Erlang variate.</p>
<p>Parameters:</p>
<ul>
<li><code>Mu</code> = Mean >= 0.</li>
<li><code>K</code> = Number of exponential samples.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Exp(Lambda, Stream)</code>: Exponential distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Lambda</code> = rate = 1/mean.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Lognormal(Mu, Sigma, Stream)</code>: Lognormal distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Mu</code> = Mean.</li>
<li><code>Sigma</code> = Standard deviation.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Pareto(Alpha, Stream)</code>: Pareto distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Alpha</code> = ?</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Weibull(Alpha, Beta, Stream)</code>: Weibull distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Alpha</code> = ?</li>
<li><code>Beta</code> = ?</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
</div>
<a name="r3_4_9_1_16_5"></a>
<div class="content-level-h6" contains="Discrete Distributions " id="r3_4_9_1_16_5">
<h6>3.4.9.1.16.5 Discrete Distributions </h6>
<p><code>Rand_Bernoulli(P, Stream)</code> and <code>Prob(P, Stream)</code>: Bernoulli distribution. Output is true with probability equal to the value of P and false with a probability of 1 - P.</p>
<p>Parameters:</p>
<ul>
<li><code>P</code> = probability range (0-1).</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Binomial(N, P, Stream)</code>: Binomial distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>N</code> = Number of trials.</li>
<li><code>P</code> = Probability (0-1)</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Geo(P, Stream)</code>: Geometric distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>P</code> = Probability (0-1).</li>
<li><code>Stream</code> = Random number stream.</li>
</ul>
<p><code>Rand_Poisson(Mu, Stream)</code>: Poisson distribution.</p>
<p>Parameters:</p>
<ul>
<li><code>Mu</code> = Mean.</li>
<li><code>Stream</code> = Random number stream.</li>
</ul></div>
<a name="r3_4_9_1_17"></a>
<div class="content-level-h5" contains="Screen.inc" id="r3_4_9_1_17">
<h5>3.4.9.1.17 Screen.inc</h5>
<p>Screen.inc will enable you to place objects and textures right in front of the camera. When you move the camera, the objects placed with screen.inc will follow the movement and stay in the same position on the screen. One use of this is to place your signature or a logo in the corner of the image.</p>
<p>You can only use screen.inc with the perspective camera. Screen.inc will automatically create a default camera definition for you when it is included. All aspects of the camera can than be changed, by invoking the appropriate 'Set_Camera_...' macros in your scene. After calling these setup macros you can use the macros Screen_Object and Screen_Plane.</p>
<p class="Note"><strong>Note:</strong> Even though objects aligned using screen.inc follow the camera, they are still part of the scene. That means that they will be affected by perspective, lighting, the surroundings etc.</p>
<p>For an example of use, see the screen.pov demo file.</p>
<p><code>Set_Camera_Location(Loc)</code>: Changes the position of the default camera to a new location as specified by the <code>Loc</code> vector.</p>
<p><code>Set_Camera_Look_At(LookAt)</code>: Changes the position the default camera looks at to a new location as specified by the <code>LookAt</code> vector.</p>
<p><code>Set_Camera_Aspect_Ratio(Aspect)</code>: Changes the default aspect ratio, <code>Aspect</code> is a float value, usually width divided by the height of the image.</p>
<p><code>Set_Camera_Aspect(Width,Height)</code>: Changes the default aspect ratio of the camera.</p>
<p><code>Set_Camera_Sky(Sky)</code>: Sets a new Sky-vector for the camera.</p>
<p><code>Set_Camera_Zoom(Zoom)</code>: The amount to zoom in or out, <code>Zoom</code> is a float.</p>
<p><code>Set_Camera_Angle(Angle)</code>: Sets a new camera angle.</p>
<p><code>Set_Camera(Location, LookAt, Angle)</code>: Set <code>location</code>, <code>look_at</code> and <code>angle</code> in one go.</p>
<p><code>Reset_Camera()</code>: Resets the camera to its default values.</p>
<p><code>Screen_Object (Object, Position, Spacing, Confine, Scaling)</code>: Puts an object in front of the camera.</p>
<p>Parameters:</p>
<ul>
<li><code>Object</code> = The object to place in front of the screen.</li>
<li><code>Position</code> = UV coordinates for the object. <0,0> is lower left corner of the screen and <1,1> is upper right corner.</li>
<li><code>Spacing</code> = Float describing minimum distance from object to the borders. UV vector can be used to get different horizontal and vertical spacing.</li>
<li><code>Confine</code> = Set to true to confine objects to visible screen area. Set to false to allow objects to be outside visible screen area.</li>
<li><code>Scaling</code> = If the object intersects or interacts with the scene, try to move it closer to the camera by decreasing Scaling.</li>
</ul>
<p><code>Screen_Plane (Texture, Scaling, BLCorner, TRCorner)</code>: Screen_Plane is a macro that will place a texture of your choice on a plane right in front of the camera.</p>
<p>Parameters:</p>
<ul>
<li><code>Texture </code> = The texture to be displayed on the camera plane. <0,0,0> is lower left corner and <1,1,0> is upper right corner.</li>
<li><code>Scaling </code> = If the plane intersects or interacts with the scene, try to move it closer to the camera by decreasing Scaling.</li>
<li><code>BLCorner </code> = The bottom left corner of the Screen_Plane.</li>
<li><code>TRCorner </code> = The top right corner of the Screen_Plane.</li>
</ul></div>
<a name="r3_4_9_1_18"></a>
<div class="content-level-h5" contains="Shapes.inc" id="r3_4_9_1_18">
<h5>3.4.9.1.18 Shapes.inc</h5>
<p>These files contain predefined shapes and shape-generation macros.</p>
<p><em>shapes.inc</em> includes <em>shapes_old.inc</em> and contains many macros for working
with objects, and for creating special objects, such as bevelled text, spherical height fields,
and rounded shapes.</p>
<p>Many of the objects in <em>shapes_old.inc</em> are not very useful in the newer versions of
POV-Ray, and are kept for backwards compatability with old scenes written for versions of POV-Ray
that lacked primitives like cones, disks, planes, etc.</p>
<p>The file <em>shapes2.inc</em> contains some more useful shapes, including regular polyhedrons,
and <em>shapesq.inc</em> contains several quartic and cubic shape definitions.</p>
<p>Some of the shapes in <em>shapesq.inc</em> would be much easier to generate, more flexible,
and possibly faster rendering as isosurfaces, but are still useful for two reasons: backwards
compatability, and the fact that isosurfaces are always finite.</p>
<p><code>Isect(Pt, Dir, Obj, OPt)</code> and <code>IsectN(Pt, Dir, Obj, OPt, ONorm)</code>: These macros are interfaces to the trace() function. Isect() only returns the intersection point, IsectN() returns the surface normal as well. These macros return the point and normal information through their parameters, and true or false depending on whether an intersection was found: If an intersection is found, they return true and set OPt to the intersection point, and ONorm to the normal. Otherwise they return false, and do not modify OPt or ONorm.</p>
<p>Parameters:</p>
<ul>
<li><code>Pt</code> = The origin (starting point) of the ray.</li>
<li><code>Dir</code> = The direction of the ray.</li>
<li><code>Obj</code> = The object to test for intersection with.</li>
<li><code>OPt</code> = A declared variable, the macro will set this to the intersection point.</li>
<li><code>ONorm</code> = A declared variable, the macro will set this to the surface normal at the intersection point.</li>
</ul>
<p><code>Extents(Obj, Min, Max)</code>: This macro is a shortcut for calling both min_extent() and max_extent() to get the corners of the bounding box of an object. It returns these values through the Min and Max parameters.</p>
<p>Parameters:</p>
<ul>
<li><code>Obj</code> = The object you are getting the extents of.</li>
<li><code>Min</code> = A declared variable, the macro will set this to the min_extent of the object.</li>
<li><code>Max</code> = A declared variable, the macro will set this to the max_extent of the object.</li>
</ul>
<p><code>Center_Object(Object, Axis)</code>: A shortcut for using the Center_Trans() macro with an object.</p>
<p>Parameters:</p>
<ul>
<li><code>Object</code> = The object to be centered.</li>
<li><code>Axis</code> = See Center_Trans() in the transforms.inc documentation.</li>
</ul>
<p><code>Align_Object(Object, Axis, Pt)</code>: A shortcut for using the <a href="r3_4.html#r3_4_9_1_29">Align_Trans()</a> macro with an object.</p>
<p>Parameters:</p>
<ul>
<li><code>Object</code> = The object to be aligned.</li>
<li><code>Axis</code> = See Align_Trans() in the transforms.inc documentation.</li>
<li><code>Point</code> = The point to which to align the bounding box of the object. </li>
</ul>
<p><code>Bevelled_Text(Font, String, Cuts, BevelAng, BevelDepth, Depth, Offset, UseMerge)</code>: This macro attempts to <em>bevel</em> the front edges of a text object. It accomplishes this by making an intersection of multiple copies of the text object, each sheared in a different direction. The results are no perfect, but may be entirely acceptable for some purposes. Warning: the object generated may render considerably more slowly than an ordinary text object.</p>
<p>Parameters:</p>
<ul>
<li><code>Font</code> = A string specifying the font to use.</li>
<li><code>String</code> = The text string the object is generated from.</li>
<li><code>Cuts</code> = The number of intersections to use in bevelling the text.
More cuts give smoother results, but take more memory and are slower rendering.</li>
<li><code>BevelAng</code> = The angle of the bevelled edge.</li>
<li><code>BevelDepth</code> = The thickness of the bevelled portion.</li>
<li><code>Depth</code> = The total thickness of the resulting text object.</li>
<li><code>Offset</code> = The offset parameter for the text object. The z value
of this vector will be ignored, because the front faces of all the letters need
to be coplanar for the bevelling to work.</li>
<li><code>UseMerge</code> = Switch between merge (1) and union (0).</li>
</ul>
<p><code>Text_Space(Font, String, Size, Spacing)</code>: Computes the width of a text string, including <em>white space</em>, it returns the advance widths of all n letters. Text_Space gives the space a text, or a glyph, occupies in regard to its surroundings.</p>
<p>Parameters:</p>
<ul>
<li><code>Font</code> = A string specifying the font to use.</li>
<li><code>String</code> = The text string the object is generated from.</li>
<li><code>Size</code> = A scaling value.</li>
<li><code>Spacing</code> = The amount of space to add between the characters.</li>
</ul>
<p><code>Text_Width(Font, String, Size, Spacing)</code>: Computes the width of a text string, it returns the advance widths of the first n-1 letters, plus the glyph width of the last letter. Text_Width gives the <em>physical</em> width of the text and if you use only one letter the <em>physical</em> width of one glyph.</p>
<p>Parameters:</p>
<ul>
<li><code>Font</code> = A string specifying the font to use.</li>
<li><code>String</code> = The text string the object is generated from.</li>
<li><code>Size</code> = A scaling value.</li>
<li><code>Spacing</code> = The amount of space to add between the characters.</li>
</ul>
<p><code>Align_Left, Align_Right, Align_Center</code>: These constants are used by the
<code>Circle_Text()</code> macro.
</p>
<p><code>Circle_Text(Font, String, Size, Spacing, Depth, Radius, Inverted, Justification, Angle)</code>: Creates a text object with the bottom (or top) of the character cells aligned with all or part of a circle. This macro should be used inside an <code>object{...}</code> block.</p>
<p>Parameters:</p>
<ul>
<li><code>Font</code> = A string specifying the font to use.</li>
<li><code>String</code> = The text string the object is generated from.</li>
<li><code>Size</code> = A scaling value.</li>
<li><code>Spacing</code> = The amount of space to add between the characters.</li>
<li><code>Depth</code> = The thickness of the text object.</li>
<li><code>Radius</code> = The radius of the circle the letters are aligned to.</li>
<li><code>Inverted</code> = Controls what part of the text faces <em>outside</em>.
If this parameter is nonzero, the tops of the letters will point toward the center
of the circle. Otherwise, the bottoms of the letters will do so.</li>
<li><code>Justification</code> = Align_Left, Align_Right, or Align_Center.</li>
<li><code>Angle</code> = The point on the circle from which rendering will begin. The +x
direction is 0 and the +y direction is 90 (i.e. the angle increases
anti-clockwise).</li>
</ul>
<p><code>Wedge(Angle)</code>: This macro creates an infinite wedge shape, an intersection of two planes. It is mainly useful in CSG, for example to obtain a specific arc of a torus. The edge of the wedge is positioned along the y axis, and one side is fixed to the zy plane, the other side rotates clockwise around the y axis.</p>
<p>Parameters:</p>
<ul>
<li><code>Angle</code> = The angle, in degrees, between the sides of the wedge shape.</li>
</ul>
<p><code>Spheroid(Center, Radius)</code>: This macro creates an unevenly scaled sphere. Radius is a vector where each component is the radius along that axis.</p>
<p>Parameters:</p>
<ul>
<li><code>Center</code> = Center of the spheroid.</li>
<li><code>Radius</code> = A vector specifying the radii of the spheroid.</li>
</ul>
<p><code>Supertorus(MajorRadius, MinorRadius, MajorControl, MinorControl, Accuracy, MaxGradient)</code>: This macro creates an isosurface of the torus equivalent of a superellipsoid. If you specify a MaxGradient of less than 1, evaluate will be used. You will have to adjust MaxGradient to fit the parameters you choose, a squarer supertorus will have a higher gradient. You may want to use the function alone in your own isosurface.</p>
<p>Parameters:</p>
<ul>
<li><code>MajorRadius, MinorRadius</code> = Base radii for the torus.</li>
<li><code>MajorControl, MinorControl</code> = Controls for the roundness of the supertorus. Use numbers in the range [0, 1].</li>
<li><code>Accuracy</code> = The accuracy parameter.</li>
<li><code>MaxGradient</code> = The max_gradient parameter.</li>
</ul>
<p><code>Supercone(EndA, A, B, EndB, C, D)</code>: This macro creates an object similar to a cone, but where the end points are ellipses. The actual object is an intersection of a quartic with a cylinder.</p>
<p>Parameters:</p>
<ul>
<li><code>EndA</code> = Center of end A.</li>
<li><code>A, B</code> = Controls for the radii of end A.</li>
<li><code>EndB</code> = Center of end B.</li>
<li><code>C, D</code> = Controls for the radii of end B.</li>
</ul>
<p><code>Connect_Spheres(PtA, RadiusA, PtB, RadiusB)</code>: This macro creates a cone that will smoothly join two spheres. It creates only the cone object, however, you will have to supply the spheres yourself or use the Round_Cone2() macro instead.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA</code> = Center of sphere A.</li>
<li><code>RadiusA</code> = Radius of sphere A.</li>
<li><code>PtB</code> = Center of sphere B.</li>
<li><code>RadiusB</code> = Radius of sphere B.</li>
</ul>
<p><code>Wire_Box_Union(PtA, PtB, Radius)</code>,</p>
<p><code>Wire_Box_Merge(PtA, PtB, Radius)</code>,</p>
<p><code>Wire_Box(PtA, PtB, Radius, UseMerge)</code>: Creates a wire-frame box from cylinders and spheres. The resulting object will fit entirely within a box object with the same corner points.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA</code> = Lower-left-front corner of box.</li>
<li><code>PtB</code> = Upper-right-back corner of box.</li>
<li><code>Radius</code> = The radius of the cylinders and spheres composing the object.</li>
<li><code>UseMerge</code> = Whether or not to use a merge.</li>
</ul>
<p><code>Round_Box_Union(PtA, PtB, EdgeRadius)</code>,</p>
<p><code>Round_Box_Merge(PtA, PtB, EdgeRadius)</code>,</p>
<p><code>Round_Box(PtA, PtB, EdgeRadius, UseMerge)</code>: Creates a box with rounded edges from boxes, cylinders and spheres. The resulting object will fit entirely within a box object with the same corner points. The result is slightly different from a superellipsoid, which has no truely flat areas.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA</code> = Lower-left-front corner of box.</li>
<li><code>PtB</code> = Upper-right-back corner of box.</li>
<li><code>EdgeRadius</code> = The radius of the edges of the box.</li>
<li><code>UseMerge</code> = Whether or not to use a merge.</li>
</ul>
<p><code>Round_Cylinder_Union(PtA, PtB, Radius, EdgeRadius)</code>,</p>
<p><code>Round_Cylinder_Merge(PtA, PtB, Radius, EdgeRadius)</code>,</p>
<p><code>Round_Cylinder(PtA, PtB, Radius, EdgeRadius, UseMerge)</code>: Creates a cylinder with rounded edges from cylinders and tori. The resulting object will fit entirely within a cylinder object with the same end points and radius. The result is slightly different from a superellipsoid, which has no truely flat areas.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA, PtB</code> = The end points of the cylinder.</li>
<li><code>Radius</code> = The radius of the cylinder.</li>
<li><code>EdgeRadius</code> = The radius of the edges of the cylinder.</li>
<li><code>UseMerge</code> = Whether or not to use a merge.</li>
</ul>
<p><code>Round_Cone_Union(PtA, RadiusA, PtB, RadiusB, EdgeRadius)</code>,</p>
<p><code>Round_Cone_Merge(PtA, RadiusA, PtB, RadiusB, EdgeRadius)</code>,</p>
<p><code>Round_Cone(PtA, RadiusA, PtB, RadiusB, EdgeRadius, UseMerge)</code>: Creates a cone with rounded edges from cones and tori. The resulting object will fit entirely within a cone object with the same end points and radii.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA, PtB</code> = The end points of the cone.</li>
<li><code>RadiusA, RadiusB</code> = The radii of the cone.</li>
<li><code>EdgeRadius</code> = The radius of the edges of the cone.</li>
<li><code>UseMerge</code> = Whether or not to use a merge.</li>
</ul>
<p><code>Round_Cone2_Union(PtA, RadiusA, PtB, RadiusB)</code>,</p>
<p><code>Round_Cone2_Merge(PtA, RadiusA, PtB, RadiusB)</code>,</p>
<p><code>Round_Cone2(PtA, RadiusA, PtB, RadiusB, UseMerge)</code>: Creates a cone with rounded edges from a cone and two spheres. The resulting object will not fit entirely within a cone object with the same end points and radii because of the spherical caps. The end points are not used for the conical portion, but for the spheres, a suitable cone is then generated to smoothly join them.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA, PtB</code> = The centers of the sphere caps.</li>
<li><code>RadiusA, RadiusB</code> = The radii of the sphere caps.</li>
<li><code>UseMerge</code> = Whether or not to use a merge.</li>
</ul>
<p><code>Round_Cone3_Union(PtA, RadiusA, PtB, RadiusB)</code>,</p>
<p><code>Round_Cone3_Merge(PtA, RadiusA, PtB, RadiusB)</code>,</p>
<p><code>Round_Cone3(PtA, RadiusA, PtB, RadiusB, UseMerge)</code>: Like Round_Cone2(), this creates a cone with rounded edges from a cone and two spheres, and the resulting object will not fit entirely within a cone object with the same end points and radii because of the spherical caps. The difference is that this macro takes the end points of the conical portion and moves the spheres to be flush with the surface, instead of putting the spheres at the end points and generating a cone to join them.</p>
<p>Parameters:</p>
<ul>
<li><code>PtA, PtB</code> = The end points of the cone.</li>
<li><code>RadiusA, RadiusB</code> = The radii of the cone.</li>
<li><code>UseMerge</code> = Whether or not to use a merge.</li>
</ul>
<p><code>Quad(A, B, C, D)</code> and <code>Smooth_Quad(A, NA, B, NB, C, NC, D, ND)</code>: These macros create <em>quads</em>, 4-sided polygonal objects, using triangle pairs.</p>
<p>Parameters:</p>
<ul>
<li><code>A, B, C, D</code> = Vertices of the quad.</li>
<li><code>NA, NB, NC, ND</code> = Vertex normals of the quad.</li>
</ul>
</div>
<a name="r3_4_9_1_18_1"></a>
<div class="content-level-h6" contains="The HF Macros" id="r3_4_9_1_18_1">
<h6>3.4.9.1.18.1 The HF Macros</h6>
<p>There are several HF macros in shapes.inc, which generate meshes in various shapes. All the HF macros have these things in common: </p>
<ul>
<li>The HF macros do not directly use an image for input, but evaluate a user-defined function. The macros deform the surface based on the function values.</li>
<li>The macros can either write to a file to be included later, or create an object directly. If you want to output to a file, simply specify a filename. If you want to create an object directly, specify "" as the file name (an empty string).</li>
<li>The function values used for the heights will be taken from the square that goes from <0,0,0> to <1,1,0> if UV height mapping is on. Otherwise the function values will be taken from the points where the surface is (before the deformation).</li>
<li>The texture you apply to the shape will be evaluated in the square that goes from <0,0,0> to <1,1,0> if UV texture mapping is on. Otherwise the texture is evaluated at the points where the surface is (after the deformation.</li>
</ul>
<p>The usage of the different HF macros is described below.</p>
<p><code>HF_Square (Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, MnExt, MxExt)</code>: This macro generates a mesh in the form of a square height field, similar to the built-in height_field primitive. Also see the general description of the HF macros above.</p>
<p>Parameters:</p>
<ul>
<li><code>Function</code> = The function to use for deforming the height field.</li>
<li><code>UseUVheight</code> = A boolean value telling the macro whether or not to use UV height mapping.</li>
<li><code>UseUVtexture</code> = A boolean value telling the macro whether or not to use UV texture mapping.</li>
<li><code>Res</code> = A 2D vector specifying the resolution of the generated mesh.</li>
<li><code>Smooth</code> = A boolean value telling the macro whether or not to smooth the generated mesh.</li>
<li><code>FileName</code> = The name of the output file.</li>
<li><code>MnExt</code> = Lower-left-front corner of a box containing the height field.</li>
<li><code>MxExt</code> = Upper-right-back corner of a box containing the height field.</li>
</ul>
<p><code>HF_Sphere(Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, Center, Radius, Depth)</code>: This macro generates a mesh in the form of a spherical height field. When UV-mapping is used, the UV square will be wrapped around the sphere starting at +x and going anti-clockwise around the y axis. Also see the general description of the HF macros above.</p>
<p>Parameters:</p>
<ul>
<li><code>Function</code> = The function to use for deforming the height field.</li>
<li><code>UseUVheight</code> = A boolean value telling the macro whether or not to use UV height mapping.</li>
<li><code>UseUVtexture</code> = A boolean value telling the macro whether or not to use UV texture mapping.</li>
<li><code>Res</code> = A 2D vector specifying the resolution of the generated mesh.</li>
<li><code>Smooth</code> = A boolean value telling the macro whether or not to smooth the generated mesh.</li>
<li><code>FileName</code> = The name of the output file.</li>
<li><code>Center</code> = The center of the height field before being displaced, the displacement can, and most likely will, make the object off-center.</li>
<li><code>Radius</code> = The starting radius of the sphere, before being displaced.</li>
<li><code>Depth</code> = The depth of the height field.</li>
</ul>
<p><code>HF_Cylinder(Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, EndA, EndB, Radius,Depth)</code>: This macro generates a mesh in the form of an open-ended cylindrical height field. When UV-mapping is used, the UV square will be wrapped around the cylinder. Also see the general description of the HF macros above.</p>
<p>Parameters:</p>
<ul>
<li><code>Function</code> = The function to use for deforming the height field.</li>
<li><code>UseUVheight</code> = A boolean value telling the macro whether or not to use UV height mapping.</li>
<li><code>UseUVtexture</code> = A boolean value telling the macro whether or not to use UV texture mapping.</li>
<li><code>Res</code> = A 2D vector specifying the resolution of the generated mesh.</li>
<li><code>Smooth</code> = A boolean value telling the macro whether or not to smooth the generated mesh.</li>
<li><code>FileName</code> = The name of the output file.</li>
<li><code>EndA, EndB</code> = The end points of the cylinder.</li>
<li><code>Radius</code> = The (pre-displacement) radius of the cylinder.</li>
<li><code>Depth</code> = The depth of the height field.</li>
</ul>
<p><code>HF_Torus (Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, Major, Minor, Depth)</code>: This macro generates a mesh in the form of a torus-shaped height field. When UV-mapping is used, the UV square is wrapped around similar to spherical or cylindrical mapping. However the top and bottom edges of the map wrap over and under the torus where they meet each other on the inner rim. Also see the general description of the HF macros above.</p>
<p>Parameters:</p>
<ul>
<li><code>Function</code> = The function to use for deforming the height field.</li>
<li><code>UseUVheight</code> = A boolean value telling the macro whether or not to use UV height mapping.</li>
<li><code>UseUVtexture</code> = A boolean value telling the macro whether or not to use UV texture mapping.</li>
<li><code>Res</code> = A 2D vector specifying the resolution of the generated mesh.</li>
<li><code>Smooth</code> = A boolean value telling the macro whether or not to smooth the generated mesh.</li>
<li><code>FileName</code> = The name of the output file.</li>
<li><code>Major</code> = The major radius of the torus.</li>
<li><code>Minor</code> = The minor radius of the torus.</li>
</ul></div>
<a name="r3_4_9_1_19"></a>
<div class="content-level-h5" contains="Shapes2.inc" id="r3_4_9_1_19">
<h5>3.4.9.1.19 Shapes2.inc</h5>
<dl>
<dt><code>Tetrahedron</code></dt>
<dd>4-sided regular polyhedron.</dd>
<dt><code>Octahedron</code></dt>
<dd>8-sided regular polyhedron.</dd>
<dt><code>Dodecahedron</code></dt>
<dd>12-sided regular polyhedron.</dd>
<dt><code>Icosahedron</code></dt>
<dd>20-sided regular polyhedron.</dd>
<dt><code>Rhomboid</code></dt>
<dd>Three dimensional 4-sided diamond, basically a sheared box.</dd>
<dt><code>Hexagon</code></dt>
<dd>6-sided regular polygonal solid, axis along x.</dd>
<dt><code>HalfCone_Y</code></dt>
<dd>Convenient finite cone primitive, pointing up in the Y axis.</dd>
<dt><code>Pyramid</code></dt>
<dd>4-sided pyramid (union of triangles, can not be used in CSG).</dd>
<dt><code>Pyramid2</code></dt>
<dd>4-sided pyramid (intersection of planes, can be used in CSG).</dd>
<dt><code>Square_X, Square_Y, Square_Z</code></dt>
<dd>Finite planes stretching 1 unit along each axis. In other words, 2X2 unit squares.</dd>
</dl></div>
<a name="r3_4_9_1_20"></a>
<div class="content-level-h5" contains="Shapes3.inc" id="r3_4_9_1_20">
<h5>3.4.9.1.20 Shapes3.inc</h5>
<p>This file contains macros for segments of shapes, facetted shapes and others.</p>
<p><strong>Segments of shapes:</strong></p>
<dl>
<dt><code>Segment_of_Torus ( R_major, R_minor, Segment_Angle )</code></dt>
<dd>Segment of a torus around the y axis. The angle starts at positive x axis.</dd>
<dt><code>Segment_of_CylinderRing ( R_out, R_in, Height, Segment_Angle )</code></dt>
<dd>Segment of a cylindrical ring around the y axis. The angle starts at positive x axis.</dd>
<dt><code>Segment_of_Object ( Segment_Object, Segment_Angle )</code></dt>
<dd>Segment of an object around the y axis. The angle starts at positive x axis.<br>
Based on min_extend and max_extend.</dd>
</dl>
<p><strong>Angular shapes:</strong></p>
<dl>
<dt><code>Column_N (N, R_in, Height )</code></dt>
<dd>A regular n-sided column around the y axis, defined by the incircle radius <code>R_in</code>. <code>Height</code> is the height in y direction.</dd>
<dt><code>Column_N_AB (N, A, B, R_in)</code></dt>
<dd>A regular n-sided column from point <code>A</code> to point <code>B</code>, defined by the incircle radius <code>R_in</code>.</dd>
<dt><code>Pyramid_N (N, R_in_1, R_in_2, Height )</code></dt>
<dd>A regular n-sided pyramid around the y axis, defined by the incircle radii:<br>
<code>R_in_1</code> at y = 0 and <code>R_in_2</code> at y = <code>Height</code>.</dd>
<dt><code>Pyramid_N_AB(N, A, R_in_A, B, R_in_B)</code></dt>
<dd>A regular n-sided column from point <code>A</code> to point <code>B</code>,
defined by the incircle radii:<br>
<code>R_in_A</code> at point <code>A</code> and <code>R_in_B</code> at point <code>B</code>.</dd>
</dl>
<p><strong>Facetted shapes:</strong></p>
<dl>
<dt><code>Facetted_Sphere (Quarter_Segments, Radial_Segments)</code></dt>
<dd>A facetted sphere with incircle radius 1.<br>
<code>Quarter_Segments</code> = number of equitorial facetts in one quarter (1/2 of the total number).<br>
<code>Radial_Segments</code> = number of radial facetts.</dd>
<dt><code>Facetted_Egg_Shape (Quarter_Segments, Radial_Segments, Lower_Scale, Upper_Scale)</code></dt>
<dd>A facetted egg shape. The number of facetts are defined analog to <code>Facetted_Egg_Shape()</code>.<br>
Equitorial incircle radius = 1. Lower half scaled in y by <code>Lower_Scale</code>,
Upper half scaled in y by <code>Upper_Scale</code>.</dd>
<dt><code>Facetted_Egg (N_Quarter_Segments, N_Radial_Segments)</code></dt>
<dd>A facetted egg with total height = 2. Lower half scaled in y by 1.15, Upper half scaled in y by 1.55.</dd>
</dl>
<p><strong>Round shapes:</strong></p>
<dl>
<dt><code>Egg_Shape (Lower_Scale, Upper_Scale)</code></dt>
<dd>An egg shape with equitorial radius 1. <br>
Lower half scaled in y by <code>Lower_Scale</code>,
Upper half scaled in y by <code>Upper_Scale</code>.</dd>
<dt><code>Egg</code></dt>
<dd>Uses the macro Egg_Shape.<br>
Lower half scaled in y by 1.15, upper half scaled in y by 1.55.</dt>
</dl>
Wireframe shape (mostly also optionally filled:
<dl>
<dt><code>Ring_Sphere (Rmaj_H, Rmaj_V, Rmin_H, Rmin_V, Number_of_Rings_horizontal, Number_of_Rings_vertical)</code></dt>
<dd>A wireframe sphere by vertical and horizontal torii. <br>
Horizontal tori: equatorial radius major <code>Rmaj_H</code>, radius minor <code>Rmin_H</code>.<br>
Vertical tori: radius major <code>Rmaj_V</code>, radius minor <code>Rmin_V</code>.</dd>
<dt><code>Round_Pyramid_N_out (N, A, CornerR_out_A, B, CornerR_out_B, R_Border, Filled, Merge )</code></dt>
<dd>A regular n-sided column from point <code>A</code> to point <code>B</code>,
defined by the outcircle radii:
<code>R_in_A</code> at point <code>A</code> and <code>R_in_B</code> at point <code>B</code>.</dd>
<dt><code>Round_Pyramid_N_in (N, A, FaceR_in_A, B, FaceR_in_B, R_Border, Filled, Merge_On )</code></dt>
<dd>A regular n-sided column from point <code>A</code> to point <code>B</code>,
defined by the incircle radii:
<code>R_in_A</code> at point <code>A</code> and <code>R_in_B</code> at point <code>B</code>..</dd>
<dt><code>Round_Cylinder_Tube( A, B, R_out, R_border, Filled, Merge)</code></dt>
<dd>A cylindrical tube from point <code>A</code> to point <code>B</code>,
with the outer radius <code>R_out</code> and the border radius <code>R_border</code>.
The inner radius is <code>R_out - R_border</code>.<br>
With <code>Filled</code> = 1 we get a <code>Round_Cylinder</code>.</dd>
<dt><code>Rounded_Tube( R_out, R_in, R_Border, Height, Merge)</code></dt>
<dd>A cylindrical tube around the y axis with the <code>Height</code> in y, with the outer radius <code>R_out</code>, the inner radius <code>R_in</code> and the radius of the rounded borders <code>R_border</code>.</dd>
<dt><code>Rounded_Tube_AB( A, B, R_out, R_in, R_Border, Merge)</code></dt>
<dd>A cylindrical tube from point <code>A</code> to point <code>B</code>.<br>
The outer radius is <code>R_out</code>, the inner radius is <code>R_in</code>
and the radius of the rounded borders is <code>R_border</code>.</dd>
<dt><code>Round_Conic_Torus( Center_Distance, R_upper, R_lower, R_border, Merge)</code></dt>
<dd>A toroid ring the z axis,
with the lower torus part at y = 0 and the upper part at y = Center_Distance.<br>
The radius of the lower part is <code>R_lower</code>,
the radius of the lower part is <code>R_lower</code>
The minor radius of the toroid is <code>R_border</code>.</dd>
<dt><code>Round_Conic_Prism( Center_Distance, R_upper, R_lower, Length_Zminus, R_Border, Merge)</code></dt>
<dd>A shape of the toroidal form like <code>Round_Conic_Torus()</code>,
but filled and in the negativ z direction with the length <code> Length_Zminus</code>.</dd>
<dt><code>Half_Hollowed_Rounded_Cylinder1( Length, R_out, R_border, BorderScale, Merge)</code></dt>
<dd>A hollowed half rounded cylinder with the <code>Length</code> in x, of the outer radius <code>R_out</code>, with round ends.
The borders have a minor radius <code>R_border</code> with the scale in y <code>BorderScale</code>.<br>
The inner radius is <code>R_out - R_border</code>.</dd>
<dt><code>Half_Hollowed_Rounded_Cylinder2( Length, R_out, R_corner, R_border, BorderScale, Merge)</code></dt>
<dd>A hollowed half rounded cylinder with the <code>Length</code> in x, of the outer radius <code>R_out</code>, with flat ends.
The corners have a minor radius of <code>R_corner</code>,
the borders have a minor radius of <code>R_border</code> with the scale in y <code>BorderScale</code>.<br>
The inner radius is <code>R_out - R_border</code>, the inner lenght is <code>Length - 2*R_border</code>.</dd>
<dt><code>Round_N_Tube_Polygon (N, Tube_R, R_incircle, Edge_R, Filled, Merge)</code></dt>
<dd>A regular polygon with <code>N</code> edges (or corners) with incircle radius <code>R_incircle</code>,
formed by a tube with the minor radius <code>Tube_R</code>.
The corners are formed by torus segments with the major radius <code>Edge_R</code>.</dd>
</dl></div>
<a name="r3_4_9_1_21"></a>
<div class="content-level-h5" contains="Shapesq.inc" id="r3_4_9_1_21">
<h5>3.4.9.1.21 Shapesq.inc</h5>
<dl>
<dt><code>Bicorn</code></dt>
<dd>This curve looks like the top part of a paraboloid, bounded from below by another paraboloid.
The basic equation is: </dd>
<dd>y^2 - (x^2 + z^2) y^2 - (x^2 + z^2 + 2 y - 1)^2 = 0</dd>
<dt><code>Crossed_Trough</code></dt>
<dd>This is a surface with four pieces that sweep up from the x-z plane.</dd>
<dd>The equation is: y = x^2 z^2</dd>
<dt><code>Cubic_Cylinder</code></dt>
<dd>A drop coming out of water? This is a curve formed by using the equation:</dd>
<dd>y = 1/2 x^2 (x + 1)</dd>
<dd>as the radius of a cylinder having the x-axis as its central axis. The final form of the equation is:</dd>
<dd>y^2 + z^2 = 0.5 (x^3 + x^2)</dd>
<dt><code>Cubic_Saddle_1</code></dt>
<dd>A cubic saddle. The equation is: z = x^3 - y^3</dd>
<dt><code>Devils_Curve</code></dt>
<dd>Variant of a devil's curve in 3-space. This figure has a top and bottom part that are very similar to a hyperboloid of one sheet, however the central region is pinched in the middle leaving two teardrop shaped holes.
The equation is:</dd>
<dd>x^4 + 2 x^2 z^2 - 0.36 x^2 - y^4 + 0.25 y^2 + z^4 = 0</dd>
<dt><code>Folium</code></dt>
<dd>This is a folium rotated about the x-axis. The formula is:</dd>
<dd>2 x^2 - 3 x y^2 - 3 x z^2 + y^2 + z^2 = 0</dd>
<dt><code>Glob_5</code></dt>
<dd>Glob - sort of like basic teardrop shape. The equation is:</dd>
<dd>y^2 + z^2 = 0.5 x^5 + 0.5 x^4</dd>
<dt><code>Twin_Glob</code></dt>
<dd>Variant of a lemniscate - the two lobes are much more teardrop-like.</dd>
<dt><code>Helix, Helix_1</code></dt>
<dd>Approximation to the helix z = arctan(y/x).
The helix can be approximated with an algebraic equation (kept to the range of a quartic) with the following steps:</dd>
<dd>tan(z) = y/x => sin(z)/cos(z) = y/x =><br>
(1) x sin(z) - y cos(z) = 0
Using the taylor expansions for sin, cos about z = 0,<br>
sin(z) = z - z^3/3! + z^5/5! - ...<br>
cos(z) = 1 - z^2/2! + z^6/6! - ...<br>
Throwing out the high order terms, the expression (1) can be written as:<br>
x (z - z^3/6) - y (1 + z^2/2) = 0, or<br><br>
(2) -1/6 x z^3 + x z + 1/2 y z^2 - y = 0<br>
This helix (2) turns 90 degrees in the range 0 <= z <= sqrt(2)/2.
By using scale <2 2 2>, the helix defined below turns 90 degrees in the range 0 <= z <= sqrt(2) = 1.4042.</dd>
<dt><code>Hyperbolic_Torus</code></dt>
<dd>Hyperbolic Torus having major radius sqrt(40), minor radius sqrt(12). This figure is
generated by sweeping a circle along the arms of a hyperbola. The equation is:</dd>
<dd>x^4 + 2 x^2 y^2 - 2 x^2 z^2 - 104 x^2 + y^4 - 2 y^2 z^2 + 56 y^2 + z^4 + 104 z^2 + 784 = 0</dd>
<dt><code>Lemniscate</code></dt>
<dd>Lemniscate of Gerono. This figure looks like two teardrops with their pointed ends connected. It is formed by rotating the Lemniscate of Gerono about the x-axis. The formula is:</dd>
<dd>x^4 - x^2 + y^2 + z^2 = 0</dd>
<dt><code>Quartic_Loop_1</code></dt>
<dd>This is a figure with a bumpy sheet on one side and something that looks like a paraboloid (but with an internal bubble). The formula is:</dd>
<dd>(x^2 + y^2 + a c x)^2 - (x^2 + y^2)(c - a x)^2</dd>
<dd>-99*x^4+40*x^3-98*x^2*y^2-98*x^2*z^2+99*x^2+40*x*y^2</dd>
<dd>+40*x*z^2+y^4+2*y^2*z^2-y^2+z^4-z^2</dd>
<dt><code>Monkey_Saddle</code></dt>
<dd>This surface has three parts that sweep up and three down. This gives a saddle that has a place for two legs and a tail. The equation is:</dd>
<dd><code>z = c (x^3 - 3 x y^2)</code></dd>
<dd>The value c gives a vertical scale to the surface - the smaller the value of c, the flatter the surface will be (near the origin).</dd>
<dt><code>Parabolic_Torus_40_12</code></dt>
<dd>Parabolic Torus having major radius sqrt(40), minor radius sqrt(12). This figure is generated by sweeping a circle along the arms of a parabola. The equation is:</dd>
<dd>x^4 + 2 x^2 y^2 - 2 x^2 z - 104 x^2 + y^4 - 2 y^2 z + 56 y^2 + z^2 + 104 z + 784 = 0</dd>
<dt><code>Piriform</code></dt>
<dd>This figure looks like a hersheys kiss. It is formed by sweeping a Piriform about the x-axis. A basic form of the equation is:</dd>
<dd>(x^4 - x^3) + y^2 + z^2 = 0.</dd>
<dt><code>Quartic_Paraboloid</code></dt>
<dd>Quartic parabola - a 4th degree polynomial (has two bumps at the bottom) that has been swept around the z axis. The equation is:</dd>
<dd>0.1 x^4 - x^2 - y^2 - z^2 + 0.9 = 0</dd>
<dt><code>Quartic_Cylinder</code></dt>
<dd>Quartic Cylinder - a Space Needle?</dd>
<dt><code>Steiner_Surface</code></dt>
<dd>Steiners quartic surface</dd>
<dt><code>Torus_40_12</code></dt>
<dd>Torus having major radius sqrt(40), minor radius sqrt(12).</dd>
<dt><code>Witch_Hat</code></dt>
<dd>Witch of Agnesi.</dd>
<dt><code>Sinsurf</code></dt>
<dd>Very rough approximation to the sin-wave surface z = sin(2 pi x y).</dd>
<dd>In order to get an approximation good to 7 decimals at a distance of 1 from the origin would require a polynomial of degree around 60, which would require around 200,000 coefficients. For best results, scale by something like <1 1 0.2>.</dd>
</dl></div>
<a name="r3_4_9_1_22"></a>
<div class="content-level-h5" contains="Skies.inc" id="r3_4_9_1_22">
<h5>3.4.9.1.22 Skies.inc</h5>
<p>These files contain some predefined skies for you to use in your scenes.</p>
<p>skies.inc: There are textures and pigment definitions in this file.</p>
<ul>
<li>all pigment definitions start with "P_"</li>
<li>all sky_spheres start with "S_"</li>
<li>all textures start with "T_"</li>
<li>and all objects start with "O_"</li>
</ul>
<p>Pigments:</p>
<dl>
<dt><code>P_Cloud1</code></dt>
<dt><code>P_Cloud2</code></dt>
<dt><code>P_Cloud3</code></dt>
</dl>
<p>Sky Spheres:</p>
<dl>
<dt><code>S_Cloud1</code></dt>
<dd>This sky_sphere uses P_Cloud2 and P_Cloud3.</dd>
<dt><code>S_Cloud2</code></dt>
<dd>This sky_sphere uses P_Cloud4.</dd>
<dt><code>S_Cloud3</code></dt>
<dd>This sky_sphere uses P_Cloud2.</dd>
<dt><code>S_Cloud4</code></dt>
<dd>This sky_sphere uses P_Cloud3.</dd>
<dt><code>S_Cloud5</code></dt>
<dd>This sky_sphere uses a custom pigment.</dd>
</dl>
<p>Textures:</p>
<dl>
<dt><code>T_Cloud1</code></dt>
<dd>2-layer texture using P_Cloud1 pigment, contains clear regions.</dd>
<dt><code>T_Cloud2</code></dt>
<dd>1-layer texture, contains clear regions.</dd>
<dt><code>T_Cloud3</code></dt>
<dd>2-layer texture, contains clear regions.</dd>
</dl>
<p>Objects:</p>
<dl>
<dt><code>O_Cloud1</code></dt>
<dd>Sphere, radius 10000 with T_Cloud1 texture.</dd>
<dt><code>O_Cloud2</code></dt>
<dd>Union of 2 planes, with T_Cloud2 and T_Cloud3.</dd>
</dl></div>
<a name="r3_4_9_1_23"></a>
<div class="content-level-h5" contains="Stars.inc" id="r3_4_9_1_23">
<h5>3.4.9.1.23 Stars.inc</h5>
<p>stars.inc: This file contains predefined starfield textures. The starfields become denser and more colorful with the number, with Starfield6 being the densest and most colorful.</p>
<dl>
<dt><code>Starfield1</code></dt>
<dt><code>Starfield2</code></dt>
<dt><code>Starfield3</code></dt>
<dt><code>Starfield4</code></dt>
<dt><code>Starfield5</code></dt>
<dt><code>Starfield6</code></dt>
</dl></div>
<a name="r3_4_9_1_24"></a>
<div class="content-level-h5" contains="Stones.inc" id="r3_4_9_1_24">
<h5>3.4.9.1.24 Stones.inc</h5>
<p>The file <em>stones.inc</em> simply includes both <em>stones1.inc</em> and <em>stones2.inc</em>, and the file <em>stoneold.inc</em> provides backwards compatability for old scenes, the user is advised to use the textures in <em>stones1.inc</em> instead.</p>
<p>The two files stones1.inc and stones2.inc contain lists of predefined stone textures.</p>
<p>The file <em>stones1.inc</em> contains texture definitions for:</p>
<ul>
<li>T_Grnt0 to T_Grnt29</li>
<li>T_Grnt1a to T_Grnt24a</li>
<li>T_Stone0 to T_Stone24</li>
</ul>
<p>The T_GrntXX, T_GrntXXa, and CrackX textures are building blocks that are used to create the final <em>usable</em> T_StoneX textures (and other textures that *you* design, of course!)</p>
<p>The T_GrntXX textures generally contain no transparency, but the T_GrntXXa textures <em>DO</em> contain transparency. The CrackX textures are clear with thin opaque bands, simulating cracks.</p>
<p>The file <em>stones2.inc</em> provides additional stone textures, and contains texture definitions for T_Stone25 to T_Stone44.</p></div>
<a name="r3_4_9_1_25"></a>
<div class="content-level-h5" contains="Stdinc.inc" id="r3_4_9_1_25">
<h5>3.4.9.1.25 Stdinc.inc</h5>
<p>This file simply includes the most commonly used include files,
so you can get all of them with a single #include.
The files included are:</p>
<ul>
<li>colors.inc</li>
<li>shapes.inc</li>
<li>transforms.inc</li>
<li>consts.inc</li>
<li>functions.inc</li>
<li>math.inc</li>
<li>rand.inc</li>
</ul></div>
<a name="r3_4_9_1_26"></a>
<div class="content-level-h5" contains="Strings.inc" id="r3_4_9_1_26">
<h5>3.4.9.1.26 Strings.inc</h5>
<p>This include contains macros for manipulating and generating text strings.</p>
<p><code>CRGBStr(C, MinLen, Padding)</code> and <code>CRGBFTStr(C, MinLen, Padding)</code>: These macros convert a color to a string. The format of the output string is "rgb < R, G, B>" or "rgbft < R, G, B, F, T>", depending on the macro being called.</p>
<p>Parameters:</p>
<ul>
<li><code>C</code> = The color to be turned into a string.</li>
<li><code>MinLen</code> = The minimum length of the individual components, analogous to the second parameter of str().</li>
<li><code>Padding</code> = The padding to use for the components, see the third parameter of the str() function for details.</li>
</ul>
<p><code>Str(A)</code>: This macro creates a string containing a float with the systems default precision. It is a shortcut for using the str() function.</p>
<p>Parameters:</p><ul>
<li><code>A</code> = The float to be converted to a string.</li>
</ul>
<p><code>VStr2D(V), VStr(V)</code>: These macros create strings containing vectors using POV syntax (<X,Y,Z>) with the default system precision. VStr2D() works with 2D vectors, VStr() with 3D vectors. They are shortcuts for using the <code>vstr()</code> function.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = The vector to be converted to a string.</li>
</ul>
<p><code>Vstr2D(V,L,P), Vstr(V,L,P)</code>: These macros create strings containing vectors using POV syntax (<X,Y,Z>) with user specified precision. Vstr2D() works with 2D vectors, Vstr() with 3D vectors. They are shortcuts for using the vstr() function. The function of L and P is the same as in <code>vstr</code> specified in <a href="r3_3.html#r3_3_1_9_4">String Functions</a>.</p>
<p>Parameters:</p>
<ul>
<li><code>V</code> = The vector to be converted to a string.</li>
<li><code>L</code> = Minimum length of the string and the type of left padding used if the string's representation is shorter than the minimum.</li>
<li><code>P</code> = Number of digits after the decimal point.</li>
</ul>
<p><code>Triangle_Str(A, B, C)</code> and <code>Smooth_Triangle_Str(A, NA, B, NB, C, NC)</code>: These macros take vertex and normal information and return a string representing a triangle in POV-Ray syntax. They are mainly useful for generating mesh files.</p>
<p>Parameters:</p>
<ul>
<li><code>A, B, C</code> = Triangle vertex points.</li>
<li><code>NA, NB, NC</code> = Triangle vertex normals (Smooth_Triangle_Str() only).</li>
</ul>
<p><code>Parse_String(String)</code>: This macro takes a string, writes it to a file, and then includes that file. This has the effect of parsing that string: "<code>Parse_String("MyColor")</code>" will be seen by POV-Ray as "<code>MyColor</code>".</p>
<p>Parameters:</p>
<ul>
<li><code>String</code> = The string to be parsed.</li>
</ul></div>
<a name="r3_4_9_1_27"></a>
<div class="content-level-h5" contains="Sunpos.inc" id="r3_4_9_1_27">
<h5>3.4.9.1.27 Sunpos.inc</h5>
<p> This file only contains the sunpos() macro</p>
<p><code>sunpos(Year, Month, Day, Hour, Minute, Lstm, LAT, LONG)</code>: The macro returns the position of the sun, for a given date, time, and location on earth. The suns position is also globally declared as the vector <code>SolarPosition</code>. Two other declared vectors are the <code>Az</code> (Azimuth) and <code>Al</code> (Altitude), these can be useful for aligning an object (media container) with the sunlight. Assumption: in the scene north is in the +Z direction, south is -Z.</p>
<p>Parameters:</p>
<ul>
<li><code>Year</code>= The year in four digits.</li>
<li><code>Month</code>= The month number (1-12).</li>
<li><code>Day</code>= The day number (1-31).</li>
<li><code>Hour</code>= The hour of day in 24 hour format (0-23).</li>
<li><code>Minute</code>= The minutes (0-59). </li>
<li><code>Lstm</code>= Meridian of your local time zone in degrees (+1 hour = +15 deg, east = positive, west = negative)</li>
<li><code>LAT</code>= Lattitude in degrees.decimal, northern hemisphere = positive, southern = negative</li>
<li><code>LONG</code>= Longitude in degrees.decimal, east = positive, west is negative</li>
</ul>
<p>Usage:</p>
<pre>
#include "sunpos.inc"
light_source {
//Greenwich, noon on the longest day of 2000
SunPos(2000, 6, 21, 12, 2, 0, 51.4667, 0.00)
rgb 1
}
cylinder{
<-2,0,0>,<2,0,0>,0.1
rotate <0, Az-90, Al> //align cylinder with sun
texture {...}
}
</pre>
<p class="Note"><strong>Note:</strong> The default distance of the sun from the origin is 1e+9 units.</p></div>
<a name="r3_4_9_1_28"></a>
<div class="content-level-h5" contains="Textures.inc" id="r3_4_9_1_28">
<h5>3.4.9.1.28 Textures.inc</h5>
<p>This file contains many predefined textures, including wood, glass, and metal textures, and a few texture/pattern generation macros.</p>
</div>
<a name="r3_4_9_1_28_1"></a>
<div class="content-level-h6" contains="Stones" id="r3_4_9_1_28_1">
<h6>3.4.9.1.28.1 Stones</h6>
<p>Stone Pigments:</p>
<dl>
<dt><code>Jade_Map, Jade</code></dt>
<dd>Drew Wells' superb Jade. Color map works nicely with other textures, too.</dd>
<dt><code>Red_Marble_Map, Red_Marble</code></dt>
<dd>Classic white marble with red veins. Over-worked, like checkers.</dd>
<dt><code>White_Marble_Map, White_Marble</code></dt>
<dd>White marble with black veins.</dd>
<dt><code>Blood_Marble_Map, Blood_Marble</code></dt>
<dd>Light blue and black marble with a thin red vein.</dd>
<dt><code>Blue_Agate_Map, Blue_Agate</code></dt>
<dd>A grey blue agate -- kind of purplish.</dd>
<dt><code>Sapphire_Agate_Map, Sapphire_Agate</code></dt>
<dd>Deep blue agate -- almost glows.</dd>
<dt><code>Brown_Agate_Map, Brown_Agate</code></dt>
<dd>Brown and white agate -- very pretty.</dd>
<dt><code>Pink_Granite_Map, Pink_Granite</code></dt>
<dd>Umm, well, pink granite.</dd>
</dl>
<p>Stone textures:</p>
<dl>
<dt><code>PinkAlabaster</code></dt>
<dd>Gray-pink alabaster or marble. Layers are scaled for a unit object and relative to each other.</dd>
<dd><p class="Note"><strong>Note:</strong> This texture has very tiny dark blue specks that are often mistaken for rendering errors.</p></dd>
<dd>Underlying surface is very subtly mottled with bozo.</dd>
<dd>Second layer texture has some transmit values, yet a fair amount of color.</dd>
<dd>Veining is kept quite thin in color map and by the largish scale.</dd>
</dl>
</div>
<a name="r3_4_9_1_28_2"></a>
<div class="content-level-h6" contains="Skies" id="r3_4_9_1_28_2">
<h6>3.4.9.1.28.2 Skies</h6>
<p>Sky pigments:</p>
<dl>
<dt><code>Blue_Sky_Map, Blue_Sky</code></dt>
<dd>Basic blue sky with clouds.</dd>
<dt><code>Bright_Blue_Sky</code></dt>
<dd>Bright blue sky with very white clouds.</dd>
<dt><code>Blue_Sky2</code></dt>
<dd>Another sky.</dd>
<dt><code>Blue_Sky3</code></dt>
<dd>Small puffs of white clouds.</dd>
<dt><code>Blood_Sky</code></dt>
<dd>Red sky with yellow clouds -- very surreal.</dd>
<dt><code>Apocalypse</code></dt>
<dd>Black sky with red and purple clouds.</dd>
<dd>Try adding turbulence values from 0.1 - 5.0</dd>
<dt><code>Clouds</code></dt>
<dd>White clouds with transparent sky.</dd>
<dt><code>FBM_Clouds</code></dt>
<dt><code>Shadow_Clouds</code></dt>
<dd>A multilayered cloud texture (a real texture, not a pigment).</dd>
</dl>
</div>
<a name="r3_4_9_1_28_3"></a>
<div class="content-level-h6" contains="Woods" id="r3_4_9_1_28_3">
<h6>3.4.9.1.28.3 Woods</h6>
<p>Wood pigments:</p>
<p>Several wooden pigments by Tom Price:</p>
<dl>
<dt><code>Cherry_Wood</code></dt>
<dd>A light reddish wood.</dd>
<dt><code>Pine_Wood</code></dt>
<dd>A light tan wood whiteish rings.</dd>
<dt><code>Dark_Wood</code></dt>
<dd>Dark wood with a,ish hue to it.</dd>
<dt><code>Tan_Wood</code></dt>
<dd>Light tan wood with brown rings.</dd>
<dt><code>White_Wood</code></dt>
<dd>A very pale wood with tan rings -- kind of balsa-ish.</dd>
<dt><code>Tom_Wood</code></dt>
<dd>Brown wood - looks stained.</dd>
</dl>
<dl>
<dt><code>DMFWood1, DMFWood2, DMFWood3, DMFWood4, DMFWood5</code></dt>
<dd>The scaling in these definitions is relative to a unit-sized object (radius 1).
<p class="Note"><strong>Note:</strong> These wood definitions are functionally equivalent to a log lying along the z axis. For best results, think like a woodcutter trying to extract the nicest board out of that log. A little tilt along the x axis will give elliptical rings of grain like you would expect to find on most boards.</p></dd>
</dl>
<p>Wood textures:</p>
<dl>
<dt><code>DMFWood6</code></dt>
<dd>This is a three-layer wood texture. Renders rather slowly because of the transparent layers and the two layers of turbulence, but it looks great. Try other colors of <em>varnish</em> for simple variations.</dd>
<dt><code>DMFLightOak</code></dt>
<dd>Is this really oak? I dunno. Quite light, maybe more like spruce.</dd>
<dt><code>DMFDarkOak</code></dt>
<dd>Looks like old desk oak if used correctly.</dd>
<dt><code>EMBWood1</code></dt>
<dd>Wood by Eric Barish</dd>
</dl>
<p>Doug Otwell woods:</p>
<dl>
<dt><code>Yellow_Pine</code></dt>
<dd>Yellow pine, close grained.</dd>
<dt><code>Rosewood</code></dt>
<dt><code>Sandalwood</code></dt>
<dd>makes a great burled maple, too</dd>
</dl>
</div>
<a name="r3_4_9_1_28_4"></a>
<div class="content-level-h6" contains="Glass" id="r3_4_9_1_28_4">
<h6>3.4.9.1.28.4 Glass</h6>
<p><code>Glass_Finish</code> is a generic glass finish, <code>Glass_Interior</code> is a generic glass interior, it just adds an ior of 1.5.</p>
<p>Glass materials:</p>
<dl>
<dt><code>M_Glass</code></dt>
<dd>Just glass.</dd>
<dt><code>M_Glass2</code></dt>
<dd>Probably more of a <em>Plexiglas</em> than glass.</dd>
<dt><code>M_Glass3</code></dt>
<dd>An excellent lead crystal glass!</dd>
<dt><code>M_Green_Glass</code></dt>
</dl>
<p>Glass textures contributed by Norm Bowler, of Richland WA. NBglass_finish is used by these materials.
</p>
<dl>
<dt><code>M_NBglass</code></dt>
<dt><code>M_NBoldglass</code></dt>
<dt><code>M_NBwinebottle</code></dt>
<dt><code>M_NBbeerbottle</code></dt>
</dl>
<p>A few color variations on Norm's glass.</p>
<dl>
<dt><code>M_Ruby_Glass</code></dt>
<dt><code>M_Dark_Green_Glass</code></dt>
<dt><code>M_Yellow_Glass</code></dt>
<dt><code>M_Orange_Glass</code></dt>
<dt><code>M_Vicks_Bottle_Glass</code></dt>
</dl>
</div>
<a name="r3_4_9_1_28_5"></a>
<div class="content-level-h6" contains="Metals" id="r3_4_9_1_28_5">
<h6>3.4.9.1.28.5 Metals</h6>
<p>Metal finishes:</p>
<dl>
<dt><code>Metal</code></dt>
<dd>Generic metal finish.</dd>
<dt><code>SilverFinish</code></dt>
<dd>Basic silver finish</dd>
<dt><code>Metallic_Finish</code></dt>
</dl>
<p>
Metal textures:
</p>
<dl>
<dt><code>Chrome_Metal, Brass_Metal, Bronze_Metal, Gold_Metal, Silver_Metal, Copper_Metal</code></dt>
<dd>A series of metallic textures using the Metal finish (except for Chrome_Metal, which has a custom finish). There are identical textures ending in _Texture instead of _Metal, but use of those names is discouraged.</dd>
<dt><code>Polished_Chrome</code></dt>
<dd>A highly reflective Chrome texture.</dd>
<dt><code>Polished_Brass</code></dt>
<dd>A highly reflective brass texture.</dd>
<dt><code>New_Brass</code></dt>
<dd>Beautiful military brass texture!</dd>
<dt><code>Spun_Brass</code></dt>
<dd>Spun Brass texture for cymbals & such</dd>
<dt><code>Brushed_Aluminum</code></dt>
<dd>Brushed aluminum (brushed along X axis)</dd>
<dt><code>Silver1</code></dt>
<dt><code>Silver2</code></dt>
<dt><code>Silver3</code></dt>
<dt><code>Brass_Valley</code></dt>
<dd>Sort of a <em>Black Hills Gold</em>, black, white, and orange specks or splotches.</dd>
<dt><code>Rust</code></dt>
<dt><code>Rusty_Iron</code></dt>
<dt><code>Soft_Silver</code></dt>
<dt><code>New_Penny</code></dt>
<dt><code>Tinny_Brass</code></dt>
<dt><code>Gold_Nugget</code></dt>
<dt><code>Aluminum</code></dt>
<dt><code>Bright_Bronze</code></dt>
</dl>
</div>
<a name="r3_4_9_1_28_6"></a>
<div class="content-level-h6" contains="Special textures" id="r3_4_9_1_28_6">
<h6>3.4.9.1.28.6 Special textures</h6>
<dl>
<dt><code>Candy_Cane</code></dt>
<dd>Red and white stripes - Looks best on a y axis Cylinder.</dd>
<dd>It <em>spirals</em> because it's gradient on two axis.</dd>
<dt><code>Peel</code></dt>
<dd>Orange and Clear stripes spiral around the texture to make an object look like it was <em>Peeled</em>. Now, you too can be M.C. Escher!</dd>
<dt><code>Y_Gradient</code></dt>
<dt><code>X_Gradient</code></dt>
<dt><code>M_Water</code></dt>
<dd>Wavy water material. Requires a sub-plane, and may require scaling to fit your scene.</dd>
<dd><p class="Warning"><strong>Warning:</strong> Water texture has been changed to M_Water material, see explanation in the <em>glass</em> section of this file.</p></dd>
<dt><code>Cork</code></dt>
<dt><code>Lightning_CMap1, Lightning1, and Lightning_CMap2, Lightning2</code></dt>
<dd>These are just lightning textures, they look like arcing electricity...earlier versions misspelled them as <em>Lightening</em>.</dd>
<dt><code>Starfield</code></dt>
<dd>A starfield texture by Jeff Burton</dd>
</dl>
</div>
<a name="r3_4_9_1_28_7"></a>
<div class="content-level-h6" contains="Texture and pattern macros" id="r3_4_9_1_28_7">
<h6>3.4.9.1.28.7 Texture and pattern macros</h6>
<p><code>Irregular_Bricks_Ptrn (Mortar Thickness, X-scaling, Variation, Roundness)</code>: This function pattern creates a pattern of bricks of varying lengths on the x-y plane. This can be useful in building walls that do not look like they were built by a computer. Note that mortar thickness between bricks can vary somewhat, too.</p>
<p>Parameters:</p>
<ul>
<li><code>Mortar Thickness</code> = Thickness of the mortar (0-1).</li>
<li><code>X-scaling</code> = The scaling of the bricks (but not the mortar) in the x direction.</li>
<li><code>Variation</code> = The amount by which brick lengths will vary (0=none, 1=100%).</li>
<li><code>Roundness</code> = The roundness of the bricks (0.01=almost rectangular, 1=very round).</li>
</ul>
<p><code>Tiles_Ptrn()</code>: This macro creates a repeating box pattern on the x-y plane. It can be useful for creating grids. The cells shade continuously from the center to the edges.</p>
<p>Parameters: None.</p>
<p><code>Hex_Tiles_Ptrn()</code>: This macro creates a pattern that is a sort of cross between the hexagon pattern and a repeating box pattern. The hexagonal cells shade continuously from the center to the edges.</p>
<p>Parameters: None.</p>
<p><code>Star_Ptrn (Radius, Points, Skip)</code>: This macro creates a pattern that resembles a star. The pattern is in the x-y plane, centered around the origin.</p>
<p>Parameters:</p>
<ul>
<li><code>Radius</code> = The radius of a circle drawn through the points of the star.</li>
<li><code>Points</code> = The number of points on the star.</li>
<li><code>Skip</code> = The number of points to skip when drawing lines between points to form the star.
A normal 5-pointed star skips 2 points. A Star of David also skips 2 points. Skip
must be less than Points/2 and greater than 0. Integers are preferred but not
required. Skipping 1 point makes a regular polygon with Points sides.</li>
<li><code>Pigment</code> = The pigment to be applied to the star.</li>
<li><code>Background</code> = The pigment to be applied to the background.</li>
</ul></div>
<a name="r3_4_9_1_29"></a>
<div class="content-level-h5" contains="Transforms.inc" id="r3_4_9_1_29">
<h5>3.4.9.1.29 Transforms.inc</h5>
<p>Several useful transformation macros. All these macros produce transformations, you can use them anywhere you can use scale, rotate, etc. The descriptions will assume you are working with an object, but the macros will work fine for textures, etc.</p>
<p><code>Shear_Trans(A, B, C)</code>: This macro reorients and deforms an object so its original XYZ axes point along A, B, and C, resulting in a shearing effect when the vectors are not perpendicular. You can also use vectors of different lengths to affect scaling, or use perpendicular vectors to reorient the object.</p>
<p>Parameters:</p>
<ul>
<li><code>A, B, C</code> = Vectors representing the new XYZ axes for the transformation.</li>
</ul>
<p><code>Matrix_Trans(A, B, C, D)</code>: This macro provides a way to specify a matrix transform with 4 vectors. The effects are very similar to that of the Shear_Trans() macro, but the fourth parameter controls translation.</p>
<p>Parameters:</p>
<ul>
<li><code>A, B, C, D</code> = Vectors for each row of the resulting matrix.</li>
</ul>
<p><code>Axial_Scale_Trans(Axis, Amt)</code>: A kind of directional scale, this macro will <em>stretch</em> an object along a specified axis.</p>
<p>Parameters:</p>
<ul>
<li><code>Axis</code> = A vector indicating the direction to stretch along.</li>
<li>Amt = The amount to stretch.</li>
</ul>
<p><code>Axis_Rotate_Trans(Axis, Angle)</code>: This is equivalent to the transformation done by the vaxis_rotate() function, it rotates around an arbitrary axis.</p>
<p>Parameters:</p>
<ul>
<li><code>Axis</code> = A vector representing the axis to rotate around.</li>
<li><code>Angle</code> = The amount to rotate by.</li>
</ul>
<p><code>Rotate_Around_Trans(Rotation, Point)</code>: Ordinary rotation operates around the origin, this macro rotates around a specific point.</p>
<p>Parameters:</p>
<ul>
<li><code>Rotation</code> = The rotation vector, the same as the parameter to the rotate keyword.</li>
<li><code>Point</code> = The point to rotate around.</li>
</ul>
<p><code>Reorient_Trans(Axis1, Axis2)</code>: This aligns <code>Axis1</code> to <code>Axis2</code> by rotating the object around a vector perpendicular to both axis1 and axis2.</p>
<p>Parameters:</p>
<ul>
<li><code>Axis1</code> = Vector to be rotated.</li>
<li><code>Axis2</code> = Vectors to be rotated towards.</li>
</ul>
<p><code>Point_At_Trans(YAxis)</code>: This macro is similar to Reorient_Trans(), but it points the y axis along Axis.</p>
<p>Parameters:</p>
<ul>
<li><code>YAxis</code> = The direction to point the y axis in.</li>
</ul>
<p><code>Center_Trans(Object, Axis)</code>: Calculates a transformation which will center an object along a specified axis. You indicate the axes you want to center along by adding "x", "y", and "z" together in the Axis parameter.</p>
<p class="Note"><strong>Note:</strong> This macro actually computes the transform to center the bounding box of the object, which may not be entirely accurate. There is no way to define the <em>center</em> of an arbitrary object.</p>
<p>Parameters:</p>
<ul>
<li><code>Object</code> = The object the center transform is being computed for.</li>
<li><code>Axis</code> = The axes to center the object on.</li>
</ul>
<p>Usage:</p>
<pre>
object {MyObj Center_Trans(MyObj, x)} //center along x axis
</pre>
<p> You can also center along multiple axes:</p>
<pre>
object {MyObj Center_Trans(MyObj, x+y)} //center along x and y axis
</pre>
<p><code>Align_Trans(Object, Axis, Pt)</code>: Calculates a transformation which will align the sides of the bounding box of an object to a point. Negative values on Axis will align to the sides facing the negative ends of the coordinate system, positive values will align to the opposite sides, 0 means not to do any alignment on that axis.</p>
<p>Parameters:</p>
<ul>
<li><code>Object</code> = The object being aligned.</li>
<li><code>Axis</code> = A combination of +x, +y, +z, -x, -y, and -z, or a vector where each component is -1, 0, or +1 specifying the faces of the bounding box to align to the point.</li>
<li><code>Point</code> = The point to which to align the bounding box of the object.</li>
</ul>
<p>Usage:</p>
<pre>
object {
MyObj
Align_Trans(MyObj, x, Pt) //Align right side of object to be
//coplanar with Pt
Align_Trans(MyObj,-y, Pt) //Align bottom of object to be
// coplanar with Pt
}
</pre>
<p><code>vtransform(Vect, Trans)</code> and <code>vinv_transform(Vect, Trans)</code>: The <code>vtransform()</code> macro takes a transformation (rotate, scale, translate, etc...) and a point, and returns the result of applying the transformation to the point. The <code>vinv_transform()</code> macro is similar, but applies the inverse of the transform, in effect <em>undoing</em> the transformation. You can combine transformations by enclosing them in a transform block.</p>
<p>Parameters:</p>
<ul>
<li><code>Vect</code> = The vector to which to apply the transformation.</li>
<li><code>Trans</code> = The transformation to apply to Vect.</li>
</ul>
<p><code>Spline_Trans(Spline, Time, SkyVector, ForeSight, Banking)</code>: This macro aligns an object to a spline for a given time value. The Z axis of the object will point in the forward direction of the spline and the Y axis of the object will point upwards.</p>
<p>Parameters:</p>
<ul>
<li><code>Spline</code> = The spline that the object is aligned to.</li>
<li><code>Time</code> = The time value to feed to the spline, for example clock.</li>
<li><code>Sky</code> = The vector that is upwards in your scene, usually y.</li>
<li><code>Foresight</code> = A positive value that controls how much in advance the object will turn and bank. Values close to 0 will give precise results, while higher values give smoother results. It will not affect parsing speed, so just find the value that looks best.</li>
<li><code>Banking</code> = How much the object tilts when turning. The amount of tilting is equally much controlled by the ForeSight value.</li>
</ul>
<p>Usage:</p>
<pre>
object {MyObj Spline_Trans(MySpline, clock, y, 0.1, 0.5)}
</pre></div>
<a name="r3_4_9_1_30"></a>
<div class="content-level-h5" contains="Woods.inc" id="r3_4_9_1_30">
<h5>3.4.9.1.30 Woods.inc</h5>
<p>The file woods.inc contains predefined wood textures and pigments.</p>
<p>The pigments are prefixed with P_, and do not have color_maps, allowing you to specify a color map from woodmaps.inc or create your own. There are two groups, "A" and "B": the A series is designed to work better on the bottom texture layer, and the
B series is designed for the upper layers, with semitransparent color maps. The pigments with the same number were designed to work well together, but you do not necessarily have to use them that way.</p>
<p>The textures are prefixed with T_, and are ready to use. They are designed with the major axis of the woodgrain <em>cylinder</em> aligned along the Z axis. With the exception of the few of the textures which have a small amount of rotation built-in, the textures will exhibit a very straight grain pattern unless you apply a small amount of x-axis rotation to them (generally 2 to 4 degrees seems to work well).</p>
<p>Pigments:</p>
<dl>
<dt><code>P_WoodGrain1A, ..., P_WoodGrainA</code></dt>
<dt><code>P_WoodGrain1B, ..., P_WoodGrainB</code></dt>
</dl>
<p>Textures:</p>
<dl>
<dt><code>T_Wood1</code></dt>
<dd>Natural oak (light)</dd>
<dt><code>T_Wood2</code></dt>
<dd>Dark brown </dd>
<dt><code>T_Wood3</code></dt>
<dd>Bleached oak (white)</dd>
<dt><code>T_Wood4</code></dt>
<dd>Mahogany (purplish-red)</dd>
<dt><code>T_Wood5</code></dt>
<dd>Dark yellow with reddish overgrain</dd>
<dt><code>T_Wood6</code></dt>
<dd>Cocabola (red)</dd>
<dt><code>T_Wood7</code></dt>
<dd>Yellow pine (ragged grain)</dd>
<dt><code>T_Wood8</code></dt>
<dd>Dark brown. Walnut? </dd>
<dt><code>T_Wood9</code></dt>
<dd>Yellowish-brown burl (heavily turbulated)</dd>
<dt><code>T_Wood10</code></dt>
<dd>Soft pine (light yellow, smooth grain)</dd>
<dt><code>T_Wood11</code></dt>
<dd>Spruce (yellowish, very straight, fine grain)</dd>
<dt><code>T_Wood12</code></dt>
<dd>Another very dark brown. Walnut-stained pine, perhaps?</dd>
<dt><code>T_Wood13</code></dt>
<dd>Very straight grained, whitish</dd>
<dt><code>T_Wood14</code></dt>
<dd>Red, rough grain</dd>
<dt><code>T_Wood15</code></dt>
<dd>Medium brown</dd>
<dt><code>T_Wood16</code></dt>
<dd>Medium brown</dd>
<dt><code>T_Wood17</code></dt>
<dd>Medium brown</dd>
<dt><code>T_Wood18</code></dt>
<dd>Orange</dd>
<dt><code>T_Wood19, ..., T_Wood30</code></dt>
<dd>Golden Oak.</dd>
<dt><code>T_Wood31</code></dt>
<dd>A light tan wood - heavily grained (variable coloration)</dd>
<dt><code>T_Wood32</code></dt>
<dd>A rich dark reddish wood, like rosewood, with smooth-flowing grain</dd>
<dt><code>T_Wood33</code></dt>
<dd>Similar to T_WoodB, but brighter</dd>
<dt><code>T_Wood34</code></dt>
<dd>Reddish-orange, large, smooth grain.</dd>
<dt><code>T_Wood35</code></dt>
<dd>Orangish, with a grain more like a veneer than a plank</dd>
</dl></div>
<a name="r3_4_9_1_31"></a>
<div class="content-level-h5" contains="Woodmaps.inc" id="r3_4_9_1_31">
<h5>3.4.9.1.31 Woodmaps.inc</h5>
<p>The file woodmaps.inc contains color_maps designed for use in wood textures. The M_WoodXA maps are intended to be used in the first layer of a multilayer texture, but can be used in single-layer textures. The M_WoodXB maps contain transparent areas, and are intended to be used in upper texture layers.</p>
<p>Color maps:</p>
<dl>
<dt><code>M_Wood1A, ..., M_Wood19A</code></dt>
<dt><code>M_Wood1B, ..., M_Wood19B</code></dt>
</dl></div>
<a name="r3_4_9_2"></a>
<div class="content-level-h4" contains="Old Files" id="r3_4_9_2">
<h4>3.4.9.2 Old Files</h4>
<p>These files could be considered either <em>obsolete</em> or <em>deprecated</em>. They have been included for <em>legacy</em> reasons.</p></div>
<a name="r3_4_9_2_1"></a>
<div class="content-level-h5" contains="Glass_old.inc" id="r3_4_9_2_1">
<h5>3.4.9.2.1 Glass_old.inc</h5>
<p>This file contains glass textures for POV-Ray versions 3.1 and earlier.
These textures do not take advantage of the new features introduced with POV-Ray 3.5 and are
included for backwards compatability, you will get better results with the
materials in glass.inc.</p>
<p class="Note"><strong>Note:</strong> As of version 3.7 the definitions in <code>glass_old.inc</code> have been <code><a href="r3_3.html#r3_3_2_2_5">deprecated</a></code>. To suppress warnings generated from using these textures you should consider converting them to materials.</p>
<p>Using the following example:</p>
<pre>texture {T_Glass4} interior {I_Glass caustics 1}</pre>
<p>should be rewritten as:</p>
<pre>
material {
texture {
pigment { color rgbf <0.98, 1.0, 0.99, 0.75> }
finish { F_Glass4 }
}
interior { I_Glass caustics 1 }
}
</pre>
</div>
<a name="r3_4_9_2_1_1"></a>
<div class="content-level-h6" contains="Glass finishes" id="r3_4_9_2_1_1">
<h6>3.4.9.2.1.1 Glass finishes</h6>
<p><code>F_Glass1, ..., F_Glass4</code></p>
</div>
<a name="r3_4_9_2_1_2"></a>
<div class="content-level-h6" contains="Glass textures" id="r3_4_9_2_1_2">
<h6>3.4.9.2.1.2 Glass textures</h6>
<dl>
<dt><code>T_Glass1</code></dt>
<dd>Simple clear glass.</dd>
<dt><code>T_Glass2</code></dt>
<dd>More like an acrylic plastic.</dd>
<dt><code>T_Glass3</code></dt>
<dd>An excellent lead crystal glass.</dd>
<dt><code>T_Glass4</code></dt>
<dt><code>T_Old_Glass</code></dt>
<dt><code>T_Winebottle_Glass</code></dt>
<dt><code>T_Beerbottle_Glass</code></dt>
<dt><code>T_Ruby_Glass</code></dt>
<dt><code>T_Green_Glass</code></dt>
<dt><code>T_Dark_Green_Glass</code></dt>
<dt><code>T_Yellow_Glass</code></dt>
<dt><code>T_Orange_Glass</code></dt>
<dd>Orange/amber glass.</dd>
<dt><code>T_Vicksbottle_Glass</code></dt>
</dl></div>
<a name="r3_4_9_2_2"></a>
<div class="content-level-h5" contains="Shapes_old.inc" id="r3_4_9_2_2">
<h5>3.4.9.2.2 Shapes_old.inc</h5>
<dl>
<dt><code>Ellipsoid, Sphere</code></dt>
<dd>Unit-radius sphere at the origin.</dd>
<dt><code>Cylinder_X, Cylinder_Y, Cylinder_Z</code></dt>
<dd>Infinite cylinders.</dd>
<dt><code>QCone_X, QCone_Y, QCone_Z</code></dt>
<dd>Infinite cones.</dd>
<dt><code>Cone_X, Cone_Y, Cone_Z</code></dt>
<dd>Closed capped cones: unit-radius at -1 and 0 radius at +1 along each axis.</dd>
<dt><code>Plane_YZ, Plane_XZ, Plane_XY</code></dt>
<dd>Infinite planes passing through the origin.</dd>
<dt><code>Paraboloid_X, Paraboloid_Y, Paraboloid_Z</code></dt>
<dd>y^2 + z^2 - x = 0</dd>
<dt><code>Hyperboloid, Hyperboloid_Y</code></dt>
<dd>y - x^2 + z^2 = 0</dd>
<dt><code>UnitBox, Cube</code></dt>
<dd>A cube 2 units on each side, centered on the origin.</dd>
<dt><code>Disk_X, Disk_Y, Disk_Z</code></dt>
<dd><em>Capped</em> cylinders, with a radius of 1 unit and a length of 2 units, centered on the origin.</dd>
</dl></div>
<a name="r3_4_9_2_3"></a>
<div class="content-level-h5" contains="Stage1.inc" id="r3_4_9_2_3">
<h5>3.4.9.2.3 Stage1.inc</h5>
<p>This file simply contains a camera, a light_source, and a ground plane, and includes colors.inc, textures.inc, and shapes.inc.</p></div>
<a name="r3_4_9_2_4"></a>
<div class="content-level-h5" contains="Stdcam.inc" id="r3_4_9_2_4">
<h5>3.4.9.2.4 Stdcam.inc</h5>
<p>This file simply contains a camera, a light_source, and a ground plane.</p></div>
<a name="r3_4_9_2_5"></a>
<div class="content-level-h5" contains="Stones1.inc" id="r3_4_9_2_5">
<h5>3.4.9.2.5 Stones1.inc</h5>
<dl>
<dt><code>T_Grnt0</code></dt>
<dd>Gray/Tan with Rose.</dd>
<dt><code>T_Grnt1</code></dt>
<dd>Creamy Whites with Yellow & Light Gray.</dd>
<dt><code>T_Grnt2</code></dt>
<dd>Deep Cream with Light Rose, Yellow, Orchid, & Tan.</dd>
<dt><code>T_Grnt3</code></dt>
<dd>Warm tans olive & light rose with cream.</dd>
<dt><code>T_Grnt4</code></dt>
<dd>Orchid, Sand & Mauve.</dd>
<dt><code>T_Grnt5</code></dt>
<dd>Medium Mauve Med.Rose & Deep Cream.</dd>
<dt><code>T_Grnt6</code></dt>
<dd>Med. Orchid, Olive & Dark Tan <em>mud pie</em>.</dd>
<dt><code>T_Grnt7</code></dt>
<dd>Dark Orchid, Olive & Dark Putty.</dd>
<dt><code>T_Grnt8</code></dt>
<dd>Rose & Light Cream Yellows</dd>
<dt><code>T_Grnt9</code></dt>
<dd>Light Steely Grays</dd>
<dt><code>T_Grnt10</code></dt>
<dd>Gray Creams & Lavender Tans</dd>
<dt><code>T_Grnt11</code></dt>
<dd>Creams & Grays Kahki</dd>
<dt><code>T_Grnt12</code></dt>
<dd>Tan Cream & Red Rose</dd>
<dt><code>T_Grnt13</code></dt>
<dd>Cream Rose Orange</dd>
<dt><code>T_Grnt14</code></dt>
<dd>Cream Rose & Light Moss w/Light Violet</dd>
<dt><code>T_Grnt15</code></dt>
<dd>Black with subtle chroma</dd>
<dt><code>T_Grnt16</code></dt>
<dd>White Cream & Peach</dd>
<dt><code>T_Grnt17</code></dt>
<dd>Bug Juice & Green</dd>
<dt><code>T_Grnt18</code></dt>
<dd>Rose & Creamy Yellow</dd>
<dt><code>T_Grnt19</code></dt>
<dd>Gray Marble with White feather Viens</dd>
<dt><code>T_Grnt20</code></dt>
<dd>White Marble with Gray feather Viens</dd>
<dt><code>T_Grnt21</code></dt>
<dd>Green Jade</dd>
<dt><code>T_Grnt22</code></dt>
<dd>Clear with White feather Viens (has some transparency)</dd>
<dt><code>T_Grnt23</code></dt>
<dd>Light Tan to Mauve</dd>
<dt><code>T_Grnt24</code></dt>
<dd>Light Grays</dd>
<dt><code>T_Grnt25</code></dt>
<dd>Moss Greens & Tan</dd>
<dt><code>T_Grnt26</code></dt>
<dd>Salmon with thin Green Viens</dd>
<dt><code>T_Grnt27</code></dt>
<dd>Dark Green & Browns</dd>
<dt><code>T_Grnt28</code></dt>
<dd>Red Swirl</dd>
<dt><code>T_Grnt29</code></dt>
<dd>White, Tan, w/ thin Red Viens</dd>
</dl>
<dl>
<dt><code>T_Grnt0a</code></dt>
<dd>Translucent T_Grnt0</dd>
<dt><code>T_Grnt1a</code></dt>
<dd>Translucent T_Grnt1</dd>
<dt><code>T_Grnt2a</code></dt>
<dd>Translucent T_Grnt2</dd>
<dt><code>T_Grnt3a</code></dt>
<dd>Translucent T_Grnt3</dd>
<dt><code>T_Grnt4a</code></dt>
<dd>Translucent T_Grnt4</dd>
<dt><code>T_Grnt5a</code></dt>
<dd>Translucent T_Grnt5</dd>
<dt><code>T_Grnt6a</code></dt>
<dd>Translucent T_Grnt6</dd>
<dt><code>T_Grnt7a</code></dt>
<dd>Translucent T_Grnt7</dd>
<dt><code>T_Grnt8a</code></dt>
<dd>Aqua Tints</dd>
<dt><code>T_Grnt9a</code></dt>
<dd>Transmit Creams With Cracks</dd>
<dt><code>T_Grnt10a</code></dt>
<dd>Transmit Cream Rose & light yellow</dd>
<dt><code>T_Grnt11a</code></dt>
<dd>Transmit Light Grays</dd>
<dt><code>T_Grnt12a</code></dt>
<dd>Transmit Creams & Tans</dd>
<dt><code>T_Grnt13a</code></dt>
<dd>Transmit Creams & Grays</dd>
<dt><code>T_Grnt14a</code></dt>
<dd>Cream Rose & light moss</dd>
<dt><code>T_Grnt15a</code></dt>
<dd>Transmit Sand & light Orange</dd>
<dt><code>T_Grnt16a</code></dt>
<dd>Cream Rose & light moss (again?)</dd>
<dt><code>T_Grnt17a</code></dt>
<dd>???</dd>
<dt><code>T_Grnt18a</code></dt>
<dd>???</dd>
<dt><code>T_Grnt19a</code></dt>
<dd>Gray Marble with White feather Viens with Transmit</dd>
<dt><code>T_Grnt20a</code></dt>
<dd>White Feather Viens</dd>
<dt><code>T_Grnt21a</code></dt>
<dd>Thin White Feather Viens</dd>
<dt><code>T_Grnt22a</code></dt>
<dd>???</dd>
<dt><code>T_Grnt23a</code></dt>
<dd>Transparent Green Moss</dd>
<dt><code>T_Grnt24a</code></dt>
<dd>???</dd>
</dl>
<dl>
<dt><code>T_Crack1</code></dt>
<dd>T_Crack & Red Overtint</dd>
<dt><code>T_Crack2</code></dt>
<dd>Translucent Dark T_Cracks</dd>
<dt><code>T_Crack3</code></dt>
<dd>Overtint Green w/ Black T_Cracks</dd>
<dt><code>T_Crack4</code></dt>
<dd>Overtint w/ White T_Crack</dd>
</dl>
<p>The StoneXX textures are the complete textures, ready to use.</p>
<dl>
<dt><code>T_Stone1</code></dt>
<dd>Deep Rose & Green Marble with large White Swirls</dd>
<dt><code>T_Stone2</code></dt>
<dd>Light Greenish Tan Marble with Agate style veining</dd>
<dt><code>T_Stone3</code></dt>
<dd>Rose & Yellow Marble with fog white veining</dd>
<dt><code>T_Stone4</code></dt>
<dd>Tan Marble with Rose patches</dd>
<dt><code>T_Stone5</code></dt>
<dd>White Cream Marble with Pink veining</dd>
<dt><code>T_Stone6</code></dt>
<dd>Rose & Yellow Cream Marble</dd>
<dt><code>T_Stone7</code></dt>
<dd>Light Coffee Marble with darker patches</dd>
<dt><code>T_Stone8</code></dt>
<dd>Gray Granite with white patches</dd>
<dt><code>T_Stone9</code></dt>
<dd>White & Light Blue Marble with light violets</dd>
<dt><code>T_Stone10</code></dt>
<dd>Dark Brown & Tan swirl Granite with gray undertones</dd>
<dt><code>T_Stone11</code></dt>
<dd>Rose & White Marble with dark tan swirl</dd>
<dt><code>T_Stone12</code></dt>
<dd>White & Pinkish Tan Marble</dd>
<dt><code>T_Stone13</code></dt>
<dd>Medium Gray Blue Marble</dd>
<dt><code>T_Stone14</code></dt>
<dd>Tan & Olive Marble with gray white veins</dd>
<dt><code>T_Stone15</code></dt>
<dd>Deep Gray Marble with white veining</dd>
<dt><code>T_Stone16</code></dt>
<dd>Peach & Yellow Marble with white veining</dd>
<dt><code>T_Stone17</code></dt>
<dd>White Marble with gray veining</dd>
<dt><code>T_Stone18</code></dt>
<dd>Green Jade with white veining</dd>
<dt><code>T_Stone19</code></dt>
<dd>Peach Granite with white patches & green trim</dd>
<dt><code>T_Stone20</code></dt>
<dd>Brown & Olive Marble with white veining</dd>
<dt><code>T_Stone21</code></dt>
<dd>Red Marble with gray & white veining</dd>
<dt><code>T_Stone22</code></dt>
<dd>Dark Tan Marble with gray & white veining</dd>
<dt><code>T_Stone23</code></dt>
<dd>Peach & Cream Marble with orange veining</dd>
<dt><code>T_Stone24</code></dt>
<dd>Green & Tan Moss Marble</dd>
</dl></div>
<a name="r3_4_9_2_6"></a>
<div class="content-level-h5" contains="Stones2.inc" id="r3_4_9_2_6">
<h5>3.4.9.2.6 Stones2.inc</h5>
<p><code>T_Stone25, ..., T_Stone44</code>
</p></div>
<a name="r3_4_9_3"></a>
<div class="content-level-h4" contains="Other Files" id="r3_4_9_3">
<h4>3.4.9.3 Other Files</h4>
<p>There are various other files in the include files collection. For example font files, color maps, and images for use in height fields or image maps.</p></div>
<a name="r3_4_9_3_1"></a>
<div class="content-level-h5" contains="Font Files" id="r3_4_9_3_1">
<h5>3.4.9.3.1 Font Files</h5>
<p>The fonts cyrvetic.ttf and timrom.ttf were donated to the POV-Team by their creator, Ted Harrison (CompuServe:70220,344) and were built using his FontLab for Windows by SoftUnion, Ltd. of St. Petersburg, Russia.</p>
<p>The font crystal.ttf was donated courtesy of Jerry Fitzpatrick, Red Mountain Corporation, redmtn [at] ix.netcom.com</p>
<p>The font povlogo.ttf is created by Fabien Mosen and based on the POV-Ray logo design by Chris Colefax.</p>
<dl>
<dt><code>crystal.ttf</code></dt>
<dd>A fixed space programmer's font.</dd>
<dt><code>cyrvetic.ttf</code></dt>
<dd>A proportional spaces sans-serif font.</dd>
<dt><code>timrom.ttf</code></dt>
<dd>A proportional spaces serif font.</dd>
<dt><code>povlogo.ttf</code></dt>
<dd>Only contains the POV-Ray logo.</dd>
</dl>
<p class="Note"><strong>Note:</strong> In version 3.7 these fonts were <em>built-in</em> to the application. See the <code><a href="r3_4.html#r3_4_5_1_16">text</a></code> object for more details.</p></div>
<a name="r3_4_9_3_2"></a>
<div class="content-level-h5" contains="Color Map Files" id="r3_4_9_3_2">
<h5>3.4.9.3.2 Color Map Files</h5>
<p>These are 255-color color_maps, and are in individual files because of their size.</p>
<dl>
<dt><code>ash.map</code></dt>
<dt><code>benediti.map</code></dt>
<dt><code>bubinga.map</code></dt>
<dt><code>cedar.map</code></dt>
<dt><code>marbteal.map</code></dt>
<dt><code>orngwood.map</code></dt>
<dt><code>pinkmarb.map</code></dt>
<dt><code>rdgranit.map</code></dt>
<dt><code>teak.map</code></dt>
<dt><code>whiteash.map</code></dt>
</dl></div>
<a name="r3_4_9_3_3"></a>
<div class="content-level-h5" contains="Image Files" id="r3_4_9_3_3">
<h5>3.4.9.3.3 Image Files</h5>
<dl>
<dt><code>bumpmap_.png</code></dt>
<dd>A color mandelbrot fractal image, presumably intended for use as a bumpmap.</dd>
<dt><code>fract003.png</code></dt>
<dd>Some kind of fractal landscape, with color for blue water, brown land, and white peaks.</dd>
<dt><code>maze.png</code></dt>
<dd>A maze.</dd>
<dt><code>mtmand.pot</code></dt>
<dd>A grayscale mandelbrot fractal.</dd>
<dt><code>mtmandj.png</code></dt>
<dd>A 2D color julia fractal.</dd>
<dt><code>plasma2.png, plasma3.png</code></dt>
<dd><em>Plasma fractal</em> images, mainly useful for landscape height fields. The file plasma3.png
is a smoother version of plasma2.png, plasma1.png does not exist.</dd>
<dt><code>povmap.png</code></dt>
<dd>The text "Persistance of Vision" in green on a blue background, framed in black and red.</dd>
<dt><code>test.png</code></dt>
<dd>A <em>test image</em>, the image is divided into 4 areas of different colors (magenta, yellow,
cyan, red) with black text on them, and the text "POV-Ray" is centered on the image in white.</dd>
<dt><code>spiral.df3</code></dt>
<dd>A 3D bitmap density file. A spiral, <em>galaxy</em> shape.</dd>
</dl></div>
</div>
</div>
</body>
</html>
|
