POV-Wiki - User contributions [en]

User:Wfpokorny/DensityFile/arraycoupleddf3s

2019-08-19T20:11:40Z

Wfpokorny: Eliminated pasted copy of the arraycoupleddf3s.inc file. Invalid even for POV-Ray parsing for who knows how long.

The include file arraycoupleddf3s.inc defines several macros useful for working with df3 files. Supposing it might be merged into arrays.inc given the df3 write macro is already in that include file?

'''Note.''' Found in August 2019 the version of the include file pasted into this web page wouldn't even parse. The version did not match that in the branch and unsure how long it was corrupted. This page updated to point to the github branch file directly. For me adding links to the wiki has been broken for a long time due the captcha mechanism not working. You'll have to cut and paste from the text below yourself to get to the include file.

The current include file can be found on github at:

<pre>
https://github.com/wfpokorny/povray/blob/feature/newDensityPatternInterpolations/distribution/include/arraycoupleddf3s.inc
</pre>

User:Wfpokorny

2018-06-11T13:17:42Z

Wfpokorny: Updating branches perhaps useful to others.

=The Playpen=

A bit of documentation for items currently in my POV-Ray playpen.

==Git Branches on github==

I'm maintaining my POV-Ray patches as un-merged github branches to make it easier for me to keep them current
with the POV-Ray master branch. In my own space I occasionally create my own version of POV-Ray which includes
just the branches/patches of mine and others that I want.

Pointers to active branches follow with the thought some might be generally useful to others in rolling
their own versions of POV-Ray. There usually additional branches on github not documented herein.

===Fix Polynomial Solver Accuracy===
Started as a rework of the polysolve / sturm chain solver, but now includes solver tangled fixes for blobs as well as updates to the more general common solver mechanisms and invocations. NOTE! Work is in progress....

See newsgroup thread: (Unable to include link due wiki captcha being broken)

<pre>git pull https://github.com/wfpokorny/povray.git fix/polynomialsolverAccuracy</pre>

===New soft_object and hard_object Patterns===

See newsgroup thread: (Unable to include link due wiki captcha being broken)

<pre>git pull https://github.com/wfpokorny/povray.git feature/soft_objectAndhard_objectPatterns</pre>

===Better Text Object Performance===
Especially with longer text strings and inside tests. A big help if using text objects with the soft_object and hard_object patterns.

<pre>git pull https://github.com/wfpokorny/povray.git update/TrueType_BetterPerformance</pre>

===Density File Pattern Updates===
A three pronged effort to improve .df3 density file pattern support.
<ol>
<li>Improved user documentation.
<li>Additional array coupled df3 creation and read support. Write support exists.
<li>Fixes and extensions for the density file pattern.
</ol>

See: [[User:Wfpokorny/DensityFile| Density File Pattern - proposed documentation updates.]]

<pre>git pull https://github.com/wfpokorny/povray.git feature/newDensityPatternInterpolations</pre>

===Addition black_hole warp type(s)===
The black_hole warp in master today has just type 0 support so the type is not really documented though the parser picks it up. Further the default sucking black_hole is clamped in movement and it sometimes reaches outside the black_hole range making for interesting effects I've used, but certainly confusing results for any novice. This patch adds a type 1 version of the black_hole warp which duplicates exactly the pushing/inverted form of type 0, but for the sucking form it implements a form more like what folks would expect. The default with this patch is still type 0 so type 1 needs to be specified to use the new type.

See newsgroup thread: (Unable to include link due wiki captcha being broken)

<pre>git pull https://github.com/wfpokorny/povray.git feature/newBlack_holeTypes</pre>

===Non-portable 32 bit DF3 write capability===
Pull request for this rejected as not portable - and I admit I don't understand the particulars. The feature works for me on linux though and I find it useful so I maintain it for my use.

<pre>git pull https://github.com/wfpokorny/povray.git feature/nonPortable32bitDF3Write</pre>

===Both image_map and pigment_map support in density block===
Lets one use both image_map and pigment_map in density{} as a way to quickly get full color density/media.

See newsgroup thread: (Unable to include link due wiki captcha being broken)

<pre>git pull https://github.com/wfpokorny/povray.git feature/pigment_map_wDensity</pre>

===Unix file and console column wrap control by environment variable===
Enabling control of the wrapping via environment variables of
POVRAY_CONSOLE_COLUMNS for the console and POVRAY_TEXTSTREAM_COLUMNS
for files and console.

Note. There is an active pull req #117 approaching this issue in another way.

<pre>git pull https://github.com/wfpokorny/povray.git feature/unixConsoleFileColumnWrapControl</pre>

===Fix. Rejected parser check for subsurface crash/non-function issue #122===
Missing or mis-placed subsurface definition in global block can cause crash or give the indication the
subsurface feature is working when it is not. I run with this parser hack as protection pending
a more complete fix.

<pre>git pull https://github.com/wfpokorny/povray.git fix/subsurfaceCrash_Issue122_FS306</pre>

==How to merge branches into a custom version of POV-Ray==
Given you've already installed git and have an active local fork of POV-Ray master branches can be merged on linux with:

<pre>
git checkout master
git branch povraySpecial
git checkout povraySpecial
git pull https://github.com/wfpokorny/povray.git fix/unixSimpleDirectMediaLayerMessages
... Usual prebuild.sh, configure and make ...
</pre>

==Incomplete section==

[[User:Wfpokorny/HowTo| How to get sub page...]]

User:Wfpokorny/DensityFile/Bowl

2018-01-04T18:46:30Z

Wfpokorny: Changed 3.7.1 reference to 3.8.

[[Image:Df3_StringsToDF3.png|center|frame|Density_file as isosurace lathe where base df3 created from array of strings.]]

Df3 is created on the fly and represents the bowl profile to be rotated about y. Image on the left is the raw df3 as created via Fnct02a. Image on the right is of the bowl via Fnct02b. 

The scene file in total is:

<pre>
#version 3.8;
global_settings {
assumed_gamma 1
ambient_light srgb <1,1,1>
noise_generator 3
}

#include "arrays.inc" // For ARRAYS_WriteDF3()
#include "arraycoupleddf3s.inc" // Array coupled df3 macros & functions.

#declare AryStrs = array[25][1]
#declare AryStrs[0][0] = "-------------------------------------2------------";
#declare AryStrs[1][0] = "------------------------------------3-------------";
#declare AryStrs[2][0] = "-----------------------------------2--------------";
#declare AryStrs[3][0] = "----------------------------------2---------------";
#declare AryStrs[4][0] = "---------------------------------2----------------";
#declare AryStrs[5][0] = "--------------------------------3-----------------";
#declare AryStrs[6][0] = "-------------------------------4------------------";
#declare AryStrs[7][0] = "-------------------------------5------------------";
#declare AryStrs[8][0] = "------------------------------6-------------------";
#declare AryStrs[9][0] = "-----------------------------5--------------------";
#declare AryStrs[10][0] = "----------------------------6---------------------";
#declare AryStrs[11][0] = "----------------------------6---------------------";
#declare AryStrs[12][0] = "----------------------------6---------------------";
#declare AryStrs[13][0] = "----------------------------6---------------------";
#declare AryStrs[14][0] = "---------------------------7----------------------";
#declare AryStrs[15][0] = "--------------------------7-----------------------";
#declare AryStrs[16][0] = "-------------------------7------------------------";
#declare AryStrs[17][0] = "------------------------7-------------------------";
#declare AryStrs[18][0] = "-----------------------7--------------------------";
#declare AryStrs[19][0] = "-------------------6666---------------------------";
#declare AryStrs[20][0] = "------------------7-------------------------------";
#declare AryStrs[21][0] = "-----------------7--------------------------------";
#declare AryStrs[22][0] = "----------------7---------------------------------";
#declare AryStrs[23][0] = "---------------7----------------------------------";
#declare AryStrs[24][0] = "666666666666666-----------------------------------";
//
// <---------------------- 50 ---------------------->

ConvertArrayOfStringsToDF3(AryStrs,"StringsToDF3.df3",8,5,1)

// #error "Stop before render"

#declare Color_2 = srgbft <0.65,0.65,0.65,0,0>;
#declare Color_3 = srgbft <0.8,0.8,0.8,0,0>;
#declare ColorMap_CloudyGraySky2 = color_map {
[ 0 Color_2 ]
[ 1 Color_3 ]
}
#declare Pigment_CloudyGraySky2 = pigment {
bozo sine_wave frequency 3.33 turbulence 1.0
color_map { ColorMap_CloudyGraySky2 }
}
#declare Sky_Sphere00 = sky_sphere {
pigment { Pigment_CloudyGraySky2 }
emission rgb <1,1,1>
}
#declare Camera00 = camera {
perspective
location <2.7,2.7,-2.701>
sky <0,1,0>
angle 35
right x*(image_width/image_height)
look_at <0,0,0>
}
#declare White = srgbft <1,1,1,0,0>;
#declare Light00 = light_source {
<50,150,-250>, White
}
#declare Fnct00 = function {
pattern { density_file df3 "StringsToDF3.df3" interpolate 5
// warp { turbulence 0.02 octaves 6 omega 0.23 lambda 6 }
translate -0.5
}
}
#declare Fnct02a = function (x,y,z) {
0.025-Fnct00(x,y,z)
}
#declare Fnct02b = function (x,y,z) {
0.025-Fnct00(sqrt((x*x)+(z*z)),y,z/5)
}
#declare BrownOchre = srgb <0.7216,0.3059,0.1569>;
#declare Iso00 = isosurface {
function { Fnct02a(x,y,z) }
contained_by { box { -0.5,0.5 } }
threshold 0
accuracy 0.0005
max_gradient 6
all_intersections
pigment { color BrownOchre }
finish { phong 0.9 }
}
#declare Object00 = object {
Iso00
scale <3.3,0.7,3.3>
}

//---
sky_sphere { Sky_Sphere00 }
camera { Camera00 }
object { Object00 }
light_source { Light00 }
</pre>

User:Wfpokorny/DensityFile/FunctionToDF3

2018-01-04T18:45:44Z

Wfpokorny: Changed 3.7.1 reference to 3.8.

[[Image:Df3_FunctionToDF3.png|center|frame|Density_file as isosurface where df3 created by macro from a defined function or object.]]

Converting functions or objects via functions and the object pattern into df3s. The complete scene file follows:

<pre>
#version 3.8;
global_settings {
assumed_gamma 1
ambient_light srgb <1,1,1>
noise_generator 3
}

#include "arrays.inc" // For ARRAYS_WriteDF3()
#include "arraycoupleddf3s.inc" // Array coupled df3 macros & functions.

#include "functions.inc"

//--- Can turn objects into df3 via ConvertFunctionToDF3 as follows
// #declare Sphere00 = sphere { 0.5,0.2 }
// #declare Fnct00 = function { pattern { object { Sphere00 } } }
// ConvertFunctionToDF3(50,50,50,0.0,0.5,0.9,1.1,Fnct00,"FunctionToDF3.df3",8,0)

#declare Fnct00 = function (x,y,z) { f_sphere(x-0.5,y-0.5,z-0.5,0.2) }

ConvertFunctionToDF3(50,50,50,0.0,0.5,-9e10,0.0,Fnct00,"FunctionToDF3.df3",8,0)

// #error "Stop before render if just creating df3 for future work"

#declare Color_2 = srgbft <0.65,0.65,0.65,0,0>;
#declare Color_3 = srgbft <0.8,0.8,0.8,0,0>;
#declare ColorMap_CloudyGraySky2 = color_map {
[ 0 Color_2 ]
[ 1 Color_3 ]
}
#declare Pigment_CloudyGraySky2 = pigment {
bozo sine_wave frequency 3.33 turbulence 1.0
color_map { ColorMap_CloudyGraySky2 }
}
#declare Sky_Sphere00 = sky_sphere {
pigment { Pigment_CloudyGraySky2 }
emission rgb <1,1,1>
}
#declare Camera00 = camera {
perspective
location <2.7,2.7,-2.701>
sky <0,1,0>
angle 35
right x*(image_width/image_height)
look_at <0,0,0>
}
#declare White = srgbft <1,1,1,0,0>;
#declare Light00 = light_source {
<50,150,-250>, White
}

#declare Fnct01 = function {
pattern { density_file df3 "FunctionToDF3.df3" interpolate 3 }
}
#declare Fnct02 = function (x,y,z) {
0.025-Fnct01(x,y,z)
}
#declare Neptune = srgb <0.4863,0.7176,0.7333>;
#declare Iso00 = isosurface {
function { Fnct02(x,y,z) }
contained_by { box { 0.2+1e-6,0.8-1e-6 } }
threshold 0
accuracy 0.0005
max_gradient 6
all_intersections
pigment { color Neptune }
finish { phong 0.9 }
}
#declare Object00 = object {
Iso00
translate -0.5
scale 2.2
}

//---
sky_sphere { Sky_Sphere00 }
camera { Camera00 }
object { Object00 }
light_source { Light00 }
</pre>

User:Wfpokorny/DensityFile/TubulenceWarpsExamples

2018-01-04T18:45:07Z

Wfpokorny: Changed 3.7.1 reference to 3.8.

[[Image:Df3_TurbulenceWarps.png|center|frame|Density_file as isosurface with various turbulence warps applied.]]

Complete pov example file for the 6 images above :

<pre>
#version 3.8;
global_settings {
assumed_gamma 1
ambient_light srgb <1,1,1>
noise_generator 3
}
//------ First create the df3 with 5 deep, 0.0, side padding.
#include "arrays.inc"
#declare maxZ=30;
#declare maxY=30;
#declare maxX=30;
#declare Ary=array[maxX][maxY][maxZ]
#declare midX=int(maxX/2);
#declare midY=int(maxY/2);
#declare midZ=int(maxZ/2);
#declare padMaxX=maxX-6; // Start padded at 5 end padMaxX
#declare padMaxY=maxY-6;
#declare padMaxZ=maxZ-6;
//-- First initialize all voxels to 0.0
#for (Z,0,maxZ-1)
#for (Y,0,maxY-1)
#for (X,0,maxX-1)
#declare Ary[X][Y][Z]=0.0;
#end
#end
#end
//-- Create some crossing axis
#for (X,5,padMaxX)
#declare Ary[X][midY][midZ]=0.95;
#end
#for (Y,5,padMaxY)
#declare Ary[midX][Y][midZ]=0.95;
#end
#for (Z,5,padMaxZ)
#declare Ary[midX][midY][Z]=0.95;
#end
#declare Df3FileName="TurbulenceWarps.df3";
ARRAYS_WriteDF3(Ary,Df3FileName,8)
//---

#declare Color_2 = srgbft <0.65,0.65,0.65,0,0>;
#declare Color_3 = srgbft <0.8,0.8,0.8,0,0>;
#declare ColorMap_CloudyGraySky2 = color_map {
[ 0 Color_2 ]
[ 1 Color_3 ]
}
#declare Pigment_CloudyGraySky2 = pigment {
bozo sine_wave frequency 3.33 turbulence 1.0
color_map { ColorMap_CloudyGraySky2 }
}
#declare Sky_Sphere00 = sky_sphere {
pigment { Pigment_CloudyGraySky2 }
emission rgb <1,1,1>
}
#declare Camera00 = camera {
perspective
location <2.1,2.1,-2.101>
sky <0,1,0>
angle 35
right x*(image_width/image_height)
look_at <0,0,0>
}
#declare White = srgbft <1,1,1,0,0>;
#declare Light00 = light_source { <250,250,-250>, White }

#include "functions.inc"
#declare Fnct00 = function {
pattern { density_file df3 "TurbulenceWarps.df3" interpolate 5
// // 0
// warp { turbulence 0.02 octaves 6 omega 0.33 lambda 6 } // 1
// warp { turbulence 0.05 octaves 6 omega 0.44 lambda 5 } // 2
// warp { turbulence -0.22 octaves 3 omega 3.0 lambda 2.7 } // 3
// warp { turbulence 0.20 octaves 6 omega 0.99 lambda 5 } // 4
// warp { turbulence 0.07 octaves 8 omega 0.99 lambda 7 } // 5
}
}
#declare Fnct01 = function (x,y,z) {
0.025-Fnct00(x,y,z)
}
#declare BaryteGreen = srgb <0.6157,0.7686,0.3725>;
#declare Iso00 = isosurface {
function { Fnct01(x,y,z) }
contained_by { box { -0.2+1e-6,1.2-1e-6 } }
threshold 0
accuracy 0.0005
max_gradient 6 // 12 needed for warp 3
all_intersections
texture {
pigment { color BaryteGreen }
finish { ambient <0.03,0.02,0.0> diffuse 0.8,0.4 phong 0.7 }
}
}
#declare Object00 = object {
Iso00
translate -0.5
scale 1.7
}

//---
sky_sphere { Sky_Sphere00 }
camera { Camera00 }
light_source { Light00 }
object { Object00 }
</pre>

User:Wfpokorny/DensityFile/BlackHoleFlower

2018-01-04T18:44:26Z

Wfpokorny: Changed 3.7.1 reference to 3.8.

[[Image:Df3_BlackHoleFlower.png|center|frame|Density_file as isosurface flower via black_hole warps and interpolation 3.]]

Interpolation 3 for some bumps/veins. The full scene description file:

<pre>
#version 3.8;
global_settings {
assumed_gamma 1
ambient_light srgb <1,1,1>
noise_generator 3
}
//------ First create the df3 with 5 deep, 0.0, side padding.
#include "arrays.inc"
#declare maxZ=30;
#declare maxY=30;
#declare maxX=30;
#declare Ary=array[maxX][maxY][maxZ]
#declare midX=int(maxX/2);
#declare midY=int(maxY/2);
#declare midZ=int(maxZ/2);
#declare padMaxX=maxX-6; // Start padded at 5 end padMaxX
#declare padMaxY=maxY-6;
#declare padMaxZ=maxZ-6;
//-- First initialize all voxels to 0.0
#for (Z,0,maxZ-1)
#for (Y,0,maxY-1)
#for (X,0,maxX-1)
#declare Ary[X][Y][Z]=0.0;
#end
#end
#end
//-- Create box at mid y
#for (Z,5,padMaxZ)
#for (X,5,padMaxX)
#declare Ary[X][midY][Z]=0.55;
#end
#end
#declare Df3FileName="BlackHoleFlower.df3";
ARRAYS_WriteDF3(Ary,Df3FileName,8)
//---

#declare Color_2 = srgbft <0.65,0.65,0.65,0,0>;
#declare Color_3 = srgbft <0.8,0.8,0.8,0,0>;
#declare ColorMap_CloudyGraySky2 = color_map {
[ 0 Color_2 ]
[ 1 Color_3 ]
}
#declare Pigment_CloudyGraySky2 = pigment {
bozo sine_wave frequency 3.33 turbulence 1.0
color_map { ColorMap_CloudyGraySky2 }
}
#declare Sky_Sphere00 = sky_sphere {
pigment { Pigment_CloudyGraySky2 }
emission rgb <1,1,1>
}
#declare Camera00 = camera {
perspective
location <2.1,2.1,-2.101>
sky <0,1,0>
angle 35
right x*(image_width/image_height)
look_at <0,0,0>
}
#declare White = srgbft <1,1,1,0,0>;
#declare Light00 = light_source { <150,250,-250>, White }

#declare CtrVec = <0.5,0.5,0.5>;
#macro PetalWarps ()
warp { black_hole CtrVec,0.50 falloff 2.0 strength 2.0 }
warp { black_hole CtrVec,0.40 falloff 2.0 strength 2.0 }
warp { black_hole CtrVec,0.30 falloff 2.0 strength 1.7 }
warp { black_hole CtrVec,0.25 falloff 2.0 strength 1.5 inverse }
warp { turbulence 0.015 octaves 6 omega 0.3 lambda 6 }
#end
#macro PetalTurbWarps ()
warp { turbulence <0.02,0.05,0.02> }
#end

#declare Fnct00a = function {
pattern { density_file df3 "BlackHoleFlower.df3" interpolate 3
PetalWarps()
PetalTurbWarps()
}
}
#declare Fnct00b = function {
pattern { density_file df3 "BlackHoleFlower.df3" interpolate 3
PetalWarps()
PetalTurbWarps()
translate -0.5
rotate y*30
translate 0.5
translate <0,-0.01,0>
}
}
#declare Fnct00c = function {
pattern { density_file df3 "BlackHoleFlower.df3" interpolate 3
PetalWarps()
PetalTurbWarps()
translate -0.5
rotate y*60
translate 0.5
translate <0,-0.02,0>
}
}
#declare Fnct00 = function (x,y,z) { max(Fnct00a(x,y,z),Fnct00b(x,y,z),Fnct00c(x,y,z)) }
#declare Fnct01 = function (x,y,z) { 0.025-Fnct00(x,y,z) }
#declare Iso00 = isosurface {
function { Fnct01(x,y,z) }
contained_by { box { <0,0.3,0>,<1,0.7,1> } }
threshold 0
accuracy 0.0005
max_gradient 6
all_intersections
}
#declare Object00 = object {
Iso00
texture {
pigment {
spherical
scale 0.5
translate 0.5
PetalTurbWarps()
color_map {
[ 0.00 srgb <1,0.4784,0.3804> ]
[ 0.37 srgb <0.9333,0.8667,0.7647> ]
[ 0.70 srgb <0.9882,0.9608,0.8078> ]
[ 0.77 srgb <0.8098,0.69412,0.08235> ]
[ 0.79 srgb <0.1098,0.09412,0.08235> ]
[ 1.00 srgb <0.7216,0.3059,0.1569>*0.8 ]
}
}
finish { ambient <0.03,0.02,0.0> diffuse 0.8,0.4 }
}
translate -CtrVec
scale 2
}

//---
sky_sphere { Sky_Sphere00 }
camera { Camera00 }
light_source { Light00 }
object { Object00 rotate <-22,0,-11> }
</pre>

User:Wfpokorny/DensityFile/BlackHoleLatheGreebling

2018-01-04T18:43:46Z

Wfpokorny: Changed 3.7.1 reference to 3.8.

[[Image:Df3_GreebleDf3IsoDiag.png|center|frame|Density_file as isosurface with lathe greebling via black_hole warps.]]

On the left a density_file isosurface based upon a df3 where the unit cube diagonals all have values of 0.9. On the right is the greeble-lathe effect accomplished with three black_hole warps repeating at various diagonal distances. The code in full is:

<pre>
#version 3.8;
global_settings {
assumed_gamma 1
ambient_light srgb <1,1,1>
noise_generator 3
}
//------ First create the df3 with 5 deep, 0.0, side padding.
#include "arrays.inc"
#declare maxZ=30;
#declare maxY=30;
#declare maxX=30;
#declare Ary=array[maxX][maxY][maxZ]
#declare midX=int(maxX/2);
#declare midY=int(maxY/2);
#declare midZ=int(maxZ/2);
#declare padMaxX=maxX-6; // Start padded at 5 end padMaxX
#declare padMaxY=maxY-6;
#declare padMaxZ=maxZ-6;
//-- First initialize all voxels to 0.0
#for (Z,0,maxZ-1)
#for (Y,0,maxY-1)
#for (X,0,maxX-1)
#declare Ary[X][Y][Z]=0.0;
#end
#end
#end
//-- Set the cube diagonal values to 0.9 inside outer padding.
#for (X,5,padMaxX)
#declare Ary[X][X][X]=0.9;
#end
#declare Df3FileName="GreebleDf3IsoDiag.df3";
ARRAYS_WriteDF3(Ary,Df3FileName,8)
//---

#declare Color_2 = srgbft <0.65,0.65,0.65,0,0>;
#declare Color_3 = srgbft <0.8,0.8,0.8,0,0>;
#declare ColorMap_CloudyGraySky2 = color_map {
[ 0 Color_2 ]
[ 1 Color_3 ]
}
#declare Pigment_CloudyGraySky2 = pigment {
bozo sine_wave frequency 3.33 turbulence 1.0
color_map { ColorMap_CloudyGraySky2 }
}
#declare Sky_Sphere00 = sky_sphere {
pigment { Pigment_CloudyGraySky2 }
emission rgb <1,1,1>
}
#declare Camera00 = camera {
perspective
location <2.1,2.1,-2.101>
sky <0,1,0>
angle 35
right x*(image_width/image_height)
look_at <0,0,0>
}
#declare White = srgbft <1,1,1,0,0>;
#declare Light00 = light_source { <250,250,-250>, White }

#declare Fnct00 = function {
pattern { density_file df3 "GreebleDf3IsoDiag.df3" interpolate 5
warp { black_hole <0,0,0>,0.17 falloff 3.0 strength 5 repeat <0.34,0.34,0.34> }
warp { black_hole <0,0,0>,0.15 falloff 3.0 strength 5 repeat <0.30,0.30,0.30> }
warp { black_hole <0,0,0>,0.13 falloff 3.0 strength 5 repeat <0.26,0.26,0.26> }
}
}
#declare Fnct01 = function (x,y,z) {
0.025-Fnct00(x,y,z)
}
#declare Magenta = srgbft <1,0,1,0,0>;
#declare Iso00 = isosurface {
function { Fnct01(x,y,z) }
contained_by { box { -0.0+1e-6,1.0-1e-6 } }
threshold 0
accuracy 0.0005
max_gradient 6
all_intersections
texture {
pigment { color Magenta }
finish { ambient 0 }
}
}
#declare Object00 = object {
Iso00
translate -0.5
scale 1.7
}

//---
sky_sphere { Sky_Sphere00 }
camera { Camera00 }
light_source { Light00 }
object { Object00 }
</pre>

'''Note.''' The reason the above code works - that contraction stops on different radii and doesn't collapse to nothing - is the black_hole point movement is limited to the original distance from the point to the hole's center.

User:Wfpokorny/DensityFile/FillingVolumeWithShapes

2018-01-04T18:42:40Z

Wfpokorny: Removed or changed 3.7.1 references.

[[Image:Df3_FunctionToDF3Shapes.png|center|frame|Density_file as isosurace of many individually textured shapes filling another shape.]]

This example exploits the fact, with the Github branch patch updates, individual shapes and textures per voxel can be created with the density_file pattern. Using interpolation 3 or 4 at small values gives a base spherical density function in each voxel. Interpolation 0 at the same df3 size can be used to directly control the map value for pigment, texture, etc. So long as the same warps are applied to both the map value df3 and the df3 forming shapes, the map values follow - no matter how drastic the warps/turbulence.

The code below also creates the container df3 by converting a function defining a spheroid. Commented code is shown for an alternate method using a standard sphere to define the volume via a function based upon the object pattern.

The code also uses 'poly_wave 3.0' to reduce blobbing as a way to get more individualized or separated spheres. See additional commented code for various other options.

The complete scene file is:

<pre>
#version 3.8;
global_settings {
assumed_gamma 1
ambient_light srgb <1,1,1>
noise_generator 3
// radiosity {
// pretrace_start 0.08
// pretrace_end 2/max(image_width,image_height)
// count 250
// nearest_count 10
// error_bound 0.45
// recursion_limit 1
// low_error_factor 0.5
// gray_threshold 0
// minimum_reuse 0.015
// brightness 1.0
// adc_bailout 0.01/2
// always_sample off
// normal on
// }
}

#include "arrays.inc" // For ARRAYS_WriteDF3()
#include "arraycoupleddf3s.inc" // Array coupled df3 macros & functions.

//------ First create the df3 for colormap.
#include "arrays.inc"
#declare maxZ=30;
#declare maxY=30;
#declare maxX=30;
#declare Ary=array[maxX][maxY][maxZ]
#declare midX=int(maxX/2);
#declare midY=int(maxY/2);
#declare midZ=int(maxZ/2);
#declare padMaxX=maxX-6; // Start padded at 5 end padMaxX
#declare padMaxY=maxY-6;
#declare padMaxZ=maxZ-6;
//-- First initialize all voxels to 0.0
#for (Z,0,maxZ-1)
#for (Y,0,maxY-1)
#for (X,0,maxX-1)
#declare Ary[X][Y][Z]=0.0;
#end
#end
#end
//-- Create box at mid y
#local tmpSeed=seed(now*24*60*60);
#for (Z,5,padMaxZ)
#for (Y,5,padMaxY)
#for (X,5,padMaxX)
#declare Ary[X][Y][Z]=rand(tmpSeed);
#end
#end
#end
#declare Df3FileName="FunctionToDF3ShapesMap.df3";
ARRAYS_WriteDF3(Ary,Df3FileName,8)
//---

#include "functions.inc"

//--- Can turn objects into df3 via ConvertFunctionToDF3 as follows
// #declare Sphere00 = sphere { 0.5,0.2 }
// #declare Fnct00 = function { pattern { object { Sphere00 } } }
// ConvertFunctionToDF3(30,30,30,0.0,0.2,0.9,1.1,Fnct00,"FunctionToDF3Shapes.df3",8,0)

#declare Fnct00 = function (x,y,z) { f_sphere((x-0.5)*1.5,y-0.5,(z-0.5)*2,0.33) }

ConvertFunctionToDF3(30,30,30,0.0,0.2,-9e10,0.0,Fnct00,"FunctionToDF3Shapes.df3",8,0)

// #error "Stop before render in just creating df3 for future work"

#declare Color_2 = srgbft <0.65,0.65,0.65,0,0>;
#declare Color_3 = srgbft <0.8,0.8,0.8,0,0>;
#declare ColorMap_CloudyGraySky2 = color_map {
[ 0 Color_2 ]
[ 1 Color_3 ]
}
#declare Pigment_CloudyGraySky2 = pigment {
bozo sine_wave frequency 3.33 turbulence 1.0
color_map { ColorMap_CloudyGraySky2 }
}
#declare Sky_Sphere00 = sky_sphere {
pigment { Pigment_CloudyGraySky2 }
emission rgb <1,1,1>
}
#declare Camera00 = camera {
perspective
location <2.7,2.7,-2.701>
sky <0,1,0>
angle 35
right x*(image_width/image_height)
look_at <0,0,0>
}
#declare White = srgbft <1,1,1,0,0>;
#declare Light00 = light_source {
<50,150,-250>, White
}
#macro TheWarps00 ()
scale 2.7
warp { turbulence <0.027,0.025,0.026> octaves 9 omega 0.95 lambda 1.414 } // Sphere of stones?
scale 1/2.7
// warp { turbulence -0.02 octaves 5 omega 1.33 lambda 1.7 } //--- This cool
// warp { turbulence 0.01 octaves 3 omega 1.2 lambda 9.0 } //--- Sphere-ish
// warp { turbulence 0.03 octaves 4 omega 1.70 lambda 3.3 } //
#end

#declare Fnct01 = function {
pattern { density_file df3 "FunctionToDF3Shapes.df3" interpolate 3
poly_wave 3.0
TheWarps00()
}
}
#declare Fnct02 = function (x,y,z) {
//0.025-(Fnct01(x,y,z)-f_granite(x*20,y*20,z*20)*0.05) // Needs higher max gradient
0.025-Fnct01(x,y,z)
}
#declare Iso00 = isosurface {
function { Fnct02(x,y,z) }
contained_by { box { <0.2,0.1,0.30>,<0.8,0.9,0.70> } }
threshold 0
accuracy 0.001
max_gradient 6
all_intersections
}
#declare Fnct03 = function {
pattern { density_file df3 "FunctionToDF3ShapesMap.df3" interpolate 0
TheWarps00()
}
}
#declare Object00 = object {
Iso00
texture {
pigment {
function { Fnct03(x,y,z) }
color_map {
[ 0.00 srgb <1,0.4784,0.3804> ]
[ 0.37 srgb <0.9333,0.8667,0.7647> ]
[ 0.70 srgb <0.9882,0.9608,0.8078> ]
[ 0.77 srgb <0.8098,0.69412,0.08235> ]
[ 0.79 srgb <0.1098,0.09412,0.08235> ]
[ 1.00 srgb <0.7216,0.3059,0.1569>*0.8 ]
}
}
finish { phong 0.7 phong_size 77 }
}
translate -0.5
scale 4.0
}

//---
sky_sphere { Sky_Sphere00 }
camera { Camera00 }
object { Object00 }
light_source { Light00 }
<pre>

User:Wfpokorny/DensityFile

2018-01-04T18:38:57Z

Wfpokorny: Updates to better reflect current POV-Ray versions and not presume patch adoption version.

[[Category:Patterns]]
{{#indexentry:density_file, keyword}}
{{#indexentry:density_file, pattern}}
{{#indexentry:keyword, density_file}}
{{#indexentry:pattern, density_file}}
{{#indexentry:df3, density_file}}
{{#indexentry:keyword, df3}}
{{#indexentry:interpolate, density_file}}
{{#indexentry:keyword, interpolate}}
{{#indexentry:df3}}

'''Note!''' While the following density_file (.df3) pattern documentation is often valid with respect to the current 3.7 and 3.8 forms of df3 value interpolation, it is written as if the additional interpolation modes proposed in https://github.com/wfpokorny/povray/tree/feature/newDensityPatternInterpolations have been adopted.

'''Note!''' After some discussion it's was decided the original 'assist' interpolation modes 6-12 would be dropped for methods already supported. However, newer texturing assist modes 9 & 10 are currently in play in the patch and not well documented.

= Density File Pattern =

The density_file 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 the df3 format. This pattern was originally created for use with halo or media, but it may be used anywhere a pattern may be used. The core syntax whether used in a normal, pattern or pigment block is:

<pre>density_file df3 [file name] [interpolate Type]</pre>

where the file name would be placed in double quotes and the interpolation type would be an integer value 0 through 5. For example:

<pre>density_file df3 "star.df3" 1</pre>

The general forms for each of the normal, pattern and pigment blocks are:

<pre>
normal {
density_file df3 [filename] [,Bump_Size]
[interpolate Type]
[NORMAL_MODIFIERS...]
}
</pre>

where Bump_Size is an optional float value,

<pre>
pattern {
density_file df3 [filename] [interpolate Type]
[PATTERN_MODIFIERS...]
}
</pre>

and

<pre>
pigment {
density_file df3 [filename] [interpolate Type]
[PIGMENT_MODIFIERS...]
}
</pre>

== The df3 file format ==

The df3 format consists of a 6 byte header of three 16-bit, unsigned integers with high order bytes first (big-endian order). These three values give the x,y,z size of the data in voxels.

The header is followed by x*y*z unsigned, big-endian encoded, integers with resolutions of 8, 16 or 32 bits. The resolution of the data is determined by the size of the df3 file. That is, if the file - minus the header - is twice as long as an 8 bit file, it is taken to contain 16 bit data. If it is four times as long, it is taken to contain 32 bit data.

== How the density_file pattern works ==

The density pattern occupies the unit cube <0,0,0> to <1,1,1> regardless of the x, y, z dimensions in voxels. It remains at 0.0 for all areas beyond the unit cube. Data values in the ranges of 0 to 255 (8 bit/1 byte), 0 to 65535 (16 bit/2 bytes) and 0 to 4294967295 (32 bit/4 bytes), are scaled by the various interpolation methods to a float value in the range 0.0 to 1.0. The larger 2 byte and 4 byte depths providing better resolution.

=== Interpolation options. ===
There are currently 6 data interpolation types numbered 0 through 5, with the types larger than 2 being available only with the patch. If nothing is specified via the interpolate keyword, the default is 0 which does no interpolation - meaning for a given location in the unit cube, the 0.0 to 1.0 value of the containing voxel is returned. The other interpolation methods available are:

<ol>
<li> Tri-linear. Similar to two dimensional image method, but for three dimensions.
<li> Tri-cubic. Similar to two dimensional image method.
<li> Weak exponential blobbing of defined voxels in 4x4x4 local sub regions.
<li> Moderate exponential blobbing of defined voxels in 6x6x6 local sub regions.
<li> Strong exponential blobbing of defined voxels in 8x8x8 local sub regions.
<li> NA
<li> NA
<li> NA
<li> Noisy, nearest non-zero voxel value. Texturing use.
<li> Nearest non-zero voxel value. Texturing use.
</ol>

If an interpolate value not supported is specified, the interpolation defaults to tri-cubic interpolation, 2, in POV-Ray versions 3.6 and later.

=== Exponential blobbing interpolations. ===
Exponential blobbing techniques in POV-Ray date to the introduction of isosurface objects. The method here borrows from one common technique with the form:

<pre>1/exp((function's value)*(blobbing strength))</pre>

As implemented, for each evaluated point in the unit cube, the code sums the result of the equation:

<pre>(1/exp(pow(point_to_voxel_distance,2)*(internalTuningBias/voxel_value))</pre>

for all adjacent df3 values >0 within the NxNxN sub-cube around the evaluated point. Resulting values >1 are clamped to 1.0. The larger the sub cube, the stronger the blobbing which can be accommodated.

The algorithm has been tuned so 1.0 values for each of the exponential blobbing interpolations just fit within the corresponding sub cube. The blobbing can be adjusted without the need to regenerate a df3 by using the standard pattern wave modifier poly_wave <float>. Poly_wave values >=1.0 should always work and reduce the blobbing. Values < 1.0 increase the blobbing and can cause sub cube overruns. Overruns will appear as discontinuities in the final pattern.

=== Only interpolation 0 is voxel centered in 3.8.0 and earlier releases. ===
For version 3.7.0 and 3.8, the interpolations 0 to 2 are shown below in order, left to right, as a pigment on a plane for an 11x11x11 df3 file where a single center voxel has a value of 0.5 while all others are 0.0. The red dots mark the vertices around our center voxel.

[[Image:Df3_I0thru2_370.png|center|frame|Density_file interpolations for single center voxel as a green pigment on a plane with release 3.7.0.]]

The tri-linear and tri-cubic interpolations are vertex centered without the patch resulting in a half voxel negative shift in x,y,z . This shift is perhaps of no consequence if rendering media. It does however matter if, for example, building a df3 based isosurface or when trying to control textures for media for any formed objects using interpolation 0.

Offset tri-linear and tri-cubic results can be centered with a positive translation of one half a voxel size in x,y and z. For the 11x11x11 df3 example use:

<pre>translate <-0.5+(1/11/2),-0.5+(1/11/2),-0.5+(1/11/2)></pre>

to get the density_file pattern exactly centered upon the origin. In a function for an isosurface this adjustment to center on the origin would be something like:

<pre>FnctAdjustToCenter(x+0.5-(1/11/2),y+0.5-(1/11/2),z+0.5-(1/11/2))</pre>

=== The patch makes all interpolations voxel, and so too unit cube, centered. ===
In addition to adding density_file pattern interpolation modes, the patch centers all the interpolated results. The patch interpolations 0 to 5 are shown in order, left to right, in the following image.

[[Image:Df3_I0thru5_371.png|center|frame|Density_file interpolations for single center voxel as a green pigment on a plane.]]

'''Note.''' Backward, shifted compatibility for the older 1 & 2 methods is available by using interpolations 11 & 12, respectively.

=== Tri-linear interpolation has creases, tri-cubic interpolation wobbles/rings. ===
The following figure shows isosurfaces for interpolations 1 through 5, left to right, setting the threshold very near zero to better see the non-zero values returned. The df3 used is a 15x15x15 arrangement where an x,z box has been centered in y and through which there is a y column of >0.0 values. The values for the non-zero voxels in the top row are 0.1 and the bottom row 0.9.

The former better showing the crease effect of tri-linear interpolation, the latter, the ring of tri-cubic interpolation. The tri-cubic mode always wobbles, but the most severe artifacts can be avoided by using values not near 0.0 and 1.0 where pattern clipping occurs.

[[Image:Df3_isoBoxOnSpindle.png|center|frame|Density_file interpolations 1-5 for defined voxels arranged as box on spindle.]]

Lastly, with respect the the ringing of the tri-cubic interpolation, there are at times, additional harmonics as shown at the bottom of the following image which has been gamma adjusted to make this clear. The df3 sets only 3 voxels, here seen as the brighter green rectangles.

[[Image:Df3_TriCubic2ndRingExample.png|center|frame|Density_file second ring example with tri-cubic interpolation.]]

=== DF3 value and density_file interpolation effects on an isosurface max gradient. ===
Interpolation methods and df3 values affect the max gradient in isosurface use. For tri-linear and tri-cubic Interpolations 1 and 2, lower values result in lower gradients due the typically longer ramp from the >0 edge to the voxel value used as a threshold. With the exponential blobbing of modes 3, 4 and 5, the lower gradients happen instead at larger voxel values - lower voxel values result in small spheres with much sharper local gradients. Gradients for interpolations 0-5 tend to increase as the df3 file's voxel count increase.

Interpolations 3, 4 and 5 max values always go to 1.0 at any >0.0 voxel center, where interpolations 1 and 2 peak at the voxel's specified >0.0 value.

''Reported'' maximum gradients for df3 based isosurfaces will often be much higher than what can be used. These higher gradients occur where a ray catches the far corner or edge of the df3-function in a direction more perpendicular to the best overall local gradient. Note. This far corner, near threshold, gradient effect happens with other patterns too and can often be ignored in practice.

=== Use a buffer of five 0.0 voxels on all sides to avoid density_file edge effects. ===
While not a hard and fast rule, all the interpolations other than 0, 9 and 10, will wrap or repeat values on the sides. The general recommendation of five comes from interpolation five's need for an 8 grid range (4 per side) about any evaluated point - plus a half voxel grid for the internal vertex to voxel center correction of interpolations 1-5. Often smaller buffer amounts can be used.

Below are two images. In the first, the lower-left-forward corner of the df3 has been filled with 0.2 values with all others 0.0. In the second image the top-right-back corner of df3 file has been set to values of 0.2 with all others set to 0.0. Interpolations 0 through 5 are shown left to right in each of these two images as a pigment on an x,y plane at the df3 unit cube's z center.

[[Image:Df3_LftFrontI0Thru5.png|center|frame|(1) Density_file interpolations 0-5 with defined left, bottom, front voxels.]]

[[Image:Df3_RghtBackI0Thru5.png|center|frame|(2) Density_file interpolations 0-5 with defined right, top, back voxels.]]

All truncate sharply to 0.0 where values have been run to the unit cube sides. This abrupt change is especially inconvenient for isosurface use, but the hard edge can often be seen in other pattern uses as some artifact.

The tri-linear and tri-cubic interpolations, 1 and 2, wrap side to opposite side in the lower-left-forward side-abutted case shown in the first row. These same interpolations truncate in the rop-right-back side-abutted case shown in the second row.

The exponential blobbing of 3 through 5 all repeat - or add values - at the last voxel position at the sides. This can sometimes be compensated for by lowering the on side and in-corner values.

=== df3 file size. ===
Df3 files can get very large, very quickly given the cubed dimensions. A df3 1000x1000x1000 at 1 byte resolution will take a gigabyte of storage. It practice, aim to reduce the z dimension as much as possible letting the density_file pattern scale up to the unit cube. Later scale the unit cube dimension to the desired final size.

==== 3D isosurface extrusion of image via shallow in z, density_file pattern. ====
An example compressing the df3 in one dimension comes naturally when the density_file pattern is used for extrusion of a 2D image into 3D shape. The outline for such an extrusion is shown in the following code snippets with a resulting image. A 500x500x13 deep df3 of the red in a 2D image, at left below, is created with the following code:

<pre>
#include "arrays.inc" // For ARRAYS_WriteDF3()
#include "arraycoupleddf3s.inc" // Array coupled df3 macros & functions.

#declare ImageFileNamesAry=array[3] {
"BlackRedLettersIn.png",
"BlackRedLettersIn.png",
"BlackRedLettersIn.png"
}
// Red
ConvertImagesToDF3(500,500,0.0,1.0,<1,0,0>,0.2,1,ImageFileNamesAry,"BlackRedLetters.df3",8,5)

#error "Stopping after parse stage for df3 creation from image."
</pre>

The include file arrays.inc is already part of POV-Ray and the arraycoupleddf3s.inc file is given in the examples section and is part of the Github patch branch. Once the df3 representation of the 2D image exists, the following code is used to create the function for the isosurface text using blobbing interpolation 5.

<pre>
#declare Fnct00 = function {
pattern { density_file df3 "BlackRedLetters.df3" interpolate 5
translate -0.5 // Center about origin for isosurface
scale <1,1,1/((500+10)/(3+10))>
warp { turbulence <0.015,0.015,0> octaves 6 omega 0.43 lambda 6 }
}
}
#declare Fnct01 = function (x,y,z) {
0.025-Fnct00(x,y,z)
}
</pre>

[[Image:Df3_BlackRedLetters.png|center|frame|Density_file as isosurface extrusion of 2D image while selecting color for extrusion.]]

In the function declaration, Fnct00, the pattern is centered about the origin with a translate. The z dimension, which would otherwise render stretched, is scaled back to a desired size. The turbulence warp in x and y roughens up the 3D text sides leaving the front and back smooth. The +10 accounts for the the buffer of 0.0 values about the 3 deep, in z, df3 data.

Function Fnct01 gets used in the isosurface and the general form here works more or less universally with the density_file pattern when the isosurface threshold is 0.0. '''Note.''' While a couple of functions are required for the isosurface set up, the standard pattern modifiers do most of the work.

=== Performance of various interpolations. ===
Generally the internal pattern performance in terms of the interpolation numbers runs 0 --> 1 --> 3 --> 2 --> 4 --> 5 from fastest to slowest with a strong dependence on df3 data density, values and ultimate pattern use. As pigments all perform well. Media and isosurface use will amplify the performance differences. With respect to isosurfaces and remembering how the gradients change, it happens for larger df3 values, interpolation 5 can be the fastest because the isosurface gradients are in that case the most gradual.

=== Tip. Using frequency 0 for better performance. ===
The density_file pattern like many other patterns supports the frequency, phase and waveform modifiers. If these are not in use, some of the code which does the wave related adjustments can be bypassed by setting the frequency to 0. For example:

<pre>
#declare Fnct00 = function {
pattern { density_file df3 "test.df3" interpolate 1 frequency 0 }
}
</pre>

The performance gains are typically less than 2 percent per density_file and there is one side effect important to maps. The wave code bypassed reduces all values downward by a very small amount to keep values from actually reaching 1.0. Maps wrap back to zero at 1.0 and because users often code maps as [0-1] this wrap might lead to confusion.

The 1.0 value isn't typically an issue for isosurfaces and, if you know the df3 or other pattern as interpolated never reaches 1.0, the frequency 0 trick can be used.

== Additional examples and arraycoupleddf3s.inc ==

POV-Ray ships with one example df3 file in the include directory called spiral.df3 which is used by two sample scenes in: scenes -> textures -> patterns -> densfile.pov and scenes -> interior -> media -> galaxy.pov.

[[User:Wfpokorny/DensityFile/arraycoupleddf3s|arraycoupleddf3s.inc]]

[[User:Wfpokorny/DensityFile/WriteDF3Example|Creating a df3 file with arrays.inc's ARRAYS_WriteDF3 macro]]

[[User:Wfpokorny/DensityFile/df3XYZsizeBashExample|Simple bash script to query x, y, z ranges of an existing df3 file.]]

[[User:Wfpokorny/DensityFile/DepthMap64BitDf3RsltStoreExample|Orthogonal depth map with trace. Storing +-64 bit values in a df3 file.]]

[[User:Wfpokorny/DensityFile/BlackHoleLatheGreebling|Lathe like greebling using density_file pattern with black_hole warps.]]

[[User:Wfpokorny/DensityFile/BlackHoleFlower|Flower formed using multiple black_hole warps on df3, density_file pattern.]]

[[User:Wfpokorny/DensityFile/TubulenceWarpsExamples|Various turbulence warps applied to simple axis crossing df3.]]

[[User:Wfpokorny/DensityFile/FunctionToDF3|Converting functions and objects to df3s with FunctionToDF3 macro.]]

[[User:Wfpokorny/DensityFile/FillingVolumeWithShapes|Filling a volume with many individually textured shapes.]]

[[User:Wfpokorny/DensityFile/Bowl|Isosurace lathe where base df3 created from array of strings.]]

[[User:Wfpokorny/DensityFile/Twist|Place holder for twist example. Perhaps not worth keeping without interpolations 9,11-12?]]

HowTo:POV-Ray Feature Requests

2018-01-04T18:19:30Z

Wfpokorny: Update note related to Flyspray to Github issue migration.

We all want to see POV-Ray improved, and from time to time it may occur to us that there's a feature that we would like to see, or something we'd like to see improved. The proper place for "feature wishlists" is the bugtracking and feature-request system on [https://github.com/POV-Ray/povray/issues Github], as that's ''the'' primary place where the developers will look for them.

Note: All issues still open in our previous [http://bugs.povray.org/ FlySpray Bug Reporting System] have been ported to the new [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. Please exclusively use Github for new issues and updates to open issues.

When ''making'' feature requests, a word of advice:

Please ''do'' read [[HowTo:Make A Bug Report]] and [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively] before submitting any entries to the issue tracker, and ''do'' heed the advice presented there. By following those rules - or at least keeping them in mind as you file issues - you make life a lot easier for the people you hope to address the issues.

Some other points raised in [http://news.povray.org/povray.advanced-users/thread/%3C4c1d52c5%241%40news.povray.org%3E/] and [http://news.povray.org/povray.general/thread/%3C4c09591e%241%40news.povray.org%3E/]:

* If discussion of a feature request has resulted in a summary or conclusion that differs from the original request, a new feature request should not be made. Instead, the existing one should be changed. This implies contributing ideas to the feature request discussion, and then coming up with a single coherent idea, not leaving it at two half-finished ideas.
* Closely-related feature requests should be grouped together; e.g. requests for Windows UI enhancements with respect to the editor such as "Delete", "Reload" and "Rename" commands could reasonably be put into a single request (all at once or via editing a bug later).
* There is a feature to allow other users and/or developers to comment on bugs & feature requests on github, but this is primarily intended for providing additional information, or feedback on the current status. For proper discussions, it lacks the necessary publicity. (When was the last time anyone just browsed the github just to see if there was some interesting discussion going on in some of the entries?) The POV-Ray community is strongest in the newsgroups. That said, the problem with ''discussions'' about feature requests is that they tend to have ''no'' clear-cut result whatsoever, as they tend do be free brainstorming sessions - unless there's someone with the necessary will and authority (e.g. because he has started the discussion in the first place) "driving" the discussion to a proper conclusion (ideally by summarizing the discussion and result in a proper place). In situations like these, github excels.
* A sensible rule for opening a new feature request might then be that it must be discussed in the newsgroups first, to weed out crackpot ideas and to refine ideas by feedback from what users actually need. After discussion, the request should only be entered if a member of the POV-Ray team deems the request reasonable (note that a request should not be deemed unreasonable at this point just because it would be too much effort to implement right now).
* Excessive use/misuse of the newsgroups and github may be considered "vandalism".

HowTo:Make A Bug Report

2018-01-04T18:17:20Z

Wfpokorny: Update notes related to Flyspray to Github issue migration.

===== Reporting bugs in POV-Ray =====
Bug reports are an essential part of development, and the developers need you to let them know about programming defects in POV-Ray. However, there are a few things that you need to keep in mind when you are thinking about submitting a bug report or requesting a new feature. Please take a few moments to read this brief list of guidelines ''before'' you open a new task in our [https://github.com/POV-Ray/povray/issues Github Issue Tracking System].

Note: All issues still open in our previous [http://bugs.povray.org/ FlySpray Bug Reporting System] have been ported to the new [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. Please exclusively use Github for new issues and updates to open issues.

===== Guidelines for opening new tasks =====
* Take some minutes of your time and read [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html this] document, it will teach you how to report a bug correctly.
* If you're not sure it's a bug, or how to report it, chat with the folks in the [http://news.povray.org/povray.beta-test/ beta-test forum].
* We cannot accept bug reports for modified versions of POV-Ray.
* In almost all cases where a rendering bug is being reported, we require a minimal sample scene causing the bug be submitted, as well as an image showing the problem.
* Always perform a search on '''both open and closed''' 'issues' or 'tasks' before opening a new one. Your bug might already have been reported, or your feature requested.
* Use the English language in any tasks you open. Nothing will get done if we can't understand you.
* Only report one bug or request one feature per task.
* If you report a bug, and we mark it as 'requires testing', then please test it and add a comment to the task telling us how well it works.
* If a task is closed as fixed then try the [https://github.com/POV-Ray/povray/releases development version] before requesting that it be re-opened.
* If we deny your request to re-open a task, check the history/comments for our reason. If you are unsatisfied with the reason, you are welcome to discuss it in the [http://news.povray.org/ forums].
* Be polite. Remember that you got POV-Ray for free.

===== Text formatting tips =====
Github allows for a lot more formatting within task descriptions and comments. Here are a few helpful essentials:
* To quote some other comment, use the github quote feature after marking the text to be quoted.
* To make code, use the mark code feature of github after marking your code.
* Refer to github issues and pull request by number prefixed with # and github will create the link. Please refer to older Flyspray tasks by their numeric id preceded by "<tt>FS#</tt>" (e.g. <tt>FS#123</tt>) and perhaps insert the URL for as github will create the corresponding link.
* Do make use of the preview button.

===== Miscellaneous =====
* To illustrate your bug report or comment with images, test scenes or zip files, please do make use of the "attach file" functionality, rather than linking to some 3rd party image hosting site. This way the uploaded files will remain accessible as long as the github issue persists. Note when uploading scene related files the POV-Ray extensions of .pov and .inc are not supported; needing an additional .txt suffix before upload. Further .tar and .gz files are '''not''' supported as of this writing, but rather only .zip.

==See also==
*[[Knowledgebase:POV-Ray Feature Requests]]

HowTo:Contents

2017-02-16T15:42:48Z

Wfpokorny: Adding pointer to PovClipse2.

The following is a list of the currently-available and wished for 'How To' articles. If you add a new article, please list and link it here.

Note: Some of the older articles, written while 3.7.0 was being developed, are in need of update.

Please read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

Discussions about this page should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Subject Areas==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Modeling====
*[https://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Render/POV-Ray How to: Use POV-Ray with Blender]

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]
*[[HowTo:Use for loop over traditional while loop | How to: Use for loop over traditional while loop]]

====Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[http://www.buckosoft.com/povclipse2 How to use PovClipse2 : An Eclipse plugin to manage POV-Ray source]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

==== Working with POV-Ray ====
Tips to get the most out of POV-ray:
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

==POV-Ray troubleshooting==
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*Installation Troubleshooting currently via [http://news.povray.org/groups/ newsgroups].
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests | How to make a feature request]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#POV-Ray troubleshooting | POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

HowTo:Make A Bug Report

2017-01-24T13:35:11Z

Wfpokorny: Cleanup.

===== Reporting bugs in POV-Ray =====
Bug reports are an essential part of development, and the developers need you to let them know about programming defects in POV-Ray. However, there are a few things that you need to keep in mind when you are thinking about submitting a bug report or requesting a new feature. Please take a few moments to read this brief list of guidelines ''before'' you open a new task in our [https://github.com/POV-Ray/povray/issues Github Issue Tracking System].

Note: We are in the process of porting issues still open in our previous [http://bugs.povray.org/ FlySpray Bug Reporting System] to the new
[https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. During this transition it is necessary to review both systems to know if an issue has already been made known to the developers. Please open new issues in the [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. If a FlySpray issue is marked as 'tracked on github' please make further updates on github.

===== Guidelines for opening new tasks =====
* Take some minutes of your time and read [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html this] document, it will teach you how to report a bug correctly.
* If you're not sure it's a bug, or how to report it, chat with the folks in the [http://news.povray.org/povray.beta-test/ beta-test forum].
* We cannot accept bug reports for modified versions of POV-Ray.
* In almost all cases where a rendering bug is being reported, we require a minimal sample scene causing the bug be submitted, as well as an image showing the problem.
* Always perform a search on '''both open and closed''' 'issues' or 'tasks' before opening a new one. Your bug might already have been reported, or your feature requested.
* Use the English language in any tasks you open. Nothing will get done if we can't understand you.
* Only report one bug or request one feature per task.
* If you report a bug, and we mark it as 'requires testing', then please test it and add a comment to the task telling us how well it works.
* If a task is closed as fixed then try the [https://github.com/POV-Ray/povray/releases development version] before requesting that it be re-opened.
* If we deny your request to re-open a task, check the history/comments for our reason. If you are unsatisfied with the reason, you are welcome to discuss it in the [http://news.povray.org/ forums].
* Be polite. Remember that you got POV-Ray for free.

===== Text formatting tips =====
Github allows for a lot more formatting within task descriptions and comments. Here are a few helpful essentials:
* To quote some other comment, use the github quote feature after marking the text to be quoted.
* To make code, use the mark code feature of github after marking your code.
* Refer to github issues and pull request by number prefixed with # and github will create the link. Please refer to older Flyspray tasks not yet ported by their numeric id preceded by "<tt>FS#</tt>" (e.g. <tt>FS#123</tt>) and perhaps insert the URL for as github will create the corresponding link.
* Do make use of the preview button.

===== Miscellaneous =====
* To illustrate your bug report or comment with images, test scenes or zip files, please do make use of the "attach file" functionality, rather than linking to some 3rd party image hosting site. This way the uploaded files will remain accessible as long as the github issue persists. Note when uploading scene related files the POV-Ray extensions of .pov and .inc are not supported; needing an additional .txt suffix before upload. Further .tar and .gz files are '''not''' supported as of this writing, but rather only .zip.

==See also==
*[[Knowledgebase:POV-Ray Feature Requests]]

HowTo:Contents

2017-01-23T15:53:25Z

Wfpokorny: HowTo rearrangement & simplification given efforts stalled relative to original plan.

The following is a list of the currently-available and wished for 'How To' articles. If you add a new article, please list and link it here.

Note: Some of the older articles, written while 3.7.0 was being developed, are in need of update.

Please read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

Discussions about this page should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Subject Areas==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Modeling====
*[https://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Render/POV-Ray How to: Use POV-Ray with Blender]

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]
*[[HowTo:Use for loop over traditional while loop | How to: Use for loop over traditional while loop]]

====Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

==== Working with POV-Ray ====
Tips to get the most out of POV-ray:
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

==POV-Ray troubleshooting==
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*Installation Troubleshooting currently via [http://news.povray.org/groups/ newsgroups].
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests | How to make a feature request]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#POV-Ray troubleshooting | POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

HowTo:Contents

2017-01-23T12:07:29Z

Wfpokorny: Pointed installation troubleshooting to newsgroups given no article exists.

The following is a list of the currently-available 'How To' articles. If you add a new article, please list it here.

Please also read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

==Suggestions==

It would be handy if some users co-operated in working out a 'wishlist' of articles and a hierarchy for them, and then created the links to the empty pages from this page.

Discussions should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Completed articles==

*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]
*[[HowTo:Use for loop over traditional while loop | How to: Use for loop over traditional while loop]]
*[https://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Render/POV-Ray How to: Use POV-Ray with Blender]

==Work-in-Progress Articles==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use rainbow | How to: Use rainbow]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

==== Working with POV-Ray ====
Platform-specific tips to get the most out of POV-ray:
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

=====POV-Ray for Mac OS / Mac OS X=====

=====POV-Ray for Unix=====

====Building Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#General POV-Ray troubleshooting | General POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

==General POV-Ray troubleshooting==
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*Installation Troubleshooting currently via [http://news.povray.org/groups/ newsgroups].
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests | How to make a feature request]]

HowTo:Contents

2017-01-23T11:50:55Z

Wfpokorny: Slight change in header arrangement.

The following is a list of the currently-available 'How To' articles. If you add a new article, please list it here.

Please also read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

==Suggestions==

It would be handy if some users co-operated in working out a 'wishlist' of articles and a hierarchy for them, and then created the links to the empty pages from this page.

Discussions should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Completed articles==

*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]
*[[HowTo:Use for loop over traditional while loop | How to: Use for loop over traditional while loop]]
*[https://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Render/POV-Ray How to: Use POV-Ray with Blender]

==Work-in-Progress Articles==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use rainbow | How to: Use rainbow]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

==== Working with POV-Ray ====
Platform-specific tips to get the most out of POV-ray:
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

=====POV-Ray for Mac OS / Mac OS X=====

=====POV-Ray for Unix=====

====Building Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#General POV-Ray troubleshooting | General POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

==General POV-Ray troubleshooting==
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*[[Installation#Troubleshooting | Installation Troubleshooting]]
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests | How to make a feature request]]

HowTo:Contents

2017-01-23T11:45:47Z

Wfpokorny: Added link to Blender POV-Ray page.

The following is a list of the currently-available 'How To' articles. If you add a new article, please list it here.

Please also read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

==Suggestions==

It would be handy if some users co-operated in working out a 'wishlist' of articles and a hierarchy for them, and then created the links to the empty pages from this page.

Discussions should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Completed articles==

*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]
*[[HowTo:Use for loop over traditional while loop | How to: Use for loop over traditional while loop]]
*[https://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Render/POV-Ray How to: Use POV-Ray with Blender]

==Work-in-Progress Articles==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use rainbow | How to: Use rainbow]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

==== Working with POV-Ray ====
Platform-specific tips to get the most out of POV-ray:
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

=====POV-Ray for Mac OS / Mac OS X=====

=====POV-Ray for Unix=====

====Building Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#General POV-Ray troubleshooting | General POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

====General POV-Ray troubleshooting====
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*[[Installation#Troubleshooting | Installation Troubleshooting]]
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests|How to make a feature request]]

HowTo:Known Issues

2017-01-23T11:39:22Z

Wfpokorny: Adding known issue for assumed_gamma 1 and .gray operation.

===Known Issues===
Quick list of general known issues with the version 3.7, the 3.7.1 pre-release and the current master branch(3.7.2):
<ol>
<li>Unix users. Due to problems with X11 window libraries, some special command line parameters, such as -geometry, are not available. These were previously enabled via X11 itself. However, a preview display can still be enabled if building from source and the optional [http://www.libsdl.org SDL Simple Directmedia Layer (V1.2)] development library is available to link against.</li>
<li>While utf-8 support is available in scene files, there are still issues with file names using non-ASCII characters. Meaning a user running in utf-8 or equivalent must take care to use only ASCII characters for all scene related file and directory names. See: [https://github.com/POV-Ray/povray/issues/152 github issue 152]</li>
<li>Agressive Anti-Aliasing (AA) usually addresses bright and dark speckles sometimes seen with media where rays glance - tangentially - to a mathematical surface in a way which confuses interval determination for sampling. Further, while using 'sturm on' is usually a help, it tends to make such media speckling worse. Search the newsgroups for more detail.</li>
<li>The internal .gray | .grey, color to gray conversion is not adjusted for assumed_gamma as the current conversion was set up for other than the recommended assumed_gamma 1 setting. See the newsgroup discussion at: [http://news.povray.org/povray.general/thread/%3C58800d3c%241%40news.povray.org%3E/ "Assumed_gamma and .gray"]. The following macro, as suggested in the news thread, can be used by assumed_gamma 1 users:

<pre>
#macro DotGray (Color)
#local C = color Color;
(0.2126 * C.red + 0.7152 * C.green + 0.0722 * C.blue) // ITU-R BT.709
#end
</pre>

</li>
</ol>

The developer's issue tracking can be found at [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]

User:Wfpokorny/DensityFile

2017-01-19T13:36:09Z

Wfpokorny: Playpen status updates.

[[Category:Patterns]]
{{#indexentry:density_file, keyword}}
{{#indexentry:density_file, pattern}}
{{#indexentry:keyword, density_file}}
{{#indexentry:pattern, density_file}}
{{#indexentry:df3, density_file}}
{{#indexentry:keyword, df3}}
{{#indexentry:interpolate, density_file}}
{{#indexentry:keyword, interpolate}}
{{#indexentry:df3}}

'''Note!''' While the following density_file (.df3) pattern documentation is often valid with respect to the current 3.7.0 forms of df3 value interpolation, it is written as if the additional interpolation modes proposed in https://github.com/wfpokorny/povray/tree/feature/newDensityPatternInterpolations have been adopted.

'''Note!''' After some discussion it's been decided the 'assist' interpolation modes 6-12 will be dropped for methods already supported. Wiki edits are mostly complete to match and the source code has been updated.

= Density File Pattern =

The density_file 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 the df3 format. This pattern was originally created for use with halo or media, but it may be used anywhere a pattern may be used. The core syntax whether used in a normal, pattern or pigment block is:

<pre>density_file df3 [file name] [interpolate Type]</pre>

where the file name would be placed in double quotes and the interpolation type would be an integer value 0 through 5. For example:

<pre>density_file df3 "star.df3" 1</pre>

The general forms for each of the normal, pattern and pigment blocks are:

<pre>
normal {
density_file df3 [filename] [,Bump_Size]
[interpolate Type]
[NORMAL_MODIFIERS...]
}
</pre>

where Bump_Size is an optional float value,

<pre>
pattern {
density_file df3 [filename] [interpolate Type]
[PATTERN_MODIFIERS...]
}
</pre>

and

<pre>
pigment {
density_file df3 [filename] [interpolate Type]
[PIGMENT_MODIFIERS...]
}
</pre>

== The df3 file format ==

The df3 format consists of a 6 byte header of three 16-bit, unsigned integers with high order bytes first (big-endian order). These three values give the x,y,z size of the data in voxels.

The header is followed by x*y*z unsigned, big-endian encoded, integers with resolutions of 8, 16 or 32 bits. The resolution of the data is determined by the size of the df3 file. That is, if the file - minus the header - is twice as long as an 8 bit file, it is taken to contain 16 bit data. If it is four times as long, it is taken to contain 32 bit data.

== How the density_file pattern works ==

The density pattern occupies the unit cube <0,0,0> to <1,1,1> regardless of the x, y, z dimensions in voxels. It remains at 0.0 for all areas beyond the unit cube. Data values in the ranges of 0 to 255 (8 bit/1 byte), 0 to 65535 (16 bit/2 bytes) and 0 to 4294967295 (32 bit/4 bytes), are scaled by the various interpolation methods to a float value in the range 0.0 to 1.0. The larger 2 byte and 4 byte depths providing better resolution.

=== Interpolation options. ===
There are currently 6 data interpolation types numbered 0 through 5, with the types larger than 2 being available only in releases 3.7.1 and later. If nothing is specified via the interpolate keyword, the default is 0 which does no interpolation - meaning for a given location in the unit cube, the 0.0 to 1.0 value of the containing voxel is returned. The other interpolation methods available are:

<ol>
<li> Tri-linear. Similar to two dimensional image method, but for three dimensions.
<li> Tri-cubic. Similar to two dimensional image method.
<li> Weak exponential blobbing of defined voxels in 4x4x4 local sub regions.
<li> Moderate exponential blobbing of defined voxels in 6x6x6 local sub regions.
<li> Strong exponential blobbing of defined voxels in 8x8x8 local sub regions.
</ol>

If an interpolate value not supported is specified, the interpolation defaults to tri-cubic interpolation, 2, in POV-Ray versions 3.6 and later.

=== Exponential blobbing interpolations. ===
Exponential blobbing techniques in POV-Ray date to the introduction of isosurface objects. The method here borrows from one common technique with the form:

<pre>1/exp((function's value)*(blobbing strength))</pre>

As implemented, for each evaluated point in the unit cube, the code sums the result of the equation:

<pre>(1/exp(pow(point_to_voxel_distance,2)*(internalTuningBias/voxel_value))</pre>

for all adjacent df3 values >0 within the NxNxN sub-cube around the evaluated point. Resulting values >1 are clamped to 1.0. The larger the sub cube, the stronger the blobbing which can be accommodated.

The algorithm has been tuned so 1.0 values for each of the exponential blobbing interpolations just fit within the corresponding sub cube. The blobbing can be adjusted without the need to regenerate a df3 by using the standard pattern wave modifier poly_wave <float>. Poly_wave values >=1.0 should always work and reduce the blobbing. Values < 1.0 increase the blobbing and can cause sub cube overruns. Overruns will appear as discontinuities in the final pattern.

=== Only interpolation 0 is voxel centered in 3.7.0 and earlier releases. ===
For version 3.7.0, the interpolations 0 to 2 are shown below in order, left to right, as a pigment on a plane for an 11x11x11 df3 file where a single center voxel has a value of 0.5 while all others are 0.0. The red dots mark the vertices around our center voxel.

[[Image:Df3_I0thru2_370.png|center|frame|Density_file interpolations for single center voxel as a green pigment on a plane with release 3.7.0.]]

The tri-linear and tri-cubic interpolations are vertex centered prior to 3.7.1 resulting in a half voxel negative shift in x,y,z . This shift is perhaps of no consequence if rendering media. It does however matter if, for example, building a df3 based isosurface or when trying to control textures for media for any formed objects using interpolation 0.

Offset tri-linear and tri-cubic results can be centered with a positive translation of one half a voxel size in x,y and z. For the 11x11x11 df3 example use:

<pre>translate <-0.5+(1/11/2),-0.5+(1/11/2),-0.5+(1/11/2)></pre>

to get the density_file pattern exactly centered upon the origin. In a function for an isosurface this adjustment to center on the origin would be something like:

<pre>FnctAdjustToCenter(x+0.5-(1/11/2),y+0.5-(1/11/2),z+0.5-(1/11/2))</pre>

=== Release 3.7.1 makes all interpolations voxel, and so too unit cube, centered. ===
In addition to adding density_file pattern interpolation modes, 3.7.1 centers all the interpolated results. The 3.7.1 interpolations 0 to 5 are shown in order, left to right, in the following image.

[[Image:Df3_I0thru5_371.png|center|frame|Density_file interpolations for single center voxel as a green pigment on a plane.]]

'''Note.''' Backward, shifted compatibility for the older 1 & 2 methods is available by using interpolations 11 & 12, respectively.

=== Tri-linear interpolation has creases, tri-cubic interpolation wobbles/rings. ===
The following figure shows isosurfaces for interpolations 1 through 5, left to right, setting the threshold very near zero to better see the non-zero values returned. The df3 used is a 15x15x15 arrangement where an x,z box has been centered in y and through which there is a y column of >0.0 values. The values for the non-zero voxels in the top row are 0.1 and the bottom row 0.9.

The former better showing the crease effect of tri-linear interpolation, the latter, the ring of tri-cubic interpolation. The tri-cubic mode always wobbles, but the most severe artifacts can be avoided by using values not near 0.0 and 1.0 where pattern clipping occurs.

[[Image:Df3_isoBoxOnSpindle.png|center|frame|Density_file interpolations 1-5 for defined voxels arranged as box on spindle.]]

Lastly, with respect the the ringing of the tri-cubic interpolation, there are at times, additional harmonics as shown at the bottom of the following image which has been gamma adjusted to make this clear. The df3 sets only 3 voxels, here seen as the brighter green rectangles.

[[Image:Df3_TriCubic2ndRingExample.png|center|frame|Density_file second ring example with tri-cubic interpolation.]]

=== DF3 value and density_file interpolation effects on an isosurface max gradient. ===
Interpolation methods and df3 values affect the max gradient in isosurface use. For tri-linear and tri-cubic Interpolations 1 and 2, lower values result in lower gradients due the typically longer ramp from the >0 edge to the voxel value used as a threshold. With the exponential blobbing of modes 3, 4 and 5, the lower gradients happen instead at larger voxel values - lower voxel values result in small spheres with much sharper local gradients. Gradients for interpolations 0-5 tend to increase as the df3 file's voxel count increase.

Interpolations 3, 4 and 5 max values always go to 1.0 at any >0.0 voxel center, where interpolations 1 and 2 peak at the voxel's specified >0.0 value.

''Reported'' maximum gradients for df3 based isosurfaces will often be much higher than what can be used. These higher gradients occur where a ray catches the far corner or edge of the df3-function in a direction more perpendicular to the best overall local gradient. Note. This far corner, near threshold, gradient effect happens with other patterns too and can often be ignored in practice.

=== Use a buffer of five 0.0 voxels on all sides to avoid density_file edge effects. ===
While not a hard and fast rule, all the interpolations other than 0, and 6-12, will wrap or repeat values on the sides. The general recommendation of five comes from interpolation five's need for an 8 grid range (4 per side) about any evaluated point - plus a half voxel grid for the internal vertex to voxel center correction of interpolations 1-5. Often smaller buffer amounts can be used.

Below are two images. In the first, the lower-left-forward corner of the df3 has been filled with 0.2 values with all others 0.0. In the second image the top-right-back corner of df3 file has been set to values of 0.2 with all others set to 0.0. Interpolations 0 through 5 are shown left to right in each of these two images as a pigment on an x,y plane at the df3 unit cube's z center.

[[Image:Df3_LftFrontI0Thru5.png|center|frame|(1) Density_file interpolations 0-5 with defined left, bottom, front voxels.]]

[[Image:Df3_RghtBackI0Thru5.png|center|frame|(2) Density_file interpolations 0-5 with defined right, top, back voxels.]]

All truncate sharply to 0.0 where values have been run to the unit cube sides. This abrupt change is especially inconvenient for isosurface use, but the hard edge can often be seen in other pattern uses as some artifact.

The tri-linear and tri-cubic interpolations, 1 and 2, wrap side to opposite side in the lower-left-forward side-abutted case shown in the first row. These same interpolations truncate in the rop-right-back side-abutted case shown in the second row.

The exponential blobbing of 3 through 5 all repeat - or add values - at the last voxel position at the sides. This can sometimes be compensated for by lowering the on side and in-corner values.

=== df3 file size. ===
Df3 files can get very large, very quickly given the cubed dimensions. A df3 1000x1000x1000 at 1 byte resolution will take a gigabyte of storage. It practice, aim to reduce the z dimension as much as possible letting the density_file pattern scale up to the unit cube. Later scale the unit cube dimension to the desired final size.

==== 3D isosurface extrusion of image via shallow in z, density_file pattern. ====
An example compressing the df3 in one dimension comes naturally when the density_file pattern is used for extrusion of a 2D image into 3D shape. The outline for such an extrusion is shown in the following code snippets with a resulting image. A 500x500x13 deep df3 of the red in a 2D image, at left below, is created with the following code:

<pre>
#include "arrays.inc" // For ARRAYS_WriteDF3()
#include "arraycoupleddf3s.inc" // Array coupled df3 macros & functions.

#declare ImageFileNamesAry=array[3] {
"BlackRedLettersIn.png",
"BlackRedLettersIn.png",
"BlackRedLettersIn.png"
}
// Red
ConvertImagesToDF3(500,500,0.0,1.0,<1,0,0>,0.2,1,ImageFileNamesAry,"BlackRedLetters.df3",8,5)

#error "Stopping after parse stage for df3 creation from image."
</pre>

The include file arrays.inc is already part of POV-Ray and the arraycoupleddf3s.inc file is given in the examples section. Once the df3 representation of the 2D image exists, the following code is used to create the function for the isosurface text using blobbing interpolation 5.

<pre>
#declare Fnct00 = function {
pattern { density_file df3 "BlackRedLetters.df3" interpolate 5
translate -0.5 // Center about origin for isosurface
scale <1,1,1/((500+10)/(3+10))>
warp { turbulence <0.015,0.015,0> octaves 6 omega 0.43 lambda 6 }
}
}
#declare Fnct01 = function (x,y,z) {
0.025-Fnct00(x,y,z)
}
</pre>

[[Image:Df3_BlackRedLetters.png|center|frame|Density_file as isosurface extrusion of 2D image while selecting color for extrusion.]]

In the function declaration, Fnct00, the pattern is centered about the origin with a translate. The z dimension, which would otherwise render stretched, is scaled back to a desired size. The turbulence warp in x and y roughens up the 3D text sides leaving the front and back smooth. The +10 accounts for the the buffer of 0.0 values about the 3 deep, in z, df3 data.

Function Fnct01 gets used in the isosurface and the general form here works more or less universally with the density_file pattern when the isosurface threshold is 0.0. '''Note.''' While a couple of functions are required for the isosurface set up, the standard pattern modifiers do most of the work.

=== Performance of various interpolations. ===
Generally the internal pattern performance in terms of the interpolation numbers runs 0 --> 1 --> 3 --> 2 --> 4 --> 5 from fastest to slowest with a strong dependence on df3 data density, values and ultimate pattern use. As pigments all perform well. Media and isosurface use will amplify the performance differences. With respect to isosurfaces and remembering how the gradients change, it happens for larger df3 values, interpolation 5 can be the fastest because the isosurface gradients are in that case the most gradual.

=== Tip. Using frequency 0 for better performance. ===
The density_file pattern like many other patterns supports the frequency, phase and waveform modifiers. If these are not in use, some of the code which does the wave related adjustments can be bypassed by setting the frequency to 0. For example:

<pre>
#declare Fnct00 = function {
pattern { density_file df3 "test.df3" interpolate 1 frequency 0 }
}
</pre>

The performance gains are typically less than 2 percent per density_file and there is one side effect important to maps. The wave code bypassed reduces all values downward by a very small amount to keep values from actually reaching 1.0. Maps wrap back to zero at 1.0 and because users often code maps as [0-1] this wrap might lead to confusion.

The 1.0 value isn't typically an issue for isosurfaces and, if you know the df3 or other pattern as interpolated never reaches 1.0, the frequency 0 trick can be used.

== Additional examples and arraycoupleddf3s.inc ==

POV-Ray ships with one example df3 file in the include directory called spiral.df3 which is used by two sample scenes in: scenes -> textures -> patterns -> densfile.pov and scenes -> interior -> media -> galaxy.pov.

[[User:Wfpokorny/DensityFile/arraycoupleddf3s|arraycoupleddf3s.inc]]

[[User:Wfpokorny/DensityFile/WriteDF3Example|Creating a df3 file with arrays.inc's ARRAYS_WriteDF3 macro]]

[[User:Wfpokorny/DensityFile/df3XYZsizeBashExample|Simple bash script to query x, y, z ranges of an existing df3 file.]]

[[User:Wfpokorny/DensityFile/DepthMap64BitDf3RsltStoreExample|Orthogonal depth map with trace. Storing +-64 bit values in a df3 file.]]

[[User:Wfpokorny/DensityFile/BlackHoleLatheGreebling|Lathe like greebling using density_file pattern with black_hole warps.]]

[[User:Wfpokorny/DensityFile/BlackHoleFlower|Flower formed using multiple black_hole warps on df3, density_file pattern.]]

[[User:Wfpokorny/DensityFile/TubulenceWarpsExamples|Various turbulence warps applied to simple axis crossing df3.]]

[[User:Wfpokorny/DensityFile/FunctionToDF3|Converting functions and objects to df3s with FunctionToDF3 macro.]]

[[User:Wfpokorny/DensityFile/FillingVolumeWithShapes|Filling a volume with many individually textured shapes.]]

[[User:Wfpokorny/DensityFile/Bowl|Isosurace lathe where base df3 created from array of strings.]]

[[User:Wfpokorny/DensityFile/Twist|Place holder for twist example. Perhaps not worth keeping without interpolations 9,11-12?]]

User:Wfpokorny

2017-01-19T13:32:22Z

Wfpokorny: Playpen status updates.

=The Playpen=

A bit of documentation for items currently in my POV-Ray playpen.

==Git Branches on github==

I'm maintaining my POV-Ray patches as un-merged github branches to make it easier for me to keep them current
with the POV-Ray master branch. In my own space I occasionally create my own version of POV-Ray which includes
just the branches/patches of mine and others that I want.

Pointers to my active branches follow with the thought some might be generally useful to others in rolling
their own versions of POV-Ray.

===Tune Blob Accuracy===
This just tweaks an internal value in blob.cpp that in my testing of blobs over the past year I've found works better.
I will eventually package up all my blob test cases and open a github issue/pull request, but not there today...

<pre>git pull https://github.com/wfpokorny/povray.git tune/blob_accuracy</pre>

===Density File Pattern Updates===
A three pronged effort to improve .df3 density file pattern support.
<ol>
<li>Improved user documentation.
<li>Additional array coupled df3 creation and read support. Write support exists.
<li>Fixes and extensions for the density file pattern.
</ol>

See: [[User:Wfpokorny/DensityFile| Density File Pattern - proposed documentation updates.]]

<pre>git pull https://github.com/wfpokorny/povray.git feature/newDensityPatternInterpolations</pre>

===Addition black_hole warp type(s)===
The black_hole warp in master today has just type 0 support so the type is not really documented though the parser picks it up. Further the default sucking black_hole is clamped in movement and it sometimes reaches outside the black_hole range making for interesting effects I've used, but certainly confusing results for any novice. This patch adds a type 1 version of the black_hole warp which duplicates exactly the pushing/inverted form of type 0, but for the sucking form it implements a form more like what folks would expect. The default with this patch is still type 0 so type 1 needs to be specified to use the new type.

<pre>git pull https://github.com/wfpokorny/povray.git feature/newBlack_holeTypes</pre>

Pull request #86 on github.

===Non-portable 32 bit DF3 write capability===
Pull request for this rejected as not portable - and I admit I don't understand the particulars. The feature works for me on linux though and I find it useful so I maintain it for my use.

<pre>git pull https://github.com/wfpokorny/povray.git feature/nonPortable32bitDF3Write</pre>

===Both image_map and pigment_map support in density block===
Lets one use both image_map and pigment_map in density{} as a way to quickly get full color density/media.

<pre>git pull https://github.com/wfpokorny/povray.git feature/pigment_map_wDensity</pre>

===Unix file and console column wrap control by environment variable===
Enabling control of the wrapping via environment variables of
POVRAY_CONSOLE_COLUMNS for the console and POVRAY_TEXTSTREAM_COLUMNS
for files and console.

Note. There is an active pull req #117 approaching this issue in another way.

<pre>git pull https://github.com/wfpokorny/povray.git feature/unixConsoleFileColumnWrapControl</pre>

===Fix. Rejected parser check for subsurface crash/non-function issue #122===
Missing or mis-placed subsurface definition in global block can cause crash or give the indication the
subsurface feature is working when it is not. I run with this parser hack as protection pending
a more complete fix.

<pre>git pull https://github.com/wfpokorny/povray.git fix/subsurfaceCrash_Issue122_FS306</pre>

==How to merge branches into a custom version of POV-Ray==
Given you've already installed git and have an active local fork of POV-Ray master branches can be merged on linux with:

<pre>
git checkout master
git branch povraySpecial
git checkout povraySpecial
git pull https://github.com/wfpokorny/povray.git fix/unixSimpleDirectMediaLayerMessages
... Usual prebuild.sh, configure and make ...
</pre>

==Incomplete section==

[[User:Wfpokorny/HowTo| How to get sub page...]]

User talk:Jholsenback

2017-01-08T14:52:59Z

Wfpokorny: Removed question on potential documentation... Apparently me confused.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>{{Done}} A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency. [[Reference:Finish|See-It]]</li>
<li>{{Done}} A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions. [[Reference:User Defined Pattern|See-It]]</li>
<li>{{Done}} A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a <code>blob</code> or <code>isosurface</code> object.[[Reference:Potential Pattern|See-It]]</li>
<li>{{Done}} The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code> [[Reference:Bitmap Modifiers#The map_type Option|See-It]]</li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps. [[Reference:Crackle Pattern|See-It]]</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients. [[Reference:Color Map|See-It]] and [[Reference:Pigment Map|See-Also]]</li>
<li>{{Done}} Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism. [[Reference:Finish|See-It]]</li>
</ol>

=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>{{Done}} A new parameter <code>polarity</code> has been added to isosurfaces. [[Reference:Isosurface|See-It]]</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus. [[Reference:Torus|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>{{Done}} All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>{{Done}} The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments.
[[Reference:Declare and Local Directives|See-It]]</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>

=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>{{Done}} Light sources distance-based fading can now be set to obey an inverse-power law at all distances [[Reference:Light Source#Light Fading|See-It]]</li>
<li>{{Done}} CIE L*a*b* conversion macros have been added to colors.inc [[Reference:Colors.inc#Color_macros|See-It]]</li>
<li>{{Done}} A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard [[Reference:Colors_ral.inc|See-It]]</li>
<li>Chris says only update copyright date when file otherwise changes.</li>
<li>For a 3.7.1 release we should probably pull all the X11 related sections from the documentation. Remember seeing something about VGA / SVGA support too about which I am suspicious, but maybe this all works?
</ol>

====Changed Behavior====
=====Image Files=====
<ol>
<li>{{Done}} By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>{{Done}} The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>{{Done}} The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</li>

<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension

 The term "IFF" does not seem to be mentioned anywhere in the docs (this is an input-only format), just the keyword, which wasn't chaned. (CLi)
</li>
</ol>

=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>{{Done}} The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li>Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later

 Already documented. May need to be marked as {{Change}}. [[Reference:Strings#String_Literals|See-It]] (CLi)

</li>
</ol>

====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>{{Done}} Dithering is now fully supported for Radiance HDR output files. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Trailing whitespace in INI files no longer causes a warning. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Animation status messages now include the nominal frame number. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} POV-Ray for Windows now reports file names and line numbers of warnings. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Radiosity can now honor the <code>brilliance</code> setting of a surface. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries.</li>
<ul>
<li>[[Reference:Color Map|Color Map]]</li>
<li>[[Reference:Pigment Map|Pigment Map]]</li>
<li>[[Reference:Average Pattern|Average Pattern]]</li>
<li>[[Reference:Normal Map|Normal Map]]</li>
<li>[[Reference:Slope Map|Slope Map]]</li>
<li>[[Reference:Patterned Textures|Patterned Textures]]</li>
<li>[[Reference:Density#Density and Density Maps|Density and Density Maps]]</li>
</ul>
</li>
<li>{{Done}} The number of components per blob is no longer artificially limited. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
</ol>

====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.

===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Nothing with ovus or lemon. Add to primativ.pov perhaps?</li>
<li>Rename primativ.pov to primative.pov or delete and create individual files?</li>
<li>portfolio/allobjects.pov out of date.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 2013.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48 

===Multilinks===
Just came across a nest of multilinks on [[Reference:Language_Directives]], thought you'd like to know; would have eliminated them in passing, but since you say that triggers some performance-hogging process I won't touch them. (CLi)

User talk:Jholsenback

2017-01-08T14:10:54Z

Wfpokorny: Question on potential pattern documentation versus actual behavior.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>{{Done}} A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency. [[Reference:Finish|See-It]]</li>
<li>{{Done}} A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions. [[Reference:User Defined Pattern|See-It]]</li>
<li>{{Done}} A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a <code>blob</code> or <code>isosurface</code> object.[[Reference:Potential Pattern|See-It]]
??? Just looked at this page and I'm not remembering the threshold value as a float and polarity as a boolean, but rather visa-versa. I'll go dig - WFP.
</li>
<li>{{Done}} The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code> [[Reference:Bitmap Modifiers#The map_type Option|See-It]]</li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps. [[Reference:Crackle Pattern|See-It]]</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients. [[Reference:Color Map|See-It]] and [[Reference:Pigment Map|See-Also]]</li>
<li>{{Done}} Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism. [[Reference:Finish|See-It]]</li>
</ol>

=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>{{Done}} A new parameter <code>polarity</code> has been added to isosurfaces. [[Reference:Isosurface|See-It]]</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus. [[Reference:Torus|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>{{Done}} All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>{{Done}} The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments.
[[Reference:Declare and Local Directives|See-It]]</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>

=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>{{Done}} Light sources distance-based fading can now be set to obey an inverse-power law at all distances [[Reference:Light Source#Light Fading|See-It]]</li>
<li>{{Done}} CIE L*a*b* conversion macros have been added to colors.inc [[Reference:Colors.inc#Color_macros|See-It]]</li>
<li>{{Done}} A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard [[Reference:Colors_ral.inc|See-It]]</li>
<li>Chris says only update copyright date when file otherwise changes.</li>
<li>For a 3.7.1 release we should probably pull all the X11 related sections from the documentation. Remember seeing something about VGA / SVGA support too about which I am suspicious, but maybe this all works?
</ol>

====Changed Behavior====
=====Image Files=====
<ol>
<li>{{Done}} By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>{{Done}} The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>{{Done}} The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</li>

<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension

 The term "IFF" does not seem to be mentioned anywhere in the docs (this is an input-only format), just the keyword, which wasn't chaned. (CLi)
</li>
</ol>

=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>{{Done}} The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li>Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later

 Already documented. May need to be marked as {{Change}}. [[Reference:Strings#String_Literals|See-It]] (CLi)

</li>
</ol>

====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>{{Done}} Dithering is now fully supported for Radiance HDR output files. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Trailing whitespace in INI files no longer causes a warning. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Animation status messages now include the nominal frame number. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} POV-Ray for Windows now reports file names and line numbers of warnings. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Radiosity can now honor the <code>brilliance</code> setting of a surface. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries.</li>
<ul>
<li>[[Reference:Color Map|Color Map]]</li>
<li>[[Reference:Pigment Map|Pigment Map]]</li>
<li>[[Reference:Average Pattern|Average Pattern]]</li>
<li>[[Reference:Normal Map|Normal Map]]</li>
<li>[[Reference:Slope Map|Slope Map]]</li>
<li>[[Reference:Patterned Textures|Patterned Textures]]</li>
<li>[[Reference:Density#Density and Density Maps|Density and Density Maps]]</li>
</ul>
</li>
<li>{{Done}} The number of components per blob is no longer artificially limited. [[Documentation:Tutorial Section 1#Changes and New Features Summary|See-It]]</li>
</ol>

====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.

===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Nothing with ovus or lemon. Add to primativ.pov perhaps?</li>
<li>Rename primativ.pov to primative.pov or delete and create individual files?</li>
<li>portfolio/allobjects.pov out of date.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 2013.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48 

===Multilinks===
Just came across a nest of multilinks on [[Reference:Language_Directives]], thought you'd like to know; would have eliminated them in passing, but since you say that triggers some performance-hogging process I won't touch them. (CLi)

User talk:Jholsenback

2016-12-19T16:45:04Z

Wfpokorny: Updated copyright updates per Chris's direction.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions. [[Reference:User Defined Pattern|Over-Here]]</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a <code>blob</code> or <code>isosurface</code> object.[[Reference:Potential Pattern|Over-Here]]</li>
<li>{{Done}} The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code> [[Reference:Bitmap Modifiers#The map_type Option|See-It]]</li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>

=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>{{Done}} A new parameter <code>polarity</code> has been added to isosurfaces. [[Reference:Isosurface|See-It]]</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Chris says only update copyright date when file otherwise changes.</li>
<li>For a 3.7.1 release we should probably pull all the X11 related sections from the documentation. Remember seeing something about VGA / SVGA support too about which I am suspicious, but maybe this all works?
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</li>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>

=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>Dithering is now fully supported for Radiance HDR output files</li>
<li>Trailing whitespace in INI files no longer causes a warning</li>
<li>Animation status messages now include the nominal frame number</li>
<li>POV-Ray for Windows now reports file names and line numbers of warnings</li>
<li>Radiosity can now honor the <code>brilliance</code> setting of a surface</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries.</li>
<ul>
<li>[[Reference:Color Map|Color Map]]</li>
<li>[[Reference:Pigment Map|Pigment Map]]</li>
<li>[[Reference:Average Pattern|Average Pattern]]</li>
<li>[[Reference:Normal Map|Normal Map]]</li>
<li>[[Reference:Slope Map|Slope Map]]</li>
<li>[[Reference:Patterned Textures|Patterned Textures]]</li>
<li>[[Reference:Density#Density and Density Maps|Density and Density Maps]]</li>
</ul>
</li>
<li>The number of components per blob is no longer artificially limited. [[Reference:Blob|Over-Here]]
 
I don't think any documentation is necessary except in the "what's new section", as the upper limit never seems to have been officially documented in the first place. (CLi)
</li>
</ol>

====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Nothing with ovus or lemon. Add to primativ.pov perhaps?</li>
<li>Rename primativ.pov to primative.pov or delete and create individual files?</li>
<li>portfolio/allobjects.pov out of date.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 2013.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48

User talk:Jholsenback

2016-12-19T15:33:31Z

Wfpokorny: Minor updates to Scene File Checklist

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions. [[Reference:User Defined Pattern|Over-Here]]</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a <code>blob</code> or <code>isosurface</code> object.[[Reference:Potential Pattern|Over-Here]]</li>
<li>{{Done}} The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code> [[Reference:Bitmap Modifiers#The map_type Option|See-It]]</li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>

=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>{{Done}} A new parameter <code>polarity</code> has been added to isosurfaces. [[Reference:Isosurface|See-It]]</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
<li>For a 3.7.1 release we should probably pull all the X11 related sections from the documentation. Remember seeing something about VGA / SVGA support too about which I am suspicious, but maybe this all works?
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</li>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>

=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>Dithering is now fully supported for Radiance HDR output files</li>
<li>Trailing whitespace in INI files no longer causes a warning</li>
<li>Animation status messages now include the nominal frame number</li>
<li>POV-Ray for Windows now reports file names and line numbers of warnings</li>
<li>Radiosity can now honor the <code>brilliance</code> setting of a surface</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries.</li>
<ul>
<li>[[Reference:Color Map|Color Map]]</li>
<li>[[Reference:Pigment Map|Pigment Map]]</li>
<li>[[Reference:Average Pattern|Average Pattern]]</li>
<li>[[Reference:Normal Map|Normal Map]]</li>
<li>[[Reference:Slope Map|Slope Map]]</li>
<li>[[Reference:Patterned Textures|Patterned Textures]]</li>
<li>[[Reference:Density#Density and Density Maps|Density and Density Maps]]</li>
</ul>
</li>
<li>The number of components per blob is no longer artificially limited. [[Reference:Blob|Over-Here]]
 
I don't think any documentation is necessary except in the "what's new section", as the upper limit never seems to have been officially documented in the first place. (CLi)
</li>
</ol>

====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Nothing with ovus or lemon. Add to primativ.pov perhaps?</li>
<li>Rename primativ.pov to primative.pov or delete and create individual files?</li>
<li>portfolio/allobjects.pov out of date.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 2013.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
<li>Update scene and include directory copyright dates</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48

User talk:Jholsenback

2016-12-18T14:36:52Z

Wfpokorny: added code marks

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions.</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a <code>blob</code> or <code>isosurface</code> object.</li>
<li>The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code></li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>
=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>{{Done}} A new parameter <code>polarity</code> has been added to isosurfaces. [[Reference:Isosurface|See-It]]</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
<li>For a 3.7.1 release we should probably pull all the X11 related sections from the documentation. Remember seeing something about VGA / SVGA support too about which I am suspicious, but maybe this all works?
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</code>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>
=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>Dithering is now fully supported for Radiance HDR output files</li>
<li>Trailing whitespace in INI files no longer causes a warning</li>
<li>Animation status messages now include the nominal frame number</li>
<li>POV-Ray for Windows now reports file names and line numbers of warnings</li>
<li>Radiosity can now honor the <code>brilliance</code> setting of a surface</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries. [[Reference:Color Map|See-It]] and [[Reference:Pigment Map|See-Also]]</li>
<li>The number of components per blob is no longer artificially limited. [[Reference:Blob|Over-Here]]</li>
</ol>
====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Nothing with ovus or lemon. Add to primativ.pov perhaps?</li>
<li>Rename primativ.pov to primative.pov or delete and create individual files?</li>
<li>portfolio/allobjects.pov out of date.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 20123.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48

User talk:Jholsenback

2016-12-18T14:19:31Z

Wfpokorny: Adding items to Scene File Checklist

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions.</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a blob or <code>isosurface</code> object.</li>
<li>The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code></li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>
=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>{{Done}} A new parameter <code>polarity</code> has been added to isosurfaces. [[Reference:Isosurface|See-It]]</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
<li>For a 3.7.1 release we should probably pull all the X11 related sections from the documentation. Remember seeing something about VGA / SVGA support too about which I am suspicious, but maybe this all works?
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</code>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>
=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>Dithering is now fully supported for Radiance HDR output files</li>
<li>Trailing whitespace in INI files no longer causes a warning</li>
<li>Animation status messages now include the nominal frame number</li>
<li>POV-Ray for Windows now reports file names and line numbers of warnings</li>
<li>Radiosity can now honor the <code>brilliance</code> setting of a surface</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries. [[Reference:Color Map|See-It]] and [[Reference:Pigment Map|See-Also]]</li>
<li>The number of components per blob is no longer artificially limited. [[Reference:Blob|Over-Here]]</li>
</ol>
====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Nothing with ovus or lemon. Add to primativ.pov perhaps?</li>
<li>Rename primativ.pov to primative.pov or delete and create individual files?</li>
<li>portfolio/allobjects.pov out of date.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 20123.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48

User talk:Jholsenback

2016-12-16T13:35:09Z

Wfpokorny: Thoughts on X11 unix documentation. Questioning vga/svga support and docs.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions.</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a blob or <code>isosurface</code> object.</li>
<li>The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code></li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>
=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>A new parameter <code>polarity</code> has been added to isosurfaces to choose whether function values above the threshold should indicate the inside or outside. [[Reference:Isosurface|Over-Here]]

By default, the inside of an <code>isosurface</code> is defined as the set of all points inside the <code>contained_by</code> shape where the function values are below the threshold. Since 3.7.1, this can be changed via the {{New}} <code>polarity</code> keyword: Specifying a positive setting or <code>on</code> will instead cause function values above the threshold to be considered inside. Specifying a negative setting or <code>off</code> will give the default behavior.

</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
<li>For a 3.7.1 release we should probably pull all the X11 related sections from the documentation. Remember seeing something about VGA / SVGA support too about which I am suspicious, but maybe this all works?
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</code>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>
=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>Dithering is now fully supported for Radiance HDR output files</li>
<li>Trailing whitespace in INI files no longer causes a warning</li>
<li>Animation status messages now include the nominal frame number</li>
<li>POV-Ray for Windows now reports file names and line numbers of warnings</li>
<li>Radiosity can now honor the <code>brilliance</code> setting of a surface</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries. [[Reference:Color Map|See-It]] and [[Reference:Pigment Map|See-Also]]</li>
<li>The number of components per blob is no longer artificially limited. [[Reference:Blob|Over-Here]]</li>
</ol>
====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 20123.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48

User talk:Jholsenback

2016-12-16T13:29:28Z

Wfpokorny: Note I forgot yesterday on Unix SDL change.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions.</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a blob or <code>isosurface</code> object.</li>
<li>The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code></li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>
=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>A new parameter <code>polarity</code> has been added to isosurfaces to choose whether function values above the threshold should indicate the inside or outside. [[Reference:Isosurface|Over-Here]]

By default, the inside of an <code>isosurface</code> is defined as the set of all points inside the <code>contained_by</code> shape where the function values are below the threshold. Since 3.7.1, this can be changed via the {{New}} <code>polarity</code> keyword: Specifying a positive setting or <code>on</code> will instead cause function values above the threshold to be considered inside. Specifying a negative setting or <code>off</code> will give the default behavior.

</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</code>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>
=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise). Forgot to mention yesterday this change is self-documenting due the prompts to the console changing to reflect it.

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Noteworthy Improvements====
<ol>
<li>{{Done}} Array elements no longer have to be of the same type. [[Reference:Array|See-It]]</li>
<li>Dithering is now fully supported for Radiance HDR output files</li>
<li>Trailing whitespace in INI files no longer causes a warning</li>
<li>Animation status messages now include the nominal frame number</li>
<li>POV-Ray for Windows now reports file names and line numbers of warnings</li>
<li>Radiosity can now honor the <code>brilliance</code> setting of a surface</li>
<li>{{Done}} Color maps, pigment maps and the like are no longer limited to 256 entries. [[Reference:Color Map|See-It]] and [[Reference:Pigment Map|See-Also]]</li>
<li>The number of components per blob is no longer artificially limited. [[Reference:Blob|Over-Here]]</li>
</ol>
====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 20123.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48

User talk:Jholsenback

2016-12-15T11:22:23Z

Wfpokorny: Performance degrade admission question.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions.</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a blob or <code>isosurface</code> object.</li>
<li>The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code></li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>
=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>A new parameter <code>polarity</code> has been added to isosurfaces to choose whether function values above the threshold should indicate the inside or outside. [[Reference:Isosurface|Over-Here]]

By default, the inside of an isosurface is defined as the set of all points inside the `contained_by` shape where the function values are below the threshold.
Since 3.7.1, this can be changed via the {{New}} <code>polarity</code> keyword: Specifying a positive setting or <code>on</code> will instead cause function values
above the threshold to be considered inside. Specifying a negative setting or <code>off</code> will give the default behaviour.

</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</code>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>
=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise).

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 20123.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

===Admissions...===
Do we admit 3.7.1 is slower and explain why (C++)? See: https://github.com/POV-Ray/povray/issues/48

User talk:Jholsenback

2016-12-15T11:18:08Z

Wfpokorny: Clarification on Unix SDL console message update.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions.</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a blob or <code>isosurface</code> object.</li>
<li>The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code></li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>
=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>A new parameter <code>polarity</code> has been added to isosurfaces to choose whether function values above the threshold should indicate the inside or outside. [[Reference:Isosurface|Over-Here]]

By default, the inside of an isosurface is defined as the set of all points inside the `contained_by` shape where the function values are below the threshold.
Since 3.7.1, this can be changed via the {{New}} <code>polarity</code> keyword: Specifying a positive setting or <code>on</code> will instead cause function values
above the threshold to be considered inside. Specifying a negative setting or <code>off</code> will give the default behaviour.

</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</code>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>
=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>

The focus of this change was correcting unix console messages. There was previously no notice 'p' and 'q' were active for +D renders. The final pause, if using +P, had always incorrectly said hitting any key would continue/quit when only 'q', enter or detecting on the SDL window would. Enabling 'p' to also continue from the final pause in addition to mid render ones makes 'p' operation consistent throughout the render (and it was cleaner code-wise).

<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 20123.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

User talk:Jholsenback

2016-12-15T11:01:32Z

Wfpokorny: Made a start on the Scene file checklist. Added misc item for copyright dates.

===3.7.1 Changes Checklist===
The following is a check list of the changes that need to be documented prior to version 3.7.1 release.

====New Features====
=====Materials=====
<ol>
<li>A new finish parameter <code>use_alpha</code> has been added to suppress highlights and reflections depending on pigment transparency.</li>
<li>A new special pigment pattern <code>user_defined</code> has been added to define the pigment color directly in terms of a set of functions.</li>
<li>A new pattern <code>potential</code> has been added to define a pattern based on the potential field of a blob or <code>isosurface</code> object.</li>
<li>The <code>map_type</code> keyword now supports the Angular Map projection for light probes, popularized by Paul Devebec, as <code>type 7</code></li>
<li>{{Done}} Native support for repetition has been added to the <code>crackle</code> pattern to avoid the discontinuities in the pattern caused by repeat warps.</li>
<li>{{Done}} The torus syntax has been extended to give more control over the spindle in a self-intersecting torus</li>
<li>{{Done}} Color and pigment maps now support non-linear interpolation to achieve more pleasing gradients</li>
<li>Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
</ol>
=====Geometric Primitives=====
<ol>
<li>{{Done}} UV mapping support has been added to cones and cylinders. [[Reference:UV Mapping#Supported Objects|See-It]]</li>
<li>A new parameter <code>polarity</code> has been added to isosurfaces to choose whether function values above the threshold should indicate the inside or outside. [[Reference:Isosurface|Over-Here]]

By default, the inside of an isosurface is defined as the set of all points inside the `contained_by` shape where the function values are below the threshold.
Since 3.7.1, this can be changed via the {{New}} <code>polarity</code> keyword: Specifying a positive setting or <code>on</code> will instead cause function values
above the threshold to be considered inside. Specifying a negative setting or <code>off</code> will give the default behaviour.

</li>
<li>{{Done}} A new geometric primitive <code>lemon</code> has been added. [[Reference:Lemon|See-It]]</li>
</ol>

=====Scene Description Language, Options and INI settings=====
<ol>
<li>{{Done}} Support for variable-size arrays has been added</li>
<li>{{Done}} A new data container <code>dictionary</code> has been added to support structured storage of data</li>
<li>{{Done}} Pseudo-dictionaries <code>local</code> and <code>global</code> have been added, allowing to specifically access local or global identifiers respectively</li>
<li>{{Done}} The <code>max_extent</code> function as used to determine the size of an image map in pixels can now also be used on normal maps and density files</li>
<li>{{Done}} Macros up to a certain size (currently hard-coded to 65536 characters per macro) are now cached in memory, improving parsing speed of invocations especially when the macro in question is defined in a different file</li>
<li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code>. Previously this was only the case inside function definitions where it applied only to the <code>.gray</code> color pseudo-component</li>
<li>{{Done}} A new inbuilt constant <code>tau</code> has been added</li>
<li>The <code>#declare</code> and <code>#local</code> syntax has been extended to support tuple-style assignments. The main purpose is to allow macros to return a set of values rather than just a single one</li>
<li>{{Done}} The macro syntax has been extended to allow for <code>optional</code> parameters</li>
<li>{{Done}} The creation of a log for the <code>+C</code> render abort-continue feature can now be suppressed using <code>-CC</code> to save disk space</li>
</ol>
=====Miscellaneous=====
<ol>
<li>{{Done}} Support for the ITU-R BT.709 and BT.2020 transfer functions has been added to POV-Ray's gamma handling portfolio</li>
<li>{{Done}} A new function-based user-defined camera type <code>user_defined</code> has been added</li>
<li>Light sources distance-based fading can now be set to obey an inverse-power law at all distances</li>
<li>CIE L*a*b* conversion macros have been added to colors.inc</li>
<li>A new include file colors_ral.inc has been added containing predefined colors according to the RAL Classic standard</li>
<li>Thinking all copyright dates in code, scenes, documentation should be updated to 2016 (or 2017) for beta release</li>
</ol>
====Changed Behavior====
=====Image Files=====
<ol>
<li>By default, gamma handling of NetPBM (PPM/PGM) in and output files now follows the official NetBPM standard, which mandates gamma-encoding using the ITU-R BT.709 transfer function. As usual this can be overridden by the <code>gamma</code> input file parameter or <code>File_Gamma</code> INI setting, respectively</li>
<li>The Compression setting now affects more file types: Specifying <code>Compression=1</code> with file type <code>T</code> (Targa) will now generate compressed Targa (same as file type <code>C</code>), and explicitly specifying <code>Compression=0</code> with file type <code>P</code> (Netpbm PPM/PGM) will generate plain (ASCII) Netpbm rather than
raw (binary)</li>
<li>POV-Ray will now try to auto-detect whether an input TIFF file with alpha channel uses <code>premultiplied</code> or non-premultiplied alpha mode, rather than blindly presuming <code>premultiplied</code> alpha</li>
<li>The interaction of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed to be more intuitive: rather than adding the image's transparency to the user-specified transparency, the image's opacity is now effectively multiplied with the user-specified opacity. (requires <code>#version 3.71</code> or later)</code>
<li>The image file format previously referred to as IFF (now more precisely referred to as IFF-ILBM) is now associated with the <code>.lbm</code> file extension in addition to the <code>.iff</code> extension</li>
</ol>
=====Miscellaneous=====
<ol>
<li>On Unix with Simple DirectMedia Layer (SDL) enabled the p key can now be used to pause and un-pause a render</li>
<li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed, except when used in a <code>#version</code> directive, in which case the behavior remains unchanged. The requirement to start each scene with a <code>#version</code> statement is now more strongly enforced for POV-Ray 3.7 scenes. An error is reported if the scene file does not begin with a <code>#version</code> directive but does have a <code>#version 3.71</code> (or later) directive anywhere in the main scene file</li>
<li> Using <code>ambient</code> with a suspiciously high value in a non-legacy scene will now issue a warning, unless <code>emission</code> is also specified</li>
<li>A long-standing undocumented inconsistency in the treatment of backslashes in string literals, in which backslashes were essentially not interpreted as escape characters if the parser expected a filename, has been cleaned up. Backslashes are now treated as escape characters in all string literals. requires <code>#version 3.71</code> or later</li>
</ol>
====Code Snippet's Comments and Content Related====
Use this section for code snippet's to be included in reference. Comments and content related items are welcome too.
===3.7.1 Scene File Checklist===
<ol>
<li>{{Done}} spindle torus example</li>
<li>{{Done}} user_defined camera example</li>
<li>{{Done}} Pavement pattern example</li>
<li>{{Done}} Unit square scalings for pavement and tiling patterns added to pavement.pov and tiling.pov</li>
<li>Potential pattern using blobs. Second with iso or as option in first scene.</li>
<li>Recent scenes with rendered PNGs - even some 3.7 ones - are not part of the scene directory html Friedrich A. Lohmueller created in 20123.</li>
<li>Replace while loops with for loops where counting. Cleans up our example scenes.</li>
</ol>

User:Wfpokorny/DensityFile/arraycoupleddf3s

2016-12-07T13:53:31Z

Wfpokorny: ConvertImagesToDF3() now using gamma 1.0 with input images. Think easier for users.

The include file arraycoupleddf3s.inc defines several macros useful for working with df3 files. Supposing it might be merged into arrays.inc given the df3 write macro is already in that include file?

While much of the updated df3, density_file pattern documentation presumes additional code updates have been adopted, this include file was written to work compatibly with the 3.7.0-stable release.

The current body of the include file:

<pre>
// This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.
// To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a
// letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.

// Persistence of Vision Ray Tracer version 3.7 Include File
// File: arraycoupleddf3s.inc
// Last updated: December 07 2016 WFP
// Description: Macros & functions for working with arrays and df3 files.
//
// ARRAYS_ReadDF3 - Complement to arrays.inc's ARRAYS_WriteDF3.
// ConvertImagesToDF3 - 2D images to df3 file.
// ConvertArrayOfStringsToDF3 - Array of strings to df3 file.
// ConvertFunctionToDF3 - Given a function creates a df3 file.
// NxNx9DBLtoArrayEntry - Convert POV-Ray DBL to 9 deep NxN array
// usually ahead of ARRAYS_WriteDF3 write and
// access to the values as +-64 bit depth via
// FnctNxNx9ArrayEntryToDBL.
// FnctNxNx9ArrayEntryToDBL - Function to work with +-64 bit, df3 stored,
// integer values.
//------------------------------------------------------------------------------

#ifndef(ARRAYCOUPLEDDF3S_INC_TEMP)
#declare ARRAYCOUPLEDDF3S_INC_TEMP = version;
#version 3.7;

#ifdef(View_POV_Include_Stack)
#debug "including arraycoupleddf3s.inc\n"
#end

#include "arrays.inc"

//--- Generic df3 read. The df3 write was added in 3.7.0 to arrays.inc
// as ARRAYS_WriteDF3(). The incoming array must have been pre-defined
// at a size matching the df3 file to accurately read and store all
// voxel values.
#macro ARRAYS_ReadDF3(_Ary,_FileName)
#local Fn_df3 = function{pattern{density_file df3 _FileName interpolate 0}}
#local _X = dimension_size(_Ary,1);
#local _Y = dimension_size(_Ary,2);
#local _Z = dimension_size(_Ary,3);
#local Dx = 1/_X;
#local DxVoxCtr = Dx/2;
#local Dy = 1/_Y;
#local DyVoxCtr = Dy/2;
#local Dz = 1/_Z;
#local DzVoxCtr = Dz/2;
#for (Z,0,_Z-1)
#for (Y,0,_Y-1)
#for (X,0,_X-1)
#local Xi=(X*Dx)+DxVoxCtr;
#local Yi=(Y*Dy)+DyVoxCtr;
#local Zi=(Z*Dz)+DzVoxCtr;
#local _Ary[X][Y][Z]=Fn_df3(Xi,Yi,Zi).red;
#end
#end
#end
#end

//--- Utility function with with ConvertArrayOfStringsToDF3.
#macro arraycoupleddf3sAsciiToVal(_AsciiVal)
#switch (_AsciiVal)
#range (asc("a"), asc("z")) #local ReturnVal = (_AsciiVal-asc("a"))/52.0; #break
#range (asc("A"), asc("Z")) #local ReturnVal = (_AsciiVal-asc("A")+26)/52.0; #break
#range (asc("0"), asc("9")) #local ReturnVal = (_AsciiVal-asc("0"))/10.0; #break
#case (asc ("*")) #local ReturnVal = 1.0; #break
#else #local ReturnVal = 0.0; #break
#end
(ReturnVal)
#end

//--- Translate a 'y,z' 2D array of text strings into df3 file. String length
// provides the 'x' range for the df3.
//
// 0-9 characters => 0.0 to 0.9 df3 values.
// * character => 1.0.
// a-zA-Z characters => 52 levels from a=1/52 to Z=52/52.
// Other characters => 0.0.
//
// _Ary - The array containing text strings to convert.
// _DF3FileName - Name of the output df3 file.
// _Depth - 8 or 16. Best resolution from text only 1/52 so usually 8.
// _Pad - 0|<val>. If >0, we will pad all sides of the df3 with that
// count of 0.0 values.
// _PadOnLeft - 0 or 1. If 1 defined array df3 is padded on the left with
// 0s to a width equal to the incoming right side. This is
// done for convenience when creating df3 for lathe work, but
// also due the 256 character string limit in POV-Ray SDL.
//
// Example creating a df3 profile for bowl. Isosurface later scales flatter.
//
// #include "arrays.inc" // For ARRAYS_WriteDF3()
// #include "arraycoupleddf3s.inc" // Array coupled DF3 macros & functions.
//
// #declare AryStrs = array[25][1]
// #declare AryStrs[0][0] = "-------------------------------------2------------";
// #declare AryStrs[1][0] = "------------------------------------3-------------";
// #declare AryStrs[2][0] = "-----------------------------------2--------------";
// #declare AryStrs[3][0] = "----------------------------------2---------------";
// #declare AryStrs[4][0] = "---------------------------------2----------------";
// #declare AryStrs[5][0] = "--------------------------------3-----------------";
// #declare AryStrs[6][0] = "-------------------------------4------------------";
// #declare AryStrs[7][0] = "-------------------------------5------------------";
// #declare AryStrs[8][0] = "------------------------------4-------------------";
// #declare AryStrs[9][0] = "-----------------------------5--------------------";
// #declare AryStrs[10][0] = "----------------------------6---------------------";
// #declare AryStrs[11][0] = "----------------------------6---------------------";
// #declare AryStrs[12][0] = "----------------------------6---------------------";
// #declare AryStrs[13][0] = "----------------------------6---------------------";
// #declare AryStrs[14][0] = "---------------------------7----------------------";
// #declare AryStrs[15][0] = "--------------------------7-----------------------";
// #declare AryStrs[16][0] = "-------------------------7------------------------";
// #declare AryStrs[17][0] = "------------------------7-------------------------";
// #declare AryStrs[18][0] = "-----------------------7--------------------------";
// #declare AryStrs[19][0] = "-------------------6666---------------------------";
// #declare AryStrs[20][0] = "------------------7-------------------------------";
// #declare AryStrs[21][0] = "-----------------7--------------------------------";
// #declare AryStrs[22][0] = "----------------7---------------------------------";
// #declare AryStrs[23][0] = "---------------7----------------------------------";
// #declare AryStrs[24][0] = "666666666666666-----------------------------------";
// //
// // <---------------------- 50 ---------------------->
//
// ConvertArrayOfStringsToDF3(AryStrs,"StringsToDF3.df3",8,5,1)
//
#macro ConvertArrayOfStringsToDF3(_Ary,_DF3FileName,_Depth,_Pad,_PadOnLeft)
#ifndef (_Ary)
#error "ConvertArrayOfStringsToDF3: Array passed is not defined.\n"
#end
#if (dimensions(_Ary)!=2)
#error "ConvertArrayOfStringsToDF3: Array/DF3 must have 2 dimensions.\n"
#end
#local _Y = dimension_size(_Ary,1);
#local _Z = dimension_size(_Ary,2);
#if (_Y<1)
#error "ConvertArrayOfStringsToDF3: Array/DF3 dimension 1 must be >=1.\n"
#end
#if (_Z<1)
#error "ConvertArrayOfStringsToDF3: Array/DF3 dimension 2 must be >=1.\n"
#end
#local _X = strlen(_Ary[0][0]);
#if (_X<1)
#error "ConvertArrayOfStringsToDF3: String lengths must be >=1.\n"
#end
#if (_Depth!=8 & _Depth!=16)
#error "ConvertArrayOfStringsToDF3: Depth parameter must be 8 or 16.\n"
#end
#if (_Pad<0 | _Pad>=pow(2,16))
#error "ConvertArrayOfStringsToDF: Pad value must be >=0 and less than max df3 range.\n"
#end
#if (_PadOnLeft!=0 & _PadOnLeft!=1)
#error "ConvertImagesToDF3: PadOnLeft value must be 0 or 1.\n"
#end

#local _Xn = _X+(2*_Pad);
#local _Yn = _Y+(2*_Pad);
#local _Zn = _Z+(2*_Pad);
#if (_PadOnLeft)
#local _Xn = _Xn+_X;
#local padBy = _X;
#else
#local padBy = 0;
#end
#local DF3Ary = array[_Xn][_Yn][_Zn];

#local LookAtStringPlaneCnt=0;
#for (Z,0,_Zn-1)
#if (Z>=_Pad & Z<_Zn-_Pad)
#debug concat("zPlane ",str(Z,-1,0)," StringPlane ",str(LookAtStringPlaneCnt,-1,0),"\n")
#else
#debug concat("zPlane ",str(Z,-1,0)," Padding with zeroes.\n")
#end

#for (Y,0,_Yn-1)
#if (Y>=_Pad & Y<_Yn-_Pad)
#local _Yr=Y-_Pad;
#else
#local _Yr=0;
#end
#if (strlen(_Ary[_Yr][min(LookAtStringPlaneCnt,_Z-1)])!=_X)
#debug concat("\n","ConvertArrayOfStringsToDF3: String length of array entry at:","\n")
#debug concat("[",str(_Yr,-1,0),"][",str(min(LookAtStringPlaneCnt,_Z-1),-1,0),"] must match [0][0] length of ",str(_X,-1,0),".","\n\n")
#error "Stop."
#end
#for (X,0,_Xn-1)
#if (X>=_Pad+padBy & Y>=_Pad & Z>=_Pad & X<_Xn-_Pad & Y<_Yn-_Pad & Z<_Zn-_Pad)
#local _Xr=X-_Pad;
// #debug concat(str(_Xr,-1,0)," ",str(_Yr,-1,0)," ",str(LookAtStringPlaneCnt,-1,0),"\n")
#local Character=asc(substr(_Ary[_Yr][LookAtStringPlaneCnt],_Xr-padBy+1,1));
#local DF3Ary[X][(_Yn-1)-Y][Z]=arraycoupleddf3sAsciiToVal(Character);
#else
#local DF3Ary[X][(_Yn-1)-Y][Z]=0.0;
#end
#end
#end
#if (Z>=_Pad & Z<_Zn-_Pad)
#local LookAtStringPlaneCnt=LookAtStringPlaneCnt+1;
#end
#end
ARRAYS_WriteDF3(DF3Ary,_DF3FileName,_Depth)
#end

//--- Translate one or more images into df3 file filtering by linear distance
// from the passed color as a 0-1 ratio in the color unit cube.
//
// _X - The x voxel grid count.
// _Y - The y voxel grid count.
// _BaseVal - The base value to use when color is not matched.
// This is normally 0.0.
// _UseVal - To get specific value in the df3 on matching color
// set explicitly to >=0.0, <=1.0 value.
// Otherwise -1 will set voxel to the image's '.grey'.
// _Color - The color to match as 3 value vector.
// _ColorNearness - 0-1 value specifies how near image color must be to
// be considered a match.
// _Weight - 0|1 If 1, samples 12 times in circular pattern to
// a half voxel radius and multiplies voxel center
// sampled value by ratio matched by color-wise near.
// _ImageFileNamesAry - An array of 1 to N image file names. Image files
// can repeat for depth of representation in the df3.
// _DF3FileName - Name of the output df3 file.
// _Depth - 8 or 16.
// _Pad - 0|<val>. If >0, we will pad all sides of the df3
// with that count of 0.0 values.
//
// Example code to create a df3 where clouds defined white/grey on black
// background in 3 image files:
//
// #include "arrays.inc" // For ARRAYS_WriteDF3()
// #include "arraycoupleddf3s.inc" // Array coupled DF3 macros & functions.
//
// #declare ImageFileNamesAry=array[3] {
// "CloudFront.png",
// "CloudMiddle.png",
// "CloutBack.png"
// }
// ConvertImagesToDF3(500,500,0.0,-1,<1,1,1>,1.5,0,ImageFileNamesAry,"Cloud.df3",8,5)
//
// #error "Stopping after parse stage for DF3 creation from image."
//
#macro ConvertImagesToDF3(_X,_Y,_BaseVal,_UseVal,_Color,_ColorNearness,_Weight,
_ImageFileNamesAry,_DF3FileName,_Depth,_Pad)
#if (_X<1 | _Y<1)
#error "ConvertImagesToDF3: Passed X and Y dimensions must be >=1.\n"
#end
#if (_BaseVal<0.0 | _BaseVal>1.0)
#error "ConvertImagesToDF3: Base value must be >=0.0 and <=1.0 (normally 0.0).\n"
#end
#if ((_UseVal!=-1) & (_UseVal<0.0 | _UseVal>1.0))
#error "ConvertImagesToDF3: Use value must -1 or be >=0.0 and <=1.0.\n"
#end
#local _tmpColor = color _Color;
#if (_tmpColor.red<0.0)
#error "ConvertImagesToDF3: red component of color must be >=0.0.\n"
#end
#if (_tmpColor.green<0.0)
#error "ConvertImagesToDF3: green component of color must be >=0.0.\n"
#end
#if (_tmpColor.blue<0.0)
#error "ConvertImagesToDF3: blue component of color must be >=0.0.\n"
#end
#if (_ColorNearness<0.0)
#error "ConvertImagesToDF3: ColorNearness value must be >=0.0.\n"
#end
#if (_Weight!=0 & _Weight!=1)
#error "ConvertImagesToDF3: Weight value must be 0 or 1.\n"
#end
#ifndef (_ImageFileNamesAry)
#error "ConvertImagesToDF3: Image array passed is not defined.\n"
#end
#if (dimensions(_ImageFileNamesAry)!=1)
#error "ConvertImagesToDF3: Image array must have 1 dimension - a list.\n"
#end
#if (dimension_size(_ImageFileNamesAry,1)<1)
#error "ConvertImagesToDF3: Image array dimension 1 must be >=1.\n"
#end
#if (_Depth!=8 & _Depth!=16)
#error "ConvertImagesToDF3: Depth parameter must be 8 or 16.\n"
#end
#if (_Pad<0 | _Pad>=pow(2,16))
#error "ConvertImagesToDF3: Pad value must be >=0 and less than max df3 range.\n"
#end

#local _LookAtImageCnt=0;
#for (Z,0,_Zn-1)
#if (Z>=_Pad & Z<_Zn-_Pad)
#debug concat("zPlane ",str(Z,-1,0)," ",_ImageFileNamesAry[_LookAtImageCnt],"\n")
#ifdef (FnImagePigment)
#undef FnImagePigment
#end
#local FnImagePigment=function{ pigment {image_map {concat(_ImageFileNamesAry[_LookAtImageCnt]) gamma 1.0 map_type 0 interpolate 2} } }
#local _LookAtImageCnt=_LookAtImageCnt+1;
#else
#debug concat("zPlane ",str(Z,-1,0)," Padding with zeroes.\n")
#end

#for (Y,0,_Yn-1)
#local _Yr=(Y-_Pad)/(_Yn-(2*_Pad));
#for (X,0,_Xn-1)
#if (X>=_Pad & Y>=_Pad & Z>=_Pad & X<_Xn-_Pad & Y<_Yn-_Pad & Z<_Zn-_Pad)
#local _Xr=(X-_Pad)/(_Xn-(2*_Pad));
#local rDiff=_Color.red -FnImagePigment(_Xr,_Yr,0).red;
#local gDiff=_Color.green-FnImagePigment(_Xr,_Yr,0).green;
#local bDiff=_Color.blue -FnImagePigment(_Xr,_Yr,0).blue;
#if (sqrt(rDiff*rDiff+gDiff*gDiff+bDiff*bDiff)<=_ColorNearness)
#if (_Weight=1)
#local weightMult = 1.0; // Count center as 1 as this must be true to be at this line
#for (I,0,11)
#local rDiff=_Color.red -FnImagePigment(_Xr+AryWeightVecs[I].x,_Yr+AryWeightVecs[I].y,0).red;
#local gDiff=_Color.green-FnImagePigment(_Xr+AryWeightVecs[I].x,_Yr+AryWeightVecs[I].y,0).green;
#local bDiff=_Color.blue -FnImagePigment(_Xr+AryWeightVecs[I].x,_Yr+AryWeightVecs[I].y,0).blue;
#if (sqrt(rDiff*rDiff+gDiff*gDiff+bDiff*bDiff)<=_ColorNearness)
#local weightMult = weightMult + 1;
#end
#end
#local weightMult = weightMult/13;
#else
#local weightMult = 1.0;
#end
#if (_UseVal>=0 & _UseVal<=1)
#local Ary[X][Y][Z]=_UseVal*weightMult;
#else
#local Ary[X][Y][Z]=FnImagePigment(_Xr,_Yr,0).gray*weightMult;
#end
#else
#local Ary[X][Y][Z]=_BaseVal;
#end
#else
#local Ary[X][Y][Z]=0.0;
#end
#end
#end
#end
ARRAYS_WriteDF3(Ary,_DF3FileName,_Depth)
#end

//--- Translate a function into a df3 file.
//
// _X - The x voxel grid count to be created.
// _Y - The y voxel grid count.
// _Z - The z voxel grid count.
// _BaseVal - The base value to use when function value is not
// matched. This is normally 0.0.
// _UseVal - For specific value set explicitly as >=0.0, <=1.0.
// Otherwise -1 to use absolute of matched function
// value clamped to 0.0 - 1.0 range.
// _FnctMinValue - The minimum value returned by function to be
// considered an match.
// _FnctMaxValue - The maximum value for a match.
// _Function - The function to run over the unit cube to a
// resolution of _X,_Y,_Z.
// _DF3FileName - Name of the output df3 file.
// _Depth - 8 or 16.
// _Pad - 0|<val>. If >0, pads all sides of the df3 with
// that count of 0.0 values.
//
// Example code:
//
// #include "arrays.inc" // For ARRAYS_WriteDF3()
// #include "arraycoupleddf3s.inc" // Array coupled DF3 macros & functions.
//
// ConvertFunctionToDF3(50,50,50,0.0,0.8,-9e10,0.0,Fnct00,"Cloud.df3",8,5)
//
// #error "Stopping after parse stage for DF3 creation from image."
//
#macro ConvertFunctionToDF3(_X,_Y,_Z,_BaseVal,_UseVal,_FnctMinVal,_FnctMaxVal,
_Function,_DF3FileName,_Depth,_Pad)
#if (_X<1 | _Y<1 | _Z<1)
#error "ConvertFunctionToDF3: Passed X, Y and Z dimensions must be >=1.\n"
#end
#if (_BaseVal<0.0 | _BaseVal>1.0)
#error "ConvertFunctionToDF3: Base value must be >=0.0 and <=1.0 (normally 0.0).\n"
#end
#if ((_UseVal!=-1) & (_UseVal<0.0 | _UseVal>1.0))
#error "ConvertFunctionToDF3: Use value must -1 or be >=0.0 and <=1.0.\n"
#end
#if (_FnctMinVal > _FnctMaxVal)
#error "ConvertFunctionToDF3: Function min value must be <=0.0 max value.\n"
#end
#ifndef (_Function)
#error "ConvertFunctionToDF3: Function passed is not defined.\n"
#end
#if (_Depth!=8 & _Depth!=16)
#error "ConvertFunctionToDF3: Depth parameter must be 8 or 16.\n"
#end

#local _Xn = _X+(2*_Pad);
#local _Yn = _Y+(2*_Pad);
#local _Zn = _Z+(2*_Pad);
#local Ary = array[_Xn][_Yn][_Zn];
//---
#for (Z,0,_Zn-1)
#if (Z>=_Pad & Z<_Zn-_Pad)
#debug concat("zPlane ",str(Z,-1,0)," Evaluating\n")
#else
#debug concat("zPlane ",str(Z,-1,0)," Padding with zeroes.\n")
#end
#local _Zr=(Z-_Pad)/_Z;

#for (Y,0,_Yn-1)
#local _Yr=(Y-_Pad)/_Y;
#for (X,0,_Xn-1)
#if (X>=_Pad & Y>=_Pad & Z>=_Pad & X<_Xn-_Pad & Y<_Yn-_Pad & Z<_Zn-_Pad)
#local _Xr=(X-_Pad)/_X;
#local tmpVal=_Function(_Xr+((1/_X)/2),_Yr+((1/_Y)/2),_Zr+((1/_Z)/2));
#if (tmpVal>=_FnctMinVal & tmpVal<=_FnctMaxVal)
#if (_UseVal>=0 & _UseVal<=1)
#local Ary[X][Y][Z]=_UseVal;
#else
#local Ary[X][Y][Z]=min(1,max(0,abs(tmpVal)));
#end
#else
#local Ary[X][Y][Z]=_BaseVal;
#end
#else
#local Ary[X][Y][Z]=0.0;
#end
#end
#end
#end
ARRAYS_WriteDF3(Ary,_DF3FileName,_Depth)
#end

//--- NxNx9 DF3 (coupled to Array) entry of converted POV-Ray DBL.
// Expected depth is Nine 0.0 to 1.0 values being least to
// most significant bytes of 64bits in depths 0-7 and
// a 0 or >zero value in depth 8 with 0 meaning positive.
// Result is DBL like in accuracy, but of course not range.
// Macro defines a function which returns the DBL normalized
// to +- the passed limited range. Function set up has
// the parameters i,j,DeltaZ,range. Intended for use with one
// byte per voxel DF3 file storage and retrieval of DBL, 64bit
// accurate values.
//
// Example set up of function FnctDepth follows. Macro call passed
// couple and already defined array and function->density_file pattern.
//
// #declare FnctDepth=FnctNxNx9ArrayEntryToDBL(Ary,PairedDF3Fnct);
//
// _i - What entry in i (x in df3, perhaps not geometrical info stored...)
// _j - what entry in j (y in df3)
// _Db - Depth of byte (z in df3)
// _range - Range over which stored values previously normalized.
//
// An example scene finding distance, or depth map, values is
// included in the documentation.
//
#macro FnctNxNx9ArrayEntryToDBL(_Ary,_FnctDF3)
function (_i,_j,_Db,_range) {
(_FnctDF3(_i,_j,(0*_Db)+(_Db/2))*255 +_FnctDF3(_i,_j,(1*_Db)+(_Db/2))*255*pow(2, 8)+
_FnctDF3(_i,_j,(2*_Db)+(_Db/2))*255*pow(2,16)+_FnctDF3(_i,_j,(3*_Db)+(_Db/2))*255*pow(2,24)+
_FnctDF3(_i,_j,(4*_Db)+(_Db/2))*255*pow(2,32)+_FnctDF3(_i,_j,(5*_Db)+(_Db/2))*255*pow(2,40)+
_FnctDF3(_i,_j,(6*_Db)+(_Db/2))*255*pow(2,48)+_FnctDF3(_i,_j,(7*_Db)+(_Db/2))*255*pow(2,56)
)/pow(2,56)*_range*select((_FnctDF3(_i,_j,(8*_Db)+(_Db/2))-0.5),1,-1)
}
#ifndef (_Ary)
#error "FnctNxNx9ArrayEntryToDBL: Array passed is not defined.\n"
#end
#ifndef (_FnctDF3)
#error "FnctNxNx9ArrayEntryToDBL: Function passed is not defined.\n"
#end
#if (dimensions(_Ary)!=3)
#error "FnctNxNx9ArrayEntryToDBL: Array/DF3 must have 3 dimensions.\n"
#end
#local _II = dimension_size(_Ary,1);
#if (_II<1)
#error "FnctNxNx9ArrayEntryToDBL: Array/DF3 dimension 1 must be >=1.\n"
#end
#local _JJ = dimension_size(_Ary,2);
#if (_JJ<1)
#error "FnctNxNx9ArrayEntryToDBL: Array/DF3 dimension 2 must be >=1.\n"
#end
#local _B = dimension_size(_Ary,3);
#if (_B!=9)
#error "FnctNxNx9ArrayEntryToDBL: Array/DF3 dimension 3 must be 9.\n"
#end
#end

//--- NxNx9 POV-Ray DBL to 9 array entries (64bit+sign) conversion.
// Expected depth is Nine 0.0 to 1.0 values being Least to
// most significant bytes of 64bits in depths 0-7.
// A 0 or >zero value in byte depth 8. 0 meaning the value is positive.
// Result is > DBL like in accuracy, but of course not range.
// Macro converts the DBL normalized to +- the passed limited range to a
// set of 9 array entries. The parameters are array,i,j,range,dbl.
// Intended for use with one byte per voxel DF3 file storage
// and retrieval of DBL, 64bit accurate values. Values larger than
// the passed +-range are set to 0.
//
// Example macro call:
//
// NxNx9DBLtoArrayEntry(DepthAry,I,J,Range,Value)
//
// An example scene finding distance, or depth map, values is
// included in the documentation.
//
#macro NxNx9DBLtoArrayEntry(_Ary,_i,_j,_range,_value)
#ifndef (_Ary)
#error "FnctNxNx9ArrayEntryToDBL: Array passed is not defined.\n"
#end
#if (dimensions(_Ary)!=3)
#error "FnctNxNx9ArrayEntryToDBL: Array must have 3 dimensions.\n"
#end
#local _II = dimension_size(_Ary,1);
#if (_II<1)
#error "FnctNxNx9ArrayEntryToDBL: Array dimension 1 must be >=1.\n"
#end
#local _JJ = dimension_size(_Ary,2);
#if (_JJ<1)
#error "FnctNxNx9ArrayEntryToDBL: Array dimension 2 must be >=1.\n"
#end
#local _B = dimension_size(_Ary,3);
#if (_B!=9)
#error "FnctNxNx9ArrayEntryToDBL: Array dimension 3 must be 9.\n"
#end
#if (_value<0)
#local _Ary[_i][_j][8] = 1;
#else
#local _Ary[_i][_j][8] = 0;
#end
#if (abs(_value)>_range)
#local _AbsFullBitsVal=0;
#else
#local _AbsFullBitsVal=((abs(_value)/_range)*pow(2,56));
#end
#declare _Ary[_i][_j][0] = bitwise_and( _AbsFullBitsVal ,255)/255;
#declare _Ary[_i][_j][1] = bitwise_and((_AbsFullBitsVal/pow(2, 8)),255)/255;
#declare _Ary[_i][_j][2] = bitwise_and((_AbsFullBitsVal/pow(2,16)),255)/255;
#declare _Ary[_i][_j][3] = bitwise_and((_AbsFullBitsVal/pow(2,24)),255)/255;
#declare _Ary[_i][_j][4] = bitwise_and((_AbsFullBitsVal/pow(2,32)),255)/255;
#declare _Ary[_i][_j][5] = bitwise_and((_AbsFullBitsVal/pow(2,40)),255)/255;
#declare _Ary[_i][_j][6] = bitwise_and((_AbsFullBitsVal/pow(2,48)),255)/255;
#declare _Ary[_i][_j][7] = bitwise_and((_AbsFullBitsVal/pow(2,56)),255)/255;
#end

//---------------------------------------------------------------------------
#version ARRAYCOUPLEDDF3S_INC_TEMP;
#end
</pre>

User:Wfpokorny

2016-12-04T13:14:06Z

Wfpokorny: Removed text related to fix/unixSimpleDirectMediaLayerMessages merged into 371 master.

=The Playpen=

A bit of documentation for items currently in my POV-Ray playpen.

==Git Branches on github==

I'm maintaining my POV-Ray patches as un-merged github branches to make it easier for me to keep them current
with the POV-Ray master branch. In my own space I occasionally create my own version of POV-Ray which includes
just the branches/patches of mine and others that I want.

Pointers to my active branches follow with the thought some might be generally useful to others in rolling
their own versions of POV-Ray.

===Tune Blob Accuracy===
This just tweaks an internal value in blob.cpp that in my testing of blobs over the past year I've found works better.
I will eventually package up all my blob test cases and open a github issue/pull request, but not there today...

<pre>git pull https://github.com/wfpokorny/povray.git tune/blob_accuracy</pre>

===Density File Pattern Updates===
A three pronged effort to improve .df3 density file pattern support.
<ol>
<li>Improved user documentation.
<li>Additional array coupled df3 creation and read support. Write support exists.
<li>Fixes and extensions for the density file pattern.
</ol>

See: [[User:Wfpokorny/DensityFile| Density File Pattern - proposed documentation updates.]]

<pre>git pull https://github.com/wfpokorny/povray.git feature/newDensityPatternInterpolations</pre>

Pull request #79 on github.

===Allowing image_map use in density block===
A more targeted feature addition to the density feature requested by developers. I use the pigment_map
branch, which includes this image_map support.

<pre>git pull https://github.com/wfpokorny/povray.git feature/image_map_wDensity</pre>

Pull request #82 on github.

===Addition black_hole warp type(s)===
The black_hole warp in master today has just type 0 support so the type is not really documented though the parser picks it up. Further the default sucking black_hole is clamped in movement and it sometimes reaches outside the black_hole range making for interesting effects I've used, but certainly confusing results for any novice. This patch adds a type 1 version of the black_hole warp which duplicates exactly the pushing/inverted form of type 0, but for the sucking form it implements a form more like what folks would expect. The default with this patch is still type 0 so type 1 needs to be specified to use the new type.

<pre>git pull https://github.com/wfpokorny/povray.git feature/newBlack_holeTypes</pre>

Pull request #86 on github.

===Non-portable 32 bit DF3 write capability===
Pull request for this rejected as not portable - and I admit I don't understand the particulars. The feature works for me on linux though and I find it useful so I maintain it for my use.

<pre>git pull https://github.com/wfpokorny/povray.git feature/nonPortable32bitDF3Write</pre>

===Both image_map and pigment_map support in density block===
Lets one use both image_map and pigment_map in density{} as a way to quickly get full color density/media.

<pre>git pull https://github.com/wfpokorny/povray.git feature/pigment_map_wDensity</pre>

===Unix file and console column wrap control by environment variable===
Enabling control of the wrapping via environment variables of
POVRAY_CONSOLE_COLUMNS for the console and POVRAY_TEXTSTREAM_COLUMNS
for files and console.

Note. There is an active pull req #117 approaching this issue in another way.

<pre>git pull https://github.com/wfpokorny/povray.git feature/unixConsoleFileColumnWrapControl</pre>

===Fix. Rejected parser check for subsurface crash/non-function issue #122===
Missing or mis-placed subsurface definition in global block can cause crash or give the indication the
subsurface feature is working when it is not. I run with this parser hack as protection pending
a more complete fix.

<pre>git pull https://github.com/wfpokorny/povray.git fix/subsurfaceCrash_Issue122_FS306</pre>

==How to merge branches into a custom version of POV-Ray==
Given you've already installed git and have an active local fork of POV-Ray master branches can be merged on linux with:

<pre>
git checkout master
git branch povraySpecial
git checkout povraySpecial
git pull https://github.com/wfpokorny/povray.git fix/unixSimpleDirectMediaLayerMessages
... Usual prebuild.sh, configure and make ...
</pre>

==Incomplete section==

[[User:Wfpokorny/HowTo| How to get sub page...]]

User:Wfpokorny

2016-11-27T15:25:01Z

Wfpokorny: Formatting & typos.

=The Playpen=

A bit of documentation for items currently in my POV-Ray playpen.

==Git Branches on github==

I'm maintaining my POV-Ray patches as un-merged github branches to make it easier for me to keep them current
with the POV-Ray master branch. In my own space I occasionally create my own version of POV-Ray which includes
just the branches/patches of mine and others that I want.

Pointers to my active branches follow with the thought some might be generally useful to others in rolling
their own versions of POV-Ray.

===Tune Blob Accuracy===
This just tweaks an internal value in blob.cpp that in my testing of blobs over the past year I've found works better.
I will eventually package up all my blob test cases and open a github issue/pull request, but not there today...

<pre>git pull https://github.com/wfpokorny/povray.git tune/blob_accuracy</pre>

===Density File Pattern Updates===
A three pronged effort to improve .df3 density file pattern support.
<ol>
<li>Improved user documentation.
<li>Additional array coupled df3 creation and read support. Write support exists.
<li>Fixes and extensions for the density file pattern.
</ol>

See: [[User:Wfpokorny/DensityFile| Density File Pattern - proposed documentation updates.]]

<pre>git pull https://github.com/wfpokorny/povray.git feature/newDensityPatternInterpolations</pre>

Pull request #79 on github.

===Allowing image_map use in density block===
A more targeted feature addition to the density feature requested by developers. I use the pigment_map
branch, which includes this image_map support.

<pre>git pull https://github.com/wfpokorny/povray.git feature/image_map_wDensity</pre>

Pull request #82 on github.

===Addition black_hole warp type(s)===
The black_hole warp in master today has just type 0 support so the type is not really documented though the parser picks it up. Further the default sucking black_hole is clamped in movement and it sometimes reaches outside the black_hole range making for interesting effects I've used, but certainly confusing results for any novice. This patch adds a type 1 version of the black_hole warp which duplicates exactly the pushing/inverted form of type 0, but for the sucking form it implements a form more like what folks would expect. The default with this patch is still type 0 so type 1 needs to be specified to use the new type.

<pre>git pull https://github.com/wfpokorny/povray.git feature/newBlack_holeTypes</pre>

Pull request #86 on github.

===Non-portable 32 bit DF3 write capability===
Pull request for this rejected as not portable - and I admit I don't understand the particulars. The feature works for me on linux though and I find it useful so I maintain it for my use.

<pre>git pull https://github.com/wfpokorny/povray.git feature/nonPortable32bitDF3Write</pre>

===Both image_map and pigment_map support in density block===
Lets one use both image_map and pigment_map in density{} as a way to quickly get full color density/media.

<pre>git pull https://github.com/wfpokorny/povray.git feature/pigment_map_wDensity</pre>

===Unix file and console column wrap control by environment variable===
Enabling control of the wrapping via environment variables of
POVRAY_CONSOLE_COLUMNS for the console and POVRAY_TEXTSTREAM_COLUMNS
for files and console.

Note. There is an active pull req #117 approaching this issue in another way.

<pre>git pull https://github.com/wfpokorny/povray.git feature/unixConsoleFileColumnWrapControl</pre>

===Fix. Rejected parser check for subsurface crash/non-function issue #122===
Missing or mis-placed subsurface definition in global block can cause crash or give the indication the
subsurface feature is working when it is not. I run with this parser hack as protection pending
a more complete fix.

<pre>git pull https://github.com/wfpokorny/povray.git fix/subsurfaceCrash_Issue122_FS306</pre>

===Fix. Improved unix Simple DirectMedia Layer messages===
See pull req or commit message for more information.

<pre>git pull https://github.com/wfpokorny/povray.git fix/unixSimpleDirectMediaLayerMessages</pre>

Pull request #109 on github.

==How to merge branches into a custom version of POV-Ray==
Given you've already installed git and have an active local fork of POV-Ray master branches can be merged on linux with:

<pre>
git checkout master
git branch povraySpecial
git checkout povraySpecial
git pull https://github.com/wfpokorny/povray.git fix/unixSimpleDirectMediaLayerMessages
... Usual prebuild.sh, configure and make ...
</pre>

==Incomplete section==

[[User:Wfpokorny/HowTo| How to get sub page...]]

User:Wfpokorny

2016-11-27T15:18:52Z

Wfpokorny: Some initial documentation for my active git branches.

=The Playpen=

A bit of documentation for items currently in my POV-Ray playpen.

==Git Branches on github==

I'm maintaining my POV-Ray patches as un-merged github branches to make it easier for me to keep them current
with the POV-Ray master branch. In my own space I occasionally create my own version of POV-Ray which includes
just the branches/patches of mine and others that I want.

Pointers to my active branches follow with the thought some might be generally useful to others in rolling
their own versions of POV-Ray.

===Tune Blob Accuracy===
This just tweaks an internal value in blob.cpp that in my testing of blobs over the past year I've found works better.
I will eventually package up all my blob test cases and open a github issue/pull request, but not there today...

<code>git pull https://github.com/wfpokorny/povray.git tune/blob_accuracy</code>

===Density File Pattern Updates===
A three pronged effort to improve .df3 density file pattern support.
<ol>
<li>Improved user documentation.
<li>Additional array coupled df3 creation and read support. Write support exists.
<li>Fixes and extensions for the density file pattern.
</ol>

See: [[User:Wfpokorny/DensityFile| Density File Pattern - proposed documentation updates.]]

<code>git pull https://github.com/wfpokorny/povray.git feature/newDensityPatternInterpolations</code>

Pull request #79 on github.

===Allowing image_map use in density block===
A more targeted feature addition to the density feature requested by developers. I use the pigment_map
branch, which includes this image_map support.

<code>git pull https://github.com/wfpokorny/povray.git feature/image_map_wDensity</code>

Pull request #82 on github.

===Addition black_hole warp type(s)===
The black_hole warp in master today has just type 0 support so the type is not really documented though the parser picks it up. Further the default sucking black_hole is clamped in movement and it sometimes reaches outside the black_hole range making for interesting effects I've used, but certainly confusing results for any novice. This patch adds a type 1 version of the black_hole warp which duplicates exactly the pushing/inverted form of type 0, but for the sucking form it implements a form more like what folks would expect. The default with this patch is still type 0 so type 1 needs to be specified to use the new type.

<code>git pull https://github.com/wfpokorny/povray.git feature/newBlack_holeTypes</code>

Pull request #86 on github.

===Non-portable 32 bit DF3 write capability===
Pull request for this rejected as not portable - and I admit I don't understand the particulars. The feature works for me on linux though and I find it useful so I maintain it for my use.

<code>git pull https://github.com/wfpokorny/povray.git feature/nonPortable32bitDF3Write</code>

===Both image_map and pigment_map support in density block===
Lets one use both image_map and pigment_map in density{} as a way to quickly get full color density/media.

<code>git pull https://github.com/wfpokorny/povray.git feature/pigment_map_wDensity</code>

===Unix file and console column wrap control by environment variable===
Enabling control of the wrapping via environment variables of
POVRAY_CONSOLE_COLUMNS for the console and POVRAY_TEXTSTREAM_COLUMNS
for files and console.

Note. There is an active pull req #117 approaching this issue in another way.

<code>git pull https://github.com/wfpokorny/povray.git feature/unixConsoleFileColumnWrapControl</code>

===Fix. Rejected parser check for subsurface crash/non-function issue #122===
Missing or mis-placed subsurface definition in global block can cause crash or give the indication the
subsurface feature is working when it is not. I run with this parser hack as protection pending
a more complete fix.

<code>git pull https://github.com/wfpokorny/povray.git fix/subsurfaceCrash_Issue122_FS306</code>

===Fix. Improved unix Simple DirectMedia Layer messages===
See pull req or commit message for more information.

<code>git pull https://github.com/wfpokorny/povray.git fix/unixSimpleDirectMediaLayerMessages</code>

Pull request #109 on github.

==How to merge branches into a custom version of POV-Ray==
Given you've already installed git and have an active local fork of POV-Ray master branches can be merged on linux with:

<pre>
git checkout master
git branch povraySpecial
git checkout povraySpecial
git pull https://github.com/wfpokorny/povray.git fix/unixSimpleDirectMediaLayerMessages
... Usual prebuild.sh, configure and make ...
</pre>

==Incomplete section==

[[User:Wfpokorny/HowTo| How to get sub page...]]

HowTo:Use conditional structures

2016-11-23T13:30:51Z

Wfpokorny: Moved nested loop example to new for_over_while howto. Fixed light color warning on move.

Conditional constructs in POV-Ray are scripting features which perform different computations or actions depending on whether a condition evaluates to true or false.

==The #if, #else, #end construct==
The simplest conditional directive is the #if directive. This evaluates an expression, which must evaluate to a floating point number (often an integer value). This floating point number is interpreted as a boolean value, that is to say that if the expression evaluates to '0', it is considered 'false' and if it evaluates to anything else it is considered 'true'. If the condition is true then directives between the #if statement and a corresponding #else or #end statement are evaluated.
Note: extremely small values of about 1e-10 are considered zero (false) as a result of floating point number accuracy limits.

The #else directive is optional but, if specified and the conditional expression was false, then directives between the #else and the corresponding #end statement are evaluated.

For example:

<source lang=pov>
#declare CameraDistance=25.8;

... Definition of some complex object that looks like a sphere at great distances. ...

#if (CameraDistance>100)
sphere { <0,0,0>, 1.2 pigment {rgb 1}}
#else
object {MyComplexObject}
#end
</source>

Here the 'greater than' comparitive operator '>' is used to see whether the value of the CameraDistance variable is greater than 100. In this example, the expression 'CameraDistance>100' evaluates to 0 ('false') because the CameraDistance variable is less than 100.

===Conditional Conjunctions ===
You can combine conditional terms to build more complex conditional expressions using '&' (And), '|' (Or) and '!' (Not). Use brackets to control the sequence of evaluation. You can also use POV-Ray functions within terms so long as they can be resolved to numeric values. The built-in float identifiers on, off, yes, no, true, and false are designed for use as boolean constants and simply evaluate to 0 (off, no and false) or 1 (on, yes and true).

Here's an example that might take a little thinking about:
<source lang=pov>
#declare Clothing="Jeans";
#declare JeansPermitted=false;
// Check to see if Jeans are permitted
#if (strcmp(Clothing,"Jeans")=0 & !JeansPermitted)
#debug "Sorry. Jeans are not permitted\n"
#end
</source>

In this example, the strcmp function returns a zero because there is no difference between the two strings it has compared.
The term 'strcmp(Clothing,"Jeans")=0' therefore returns a 1 (this term is true). The '!' (Not) symbol is used to check for the condition where jeans are not permitted. The '&' symbol is used to combine the two and to therefore test for the condition where Clothing is "Jeans" and jeans are not permitted.

As you've probably realised, there are many ways of expressing the same thing with conditional expressions and the art is in writing it in a way that is clear enough that you will understand it when you read it through again later. It can help to write the condition out as a comment before you build it into an expression. Leaving the comment in place helps anyone reading it later.

== The #ifdef and #ifndef, #else and #end constructs ==

The #ifdef and #ifndef statements can be used to determine whether or not an identifier has been defined and to conditionally execute statements. If the identifier passed to the #ifdef directive exists then the statements between the #ifdef statement and a corresponding #else or #end statement are evaluated. The #else directive is optional but, if specified and the identifier passed to the #ifdef directive does not exist, then directives between the #else and the corresponding #end statement are evaluated.

These statements can help to trap potential errors in a scene file or to set default values.

For example:

<source lang=pov>
#infdef(ObjectHeight) #declare ObjectHeight=1; #end
</source>

==The #switch, #case, #range and #break Directives==
The #switch directive provides another way of specifying conditional expressions but allows you to handle a succession of conditions as defined by a #case clause or a #range clause. This directive can seem a little daunting compared to using one or more #if directives, but there are some powerful ways of using it. Like the #if directive it uses float values rather than boolean, so two values whose difference is less than 1e-10 are considered equal.

This trivial example illustrates a number of basic points about the #switch directive.
<ul>
<li>If a #case or #range clause is not a match it skips to the next one, ignoring everything else in between.
<li>If a #break is encountered within a matching #case or #range clause the #switch directive stops processing further lines, causing an immediate jump to the #end without processing subsequent sections, even if a subsequent condition would also have been satisfied.
<li>When processing a matching #case or #range clause, if a #break is not encountered it continues through successive #case statements whether they match or not.
</ul>

Although it doesn't contain a camera or any objects, the following example is a complete scene file. When you render it it'll generate a black image, but you'll be able to view the text that it writes out in the message stream.

<source lang="pov">
#declare MyVariable = 5.2;
#debug concat("MyVariable: ",str(MyVariable,3,3),"\n")
#switch (MyVariable)
#case (0)
#debug "As close to nothing as makes a tiny difference.\n"
#break
#case (1)
#case (2)
#case (3)
#case (5)
#case (7)
#debug "A Prime number between 1 and 10 (actually within 1e-10 of a prime).\n"
#break
#range (0,10)
#debug "A number between 1 and 10 that is not within 1e-10 of a Prime number\n"
#break
#range (10,100)
#debug "A number between 10 and 100 (actually 10+(1e-10) to 100+(1e-10)).\n"
#break
#else
#debug "Everything else.\n"
#debug "ie. Less than zero or greater than 100.\n"
#end
</source>

If the parameter to a #case clause matches the parameter to the #switch clause then everything up to the next #break, #else or #end clause is evaluated. Similarly, if the parameter to the #switch clause is between the minimum and maximum values of a #range clause then everything up to the next #break, #else or #end clause is evaluated.

If you are interested, you can explore the sensitivity to the accuracy of the floating point number comparison by setting a value using 'e' as follows:

<source lang="pov">
#declare MyVariable = 5+(0.5e-10);
or
#declare MyVariable = 5+(1.5e-10);
</source>

===Using #switch with text values===
The #switch, #case and #range clauses accept parameters that evaluate to float numbers. This includes the strcmp function which compares two strings and returns a zero if two strings match. By turning the #switch clause on its head a little, you can therefore use it with strings. Using the #switch directive with text can be particularly handy when writing macros that can generate an object in a large number of differently styles, because you can give each style a name and set parameters based on the name of the style specified.

Example of using #switch with text:

<source lang="pov">
#declare MyVariable = "Ostrich";
#switch (0)
#case (strcmp(strupr(MyVariable),"DOG"))
#debug "Dog, DOG, or dog.\n"
// Settings to be used for a dog
#break
#case (strcmp(strupr(MyVariable),"CAT"))
#debug "Cat, CAT, or cat.\n"
// Settings to be used for a cat
#break
#case (strcmp(strupr(MyVariable),"OSTRICH"))
#debug "Ostrich, OSTRICH, or ostrich.\n"
// Settings to be used for an ostrich
#break
#else
#debug "Not a dog, cat or ostrich.\n"
// Stuff to do if an unexpected creature was encountered.
#end
</source>

Note that the strupr function is used to remove case sensitivity.

The following example illustrates the use of multiple #case clauses for a set of associated conditions to work out how many legs an animal has:

<source lang="pov">
#declare Animal = "Ostrich";
#switch (0)
#case (strcmp(strupr(Animal),"DOG"))
#case (strcmp(strupr(Animal),"CAT"))
#case (strcmp(strupr(Animal),"RHINOCEROS"))
#case (strcmp(strupr(Animal),"TABLE"))
#declare LegCount = 4;
#break
#case (strcmp(strupr(Animal),"OSTRICH"))
#case (strcmp(strupr(Animal),"DUCK"))
#declare LegCount = 2;
#break
#case (strcmp(strupr(Animal),"WORM"))
#case (strcmp(strupr(Animal),"DOLPHIN"))
#declare LegCount = 0;
#break
#else
#declare LegCount = -1; // Unknown
#end

#debug concat("Animal: ",Animal,"\n")
#if (LegCount<0) #debug "Number of Legs Unknown\n"
#else #debug concat("Number of Legs: ",str(LegCount,3,0),"\n")
#end
</source>

You can also test for abbreviations using the following construct:

<source lang="pov">
#case (strcmp(strupr(Animal),substr("RHINOCEROS",1,strlen(Animal))))
</source>

This would match 'Rhino' or 'Rhinoceros', but you clearly need to be a little careful with this as it would also match 'Rhinoc', 'R' and <nowiki>''</nowiki>. To set a minimum abbreviation length use the max function:

<source lang="pov">
#case (strcmp(strupr(Animal),substr("RHINOCEROS",1,max(strlen(Animal),5))))
</source>

This would match 'Rhino', 'Rhinoceros' and everything in between, but not 'R', 'Rhin' or <nowiki>''</nowiki>.

== The #while, #end construct (Loops) ==
See also - [[HowTo:Use_macros_and_loops]].

The #while, #end construct encapsulates a sequence of POV-Ray statements that are repeatedly executed for as long as the conditional expression specified is true. The conditional expression can be simple or complex and adheres to the same rules as apply to the #if statement described above.

As with the #if statement, the conditional expression must evaluate to a floating point number (often an integer value). This floating point number is interpreted as a boolean value, that is to say that if the expression evaluates to '0', it is considered 'false' and if it evaluates to anything else it is considered 'true'. If the condition is true then directives between the #while statement and a corresponding #end statement are evaluated. The conditional expression is then re-evaluated and, if still true the directives between the #while statement and the corresponding #end statement are repeated.

The statements repeat in a loop until the condition evaluates to false. It is up to you to control the loop by defining a suitable condition that will not loop indefinitely. If the condition never evaluates to false then the program will continue to evaluate the statements forever, until you hit the stop button, until the memory of your computer is exhausted or until you terminate the application (whichever happens first) see [[Wikipedia:Infinite_loop]].

Note: extremely small values of about 1e-10 are considered zero (false) as a result of floating point number accuracy limits.

Here is an example of a simple loop:

<source lang=pov>
#declare Count=0;
#while (Count < 5)
object { MyObject translate x*3*Count }
#declare Count=Count+1;
#end
</source>
This example places five copies of MyObject in a row spaced three units apart in the x-direction.

As described above (for the #if statement), you can combine conditional terms to build more complex looping conditional expressions using '&' (And), '|' (Or) and '!' (Not).

HowTo:Use for loop over traditional while loop

2016-11-23T13:27:53Z

Wfpokorny: Adding content for howto for loop over while loop.

===Loops===
Traditionally in POV-Ray the <code>#while</code> directive has been the way to implement loops. In 3.7 a new <code>#for</code> directive was added that makes coding counting loops much simpler.

===Nested Loops===
Loops can of course be nested. This capability is often used to lay out very large numbers of objects using an economical amount of code.

First, here's a very simple, complete scene file containing a nested <code>#while</code> loop with which you can play:

<source lang=pov>
#include "colors.inc"
#include "woods.inc"

camera {location <-1.5,0.9,-0.08> look_at <0,0.7,0.5>}
light_source {<-20,75,-100> White}
background {LightBlue}
plane {y,0 pigment {color GreenYellow}

#declare RandomSeed = seed(1);
#declare XCount=0;
#while (XCount < 200)
#declare ZCount=0;
#while (ZCount < 200)
box {<-0.05,0,-0.05><0.05,1,0.05>
rotate <3*rand(RandomSeed),5*rand(RandomSeed),3*rand(RandomSeed)>
texture {T_Wood1 translate <rand(RandomSeed),ZCount,rand(RandomSeed)> rotate x*90 scale 0.07}
translate <XCount,0,ZCount>
}
#declare ZCount=ZCount+1;
#end
#declare XCount=XCount+1;
#end
</source>

Here's the same looping accomplished with the new <code>#for</code> loop directive:

<source lang=pov>
#include "colors.inc"
#include "woods.inc"

camera {location <-1.5,0.9,-0.08> look_at <0,0.7,0.5>}
light_source {<-20,75,-100> White}
background {LightBlue}
plane {y,0 pigment {color GreenYellow}

#declare RandomSeed = seed(1);
#for (XCount,0,199)
#for (ZCount,0,199)
box {<-0.05,0,-0.05><0.05,1,0.05>
rotate <3*rand(RandomSeed),5*rand(RandomSeed),3*rand(RandomSeed)>
texture {T_Wood1 translate <rand(RandomSeed),ZCount,rand(RandomSeed)> rotate x*90 scale 0.07}
translate <XCount,0,ZCount>
}
#end
#end
</source>

These example uses 2 nested loops. Each nested loop has its own control variable. It starts with both XCount and YCount equal to zero. With XCount at zero, YCount loops from 0 to 199, then XCount is incremented to 1, YCount is reset to zero and the second loop repeats.

This example also introduces a degree of randomness in each iteration using the POV-Ray seed and rand functions. When generating a large number of objects using loops you'll find that a little randomness goes a long way. This example generates 40,000 wooden posts, each with a little bit of a wobble and each with a slightly different wood texture pattern. It should take about 10 or 20 seconds to render

HowTo:Contents

2016-11-23T13:06:21Z

Wfpokorny: Adding hook for for loop article.

The following is a list of the currently-available 'How To' articles. If you add a new article, please list it here.

Please also read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

==Suggestions==

It would be handy if some users co-operated in working out a 'wishlist' of articles and a hierarchy for them, and then created the links to the empty pages from this page.

Discussions should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Completed articles==

*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]
*[[HowTo:Use for loop over traditional while loop | How to: Use for loop over traditional while loop]]

==Work-in-Progress Articles==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use rainbow | How to: Use rainbow]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

==== Working with POV-Ray ====
Platform-specific tips to get the most out of POV-ray:
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

=====POV-Ray for Mac OS / Mac OS X=====

=====POV-Ray for Unix=====

====Building Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#General POV-Ray troubleshooting | General POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

====General POV-Ray troubleshooting====
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*[[Installation#Troubleshooting | Installation Troubleshooting]]
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests|How to make a feature request]]

HowTo:Known Issues

2016-11-21T11:56:40Z

Wfpokorny: Misc

===Known Issues===
Quick list of general known issues with the version 3.7 and the 3.7.1 pre-release:
<ol>
<li>Unix users. Due to problems with X11 window libraries, some special command line parameters, such as -geometry, are not available. These were previously enabled via X11 itself. However, a preview display can still be enabled if building from source and the optional [http://www.libsdl.org SDL Simple Directmedia Layer (V1.2)] development library is available to link against.</li>
<li>While utf-8 support is available in scene files, there are still issues with file names using non-ASCII characters. Meaning a user running in utf-8 or equivalent must take care to use only ASCII characters for all scene related file and directory names. See: [https://github.com/POV-Ray/povray/issues/152 github issue 152]</li>
<li>Agressive Anti-Aliasing (AA) usually addresses bright and dark speckles sometimes seen with media where rays glance - tangentially - to a mathematical surface in a way which confuses interval determination for sampling. Further, while using 'sturm on' is usually a help, it tends to make such media speckling worse. Search the newsgroups for more detail.</li>
</ol>

The developer's issue tracking can be found at [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]

HowTo:Contents

2016-11-19T20:00:26Z

Wfpokorny: Removed histogram item given support was dropped in 3.7.

The following is a list of the currently-available 'How To' articles. If you add a new article, please list it here.

Please also read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

==Suggestions==

It would be handy if some users co-operated in working out a 'wishlist' of articles and a hierarchy for them, and then created the links to the empty pages from this page.

Discussions should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Completed articles==

*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

==Work-in-Progress Articles==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use rainbow | How to: Use rainbow]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

==== Working with POV-Ray ====
Platform-specific tips to get the most out of POV-ray:
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

=====POV-Ray for Mac OS / Mac OS X=====

=====POV-Ray for Unix=====

====Building Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#General POV-Ray troubleshooting | General POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

====General POV-Ray troubleshooting====
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*[[Installation#Troubleshooting | Installation Troubleshooting]]
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests|How to make a feature request]]

HowTo:Known Issues

2016-11-19T13:36:25Z

Wfpokorny: Adding blurb about media bright/dark speckling.

===Known Issues===
Quick list of general known issues with the version 3.7 and the 3.7.1 pre-release:
<ol>
<li>Due to problems with X11 libraries, some special command line parameters are not available which were previously enabled via X11 are not available. However, a preview display can still be enabled if building from source and the optional [http://www.libsdl.org SDL Simple Directmedia Layer (V1.2)] development library is available to link against.</li>
<li>While utf-8 support is available in scene files, there are still issues with file names using non-ASCII characters. Meaning a user running in utf-8 or equivalent must take care to use only ASCII characters for all scene related file and directory names. See: [https://github.com/POV-Ray/povray/issues/152 github issue 152]</li>
<li>Agressive Anti-Aliasing (AA) usually addresses bright and dark speckles sometimes seen with media where rays glance - tangentially - to a mathematical surface in a way which confuses interval determination for sampling. Further, while using 'sturm on' is usually a help, it tends to make such media speckling worse. Search the newsgroups for more detail.</li>
</ol>

The developer's issue tracking can be at [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]

HowTo:Known Issues

2016-11-19T13:18:22Z

Wfpokorny: Adding some items to the know issues entry.

===Known Issues===
Quick list of general known issues with the version 3.7 and the 3.7.1 pre-release:
<ol>
<li>Due to problems with X11 libraries, some special command line parameters are not available which were previously enabled via X11 are not available. However, a preview display can still be enabled if building from source and the optional [http://www.libsdl.org SDL Simple Directmedia Layer (V1.2)] development library is available to link against.</li>
<li>While utf-8 support is available in scene files, there are still issues with file names using non-ASCII characters. Meaning a user running in utf-8 or equivalent must take care to use only ASCII characters for all scene related file and directory names. See: [https://github.com/POV-Ray/povray/issues/152 github issue 152]</li>
</ol>

The developer's issue tracking can be at [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]

HowTo:Contents

2016-11-19T12:58:09Z

Wfpokorny: /* General POV-Ray troubleshooting */

The following is a list of the currently-available 'How To' articles. If you add a new article, please list it here.

Please also read our '''[[Help:Editing_Guidelines|Editing Guidelines]]''' prior to creating any articles.

==Suggestions==

It would be handy if some users co-operated in working out a 'wishlist' of articles and a hierarchy for them, and then created the links to the empty pages from this page.

Discussions should be held on the [[HowTo_Talk:Contents|talk]] page, not here.

==Completed articles==

*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

==Work-in-Progress Articles==

====Animating your creations====
*[[HowTo:Create animations | How to: Create animations]]
*[[HowTo:Create more complex animations | How to: Create more complex animations]]
*[[HowTo:Animation pitfalls | How to: Animation pitfalls]]
*[[HowTo:Encode animations as Ogg Theora Video | How to: Encode animations as Ogg Theora Video]] (A non-proprietary video file format)

====Objects====
*[[HowTo:Use constructive solid geometry | How to: Use constructive solid geometry]]
*[[HowTo:Use the blob object | How to: Use the blob object]]
*[[HowTo:Use the isosurface object | How to: Use the isosurface object]]
*[[HowTo:Use the lathe object | How to: Use the lathe object]]
*[[HowTo:Use the plane object | How to: Use the plane object]]
*[[HowTo:Use spline and bezier curves | How to: Use spline and bezier curves]]

====Texturing====
*[[HowTo:Use UV-mapping | How to: Use UV-mapping]]
*[[HowTo:Use an image as a texture | How to: Use an image as a texture]]
*[[HowTo:Turn a continuous function into a stepped function | How to: Turn a continuous function into a stepped function]]

====Lighting====
*[[HowTo:Make soft shadows using the area_light | How to: Make soft shadows using the area_light]]
*[[HowTo:Use radiosity | How to: Simulate real-world ambient light]]
*[[HowTo:Use photons | How to: Simulate real-world optical effects]]
*[[HowTo:Make realistic outdoor lighting | How to: Make realistic outdoor lighting]]
*[[HowTo:Make realistic indoor lighting | How to: Make realistic indoor lighting]]

====Special effects in POV-Ray====
*[[HowTo:Use fog and media | How to: Use fog and media]]
*[[HowTo:Use rainbow | How to: Use rainbow]]
*[[HowTo:Use photons | How to: Use photons]]
*[[HowTo:Use radiosity | How to: Use radiosity]]
*[[HowTo:Use sky_sphere and background | How to: Use sky_sphere and background]]
*[[HowTo:Fix old scenes to work with the new gamma system | How to: Fix old scenes to work with the new gamma system]]
*[http://www.ldraw.org/Article528.html How to: Render LDraw scenes for polarized glasses] (off site, needs to be re-written in more general terms that are not LDraw-specific)
*[[HowTo:Manual focal blur | How to create focal blur manually]]

====Special output in POV-Ray====
*[[HowTo:Create anaglyph images | How to: Create anaglyph images]]
*[[HowTo:High precision heightfields | How to: Create high precision heightfields using POV-Ray]]
*[[HowTo:Create images for use as a heightfield | How to: Create images for use as a heightfield]]
*[[HowTo:Create multi-phase web buttons | How to: Create multi-phase web buttons]]
*[[HowTo:ODS | How to: Create omnidirectional stereo (ODS) images]]
*[[HowTo:Utilize the histogram | How to: Utilize the histogram]]

====Special input in POV-Ray====
*[[HowTo:Use SVG images as the basis for prisms and lathes | How to: Use SVG images as the basis for prisms and lathes]]

==== Working with POV-Ray ====
Platform-specific tips to get the most out of POV-ray:
*[[HowTo:Install multiple versions of POV-Ray | How to: Install multiple versions of POV-Ray]]
*[[HowTo:Configure your favorite text editor to work with POV-Ray| How to: Configure your favorite text editor to work with POV-Ray]]

=====POV-Ray for Microsoft Windows=====
*[[HowTo:Take full advantage of the Insert menu | How to: Take full advantage of the Insert menu]]

=====POV-Ray for Mac OS / Mac OS X=====

=====POV-Ray for Unix=====

====Building Scenes in POV-Ray====
*[[HowTo:Build a basic scene | How to: Build a basic scene]]
*[[HowTo:Plan your scenes | How to: Plan your scenes]]
*[[HowTo:Place objects on another object | Place objects on another object]]

====Scene Description Language====
*[[HowTo:Manage your variables | How to: Manage your variables]]
*[[HowTo:Use conditional structures | How to: Use conditional structures]]
*[[HowTo:Use macros and loops | How to: Use macros and loops]]

====Troubleshooting your scene====
This section is for figuring out why your scene isn't rendering as expected. For problems related to installation or removal of POV-Ray, updates, crashes, or other software-related issues, see [[#General POV-Ray troubleshooting | General POV-Ray troubleshooting]].
*[[HowTo:Fix unexpected image output | Why is my image completely black?]]
*[[HowTo:Fix unexpected invisibility#Objects | Why aren't all of my objects showing up?]]
*[[HowTo:Fix unexpected invisibility#Media | Why doesn't my fog or other media show up?]]
*[[HowTo:Fix artifacts#Coincident surfaces | What are all of these weird speckles on my object?]]
*[[HowTo:Fix artifacts#Isosurfaces | What is the best way to fix holes in my isosurface?]]
*[[HowTo:Fix artifacts#Floating-point expressions | Why are my expressions not evaluating to 1 (or some other integer)?]]

====General POV-Ray troubleshooting====
This section is for software problems with POV-Ray. If you are trying to figure out why your scene isn't rendering as expected, see [[HowTo:Contents#Troubleshooting your scene|Troubleshooting Your Scene]].
*[[Installation#Troubleshooting | Installation Troubleshooting]]
*[[HowTo:Known Issues | Known Issues and Possible Work-arounds]]
*[[HowTo:Make A Bug Report | How to make a Bug Report]]
*[[HowTo:POV-Ray Feature Requests|How to make a feature request]]

HowTo:POV-Ray Feature Requests

2016-11-19T12:39:35Z

Wfpokorny: Updating this section for github issues over our older FlySpray issue tracker.

We all want to see POV-Ray improved, and from time to time it may occur to us that there's a feature that we would like to see, or something we'd like to see improved. The proper place for "feature wishlists" is the bugtracking and feature-request system on [https://github.com/POV-Ray/povray/issues Github], as that's ''the'' primary place where the developers will look for them.

Note: We are in the process of porting issues still open in our previous [http://bugs.povray.org/ FlySpray System] to the new
[https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. During this transition it is necessary to review both systems to know if a feature equest has already been made known to the developers. Please open all new requests in the [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. If a FlySpray issue is marked as 'tracked on github' please make any further comments or updates on github.

When ''making'' feature requests, a word of advice:

Please ''do'' read [[HowTo:Make A Bug Report]] and [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively] before submitting any entries to the issue tracker, and ''do'' heed the advice presented there. By following those rules - or at least keeping them in mind as you file issues - you make life a lot easier for the people you hope to address the issues.

Some other points raised in [http://news.povray.org/povray.advanced-users/thread/%3C4c1d52c5%241%40news.povray.org%3E/] and [http://news.povray.org/povray.general/thread/%3C4c09591e%241%40news.povray.org%3E/]:

* If discussion of a feature request has resulted in a summary or conclusion that differs from the original request, a new feature request should not be made. Instead, the existing one should be changed. This implies contributing ideas to the feature request discussion, and then coming up with a single coherent idea, not leaving it at two half-finished ideas.
* Closely-related feature requests should be grouped together; e.g. requests for Windows UI enhancements with respect to the editor such as "Delete", "Reload" and "Rename" commands could reasonably be put into a single request (all at once or via editing a bug later).
* There is a feature to allow other users and/or developers to comment on bugs & feature requests on github, but this is primarily intended for providing additional information, or feedback on the current status. For proper discussions, it lacks the necessary publicity. (When was the last time anyone just browsed the github just to see if there was some interesting discussion going on in some of the entries?) The POV-Ray community is strongest in the newsgroups. That said, the problem with ''discussions'' about feature requests is that they tend to have ''no'' clear-cut result whatsoever, as they tend do be free brainstorming sessions - unless there's someone with the necessary will and authority (e.g. because he has started the discussion in the first place) "driving" the discussion to a proper conclusion (ideally by summarizing the discussion and result in a proper place). In situations like these, github excels.
* A sensible rule for opening a new feature request might then be that it must be discussed in the newsgroups first, to weed out crackpot ideas and to refine ideas by feedback from what users actually need. After discussion, the request should only be entered if a member of the POV-Ray team deems the request reasonable (note that a request should not be deemed unreasonable at this point just because it would be too much effort to implement right now).
* Excessive use/misuse of the newsgroups and github may be considered "vandalism".

HowTo:Make A Bug Report

2016-11-19T12:25:35Z

Wfpokorny: Updating this section for github issues over our older FlySpray issue tracker.

===== Reporting bugs in POV-Ray =====
Bug reports are an essential part of development, and the developers need you to let them know about programming defects in POV-Ray. However, there are a few things that you need to keep in mind when you are thinking about submitting a bug report or requesting a new feature. Please take a few moments to read this brief list of guidelines ''before'' you open a new task in our [https://github.com/POV-Ray/povray/issues Github Issue Tracking System].

Note: We are in the process of porting issues still open in our previous [http://bugs.povray.org/ FlySpray Bug Reporting System] to the new
[https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. During this transition it is necessary to review both systems to know if an issues has already been made known to the developers. Please open all new issues in the [https://github.com/POV-Ray/povray/issues Github Issue Tracking System]. If a FlySpray issue is marked as 'tracked on github' please make any further comments or updates on github.

===== Guidelines for opening new tasks =====
* Take some minutes of your time and read [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html this] document, it will teach you how to report a bug correctly.
* If you're not sure it's a bug, or how to report it, chat with the folks in the [http://news.povray.org/povray.beta-test/ beta-test forum].
* We cannot accept bug reports for modified versions of POV-Ray.
* In almost all cases where a rendering bug is being reported, we require a minimal sample scene causing the bug be submitted, as well as an image showing the problem.
* Always perform a search on '''both open and closed''' 'issues' or 'tasks' before opening a new one. Your bug might already have been reported, or your feature requested.
* Use the English language in any tasks you open. Nothing will get done if we can't understand you.
* Only report one bug or request one feature per task.
* If you report a bug, and we mark it as 'requires testing', then please test it and add a comment to the task telling us how well it works.
* If a task is closed as fixed then try the [https://github.com/POV-Ray/povray/releases development version] before requesting that it be re-opened.
* If we deny your request to re-open a task, check the history/comments for our reason. If you are unsatisfied with the reason, you are welcome to discuss it in the [http://news.povray.org/ forums].
* Be polite. Remember that you got POV-Ray for free.

===== Text formatting tips =====
Github allows for a lot more formatting within task descriptions and comments. Here are a few helpful essentials:
* To quote some other comment, use the github quote feature after marking the text to be quoted.
* To make code, use the mark code feature of github after marking your code.
* Refer to github issues and pull request by number prefixed with # and github will create the link. Please refer to older Flyspray tasks not yet ported by their numeric id preceded by "<tt>FS#</tt>" (e.g. <tt>FS#123</tt>) and perhaps insert the URL for as github will create the corresponding link.
* Do make use of the preview button.

===== Miscellaneous =====
* To illustrate your bug report or comment with images, test scenes or zip files, please do make use of the "attach file" functionality, rather than linking to some 3rd party image hosting site. This way the uploaded files will remain accessible as long as the github issue persists. Note when uploading scene related files the POV-Ray extensions of .pov and .inc are not supported; needing an additional .txt suffix before upload. Further .tar and .gz files are '''not''' supported as of this writing, but rather only .zip.

==See also==
*[[Knowledgebase:POV-Ray Feature Requests]]

Reference Talk:Tiling Pattern

2016-09-27T14:43:04Z

Wfpokorny: Cleanup. Moved information into tiling.pov example.

Reference Talk:Tiling Pattern

2016-09-25T14:47:14Z

Wfpokorny: Table border to 5px

* Adding a table of unit square normalization scales.

[[Category:Patterns]]
{{#indexentry:tiling, keyword}}
{{#indexentry:tiling, pattern}}
{{#indexentry:keyword, tiling}}
{{#indexentry:pattern, tiling}}
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.
The syntax is as follows:
<pre>
pigment {
tiling Pattern_Number
[PATTERN_MODIFIERS...]
}
</pre>
<table class="centered" width="580px" cellpadding="0" cellspacing="10">
<tr>
<td>[[Image:RefImgTiling2.gif|center|560px]]</td>
</tr>
<tr>
<td>The various tiling patterns annotated by tiling pattern and tiling type respectively</td>
</tr>
</table>

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.

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!

The scale required to fit the core repeated tile into a unit square size for each tiling pattern is given in the table below.

<table class="centered" cellpadding="5" cellspacing="0" border="5" border-collapse="collapse">
<tr>
<th>Tiling Number</th>
<th>Unit square normalization scale</th>
</tr>
<tr><td> 1</td> <td><1,1,1> </td></tr>
<tr><td> 2</td> <td><2/3,1,1/sqrt(3)> </td></tr>
<tr><td> 3</td> <td><1,1,2/sqrt(3)> </td></tr>
<tr><td> 4</td> <td><1,1,2/sqrt(3)> </td></tr>
<tr><td> 5</td> <td><2/3,1,1/sqrt(3)> </td></tr>
<tr><td> 6</td> <td><1/4,1,1/4> </td></tr>
<tr><td> 7</td> <td><1/(sqrt(2)+1),1,1/(sqrt(2)+1)> </td></tr>
<tr><td> 8</td> <td><1,1,1/(sqrt(3)+2)> </td></tr>
<tr><td> 9</td> <td><1/2,1,1/(2*sqrt(3))> </td></tr>
<tr><td>10</td> <td><1,1,1/2> </td></tr>
<tr><td>11</td> <td><1/3,1,1/3> </td></tr>
<tr><td>12</td> <td><1/3,1,1/3> </td></tr>
<tr><td>13</td> <td><1/(sqrt(3)+1),1,1/(sqrt(3)+1)> </td></tr>
<tr><td>14</td> <td><1/(sqrt(3)+1),1,1/(sqrt(3)+1)> </td></tr>
<tr><td>15</td> <td><1/5,1,1/5> </td></tr>
<tr><td>16</td> <td><1/(sqrt(3)+3),1,1/((sqrt(3)+1.0)*2.0)></td></tr>
<tr><td>17</td> <td><1/(sqrt(3)+3),1,1/((sqrt(3)+1.0)*2.0)></td></tr>
<tr><td>18</td> <td><1/4,1,1/4> </td></tr>
<tr><td>19</td> <td><1/2,1,1/((sqrt(3)/2)*3)> </td></tr>
<tr><td>20</td> <td><1/2,1,1/((sqrt(3)/2)*3)> </td></tr>
<tr><td>21</td> <td><1/(1+sqrt(3)),1,1/(1+sqrt(3))> </td></tr>
<tr><td>22</td> <td><1/(2+sqrt(3)),1,1/(3+(2*sqrt(3)))> </td></tr>
<tr><td>23</td> <td><1/(3+sqrt(3)),1,1/(3+(3*sqrt(3)))> </td></tr>
<tr><td>24</td> <td><1/(3+sqrt(3)),1,1/(3+(3*sqrt(3)))> </td></tr>
<tr><td>25</td> <td><1/(4*sqrt(2)),1,1/(4*sqrt(2))> (*) </td></tr>
<tr><td>26</td> <td><1/(4*sqrt(2)),1,1/(4*sqrt(2))> (*) </td></tr>
<tr><td>27</td> <td><1/(4*sqrt(2)),1,1/(4*sqrt(2))> (*) </td></tr>
<tr>
<td colspan="2">(*) - Unit square scaling not possible with penrose tiling. Scaling given useful to see all tiles in a way symmetrical in z.</td>
</tr>
</table>

Reference Talk:Tiling Pattern

2016-09-23T17:47:04Z

Wfpokorny: Adding table of tiling to unit square scaling vectors.

* Adding a table of unit square normalization scales.

[[Category:Patterns]]
{{#indexentry:tiling, keyword}}
{{#indexentry:tiling, pattern}}
{{#indexentry:keyword, tiling}}
{{#indexentry:pattern, tiling}}
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.
The syntax is as follows:
<pre>
pigment {
tiling Pattern_Number
[PATTERN_MODIFIERS...]
}
</pre>
<table class="centered" width="580px" cellpadding="0" cellspacing="10">
<tr>
<td>[[Image:RefImgTiling2.gif|center|560px]]</td>
</tr>
<tr>
<td>The various tiling patterns annotated by tiling pattern and tiling type respectively</td>
</tr>
</table>

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.

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!

The scale required to fit the core repeated tile into a unit square size for each tiling pattern is given in the table below.

<table class="centered" cellpadding="5" cellspacing="0" border="2px solid black" border-collapse="collapse">
<tr>
<th>Tiling Number</th>
<th>Unit square normalization scale</th>
</tr>
<tr><td> 1</td> <td><1,1,1> </td></tr>
<tr><td> 2</td> <td><2/3,1,1/sqrt(3)> </td></tr>
<tr><td> 3</td> <td><1,1,2/sqrt(3)> </td></tr>
<tr><td> 4</td> <td><1,1,2/sqrt(3)> </td></tr>
<tr><td> 5</td> <td><2/3,1,1/sqrt(3)> </td></tr>
<tr><td> 6</td> <td><1/4,1,1/4> </td></tr>
<tr><td> 7</td> <td><1/(sqrt(2)+1),1,1/(sqrt(2)+1)> </td></tr>
<tr><td> 8</td> <td><1,1,1/(sqrt(3)+2)> </td></tr>
<tr><td> 9</td> <td><1/2,1,1/(2*sqrt(3))> </td></tr>
<tr><td>10</td> <td><1,1,1/2> </td></tr>
<tr><td>11</td> <td><1/3,1,1/3> </td></tr>
<tr><td>12</td> <td><1/3,1,1/3> </td></tr>
<tr><td>13</td> <td><1/(sqrt(3)+1),1,1/(sqrt(3)+1)> </td></tr>
<tr><td>14</td> <td><1/(sqrt(3)+1),1,1/(sqrt(3)+1)> </td></tr>
<tr><td>15</td> <td><1/5,1,1/5> </td></tr>
<tr><td>16</td> <td><1/(sqrt(3)+3),1,1/((sqrt(3)+1.0)*2.0)></td></tr>
<tr><td>17</td> <td><1/(sqrt(3)+3),1,1/((sqrt(3)+1.0)*2.0)></td></tr>
<tr><td>18</td> <td><1/4,1,1/4> </td></tr>
<tr><td>19</td> <td><1/2,1,1/((sqrt(3)/2)*3)> </td></tr>
<tr><td>20</td> <td><1/2,1,1/((sqrt(3)/2)*3)> </td></tr>
<tr><td>21</td> <td><1/(1+sqrt(3)),1,1/(1+sqrt(3))> </td></tr>
<tr><td>22</td> <td><1/(2+sqrt(3)),1,1/(3+(2*sqrt(3)))> </td></tr>
<tr><td>23</td> <td><1/(3+sqrt(3)),1,1/(3+(3*sqrt(3)))> </td></tr>
<tr><td>24</td> <td><1/(3+sqrt(3)),1,1/(3+(3*sqrt(3)))> </td></tr>
<tr><td>25</td> <td><1/(4*sqrt(2)),1,1/(4*sqrt(2))> (*) </td></tr>
<tr><td>26</td> <td><1/(4*sqrt(2)),1,1/(4*sqrt(2))> (*) </td></tr>
<tr><td>27</td> <td><1/(4*sqrt(2)),1,1/(4*sqrt(2))> (*) </td></tr>
<tr>
<td colspan="2">(*) - Unit square scaling not possible with penrose tiling. Scaling given useful to see all tiles in a way symmetrical in z.</td>
</tr>
</table>

Reference Talk:Tiling Pattern

2016-09-23T17:07:48Z

Wfpokorny: Initial copy of tiling pattern page to prep for update.

Reference Talk:UV Mapping

2016-09-23T16:41:21Z

Wfpokorny: Adding lemon object to list supported for uv mapping.

* Additional uv mapping supported objects.

==Supported Objects==
Surface mapping is currently defined for the following objects:
<ul>
<li>bicubic_patch : 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>box : the image is wrapped around the box, as shown below.</li>
<li>lathe, sor : 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>mesh, mesh2 : UV coordinates are defined for each vertex and interpolated between.</li>
<li>lemon : cylindrical mapping wrapped around the axis from the base point to the cap point.</li>
<li>ovus : 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>parametric : 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>sphere : boring spherical mapping.</li>
<li>torus : 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>