-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathhelp.html
109 lines (109 loc) · 15.3 KB
/
help.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
<!doctype html>
<html lang='en-US'>
<head>
<meta charset='utf-8' />
<meta name='author' content='Ilya Razmanov' />
<title>POV Mosaic options list</title>
<style>
body {
background-color: #f5f5dc;
margin: 16pt;
}
h1 {
font-family: Georgia, 'Times New Roman', Times, serif;
color: #000000;
font-size: 16pt;
text-align: center;
background-color: rgba(0, 0, 0, 0.3);
border: thin solid rgba(0, 0, 0, 0.5);
}
h2 {
font-family: Georgia, 'Times New Roman', Times, serif;
color: #000000;
font-size: 14pt;
text-align: left;
padding: 0px 24pt;
background-color: rgba(0, 0, 0, 0.2);
}
p {
font-family: Georgia, 'Times New Roman', Times, serif;
color: #000000;
font-size: 12pt;
text-align: left;
}
.pre {
font-family: 'Courier New', Courier, monospace;
white-space: pre;
break-inside: avoid;
border: thin solid rgba(0, 0, 0, 0.3);
margin: 0px 0pt;
padding: 0px 4pt;
background-color: rgba(0, 0, 0, 0.1);
border-radius: 6px;
}
.strong {
font-weight: bold;
letter-spacing: 0.2em;
}
.em {
font-style: italic;
color: #009900;
}
</style>
</head>
<body>
<h1>Options of POV Mosaic programs</h1>
<h2>Description</h2>
<p><a href='https://github.com/Dnyarri/POVmosaic'><span class='strong'>POVRay Mosaic</span> programs</a> is a set of Python programs for conversion of regular 2D images into a mosaic of solid 3D objects in <a href='https://www.povray.org'>POVRay</a> format. For example, every pixel of original image is converted into a 3D sphere, having the same base color as original pixel, and all set of spheres is inserted into a 3D scene file, containing, beside this sphere mosaic, camera and lights necessary to render the scene.</p>
<p>In general, any <span class='strong'>POV Mosaic</span> program exports some basic scene, as simple as possible, yet providing a vast reconfiguring option set within the scene .pov file. By editing obtained .pov file you can easily replace base objects and redefine their transforms across the whole scene by changing a couple of text stings.</p>
<p>Options are summarized and detailed below.</p>
<h2>Introduction</h2>
<p>It is important to understand that in <span class='strong'>POV Mosaic</span> output X and Y axes mimic Photoshop, that is, X is horizontal, Y is vertical, and origin (zero) is top left corner. Z axis point toward viewer.</p>
<p>To avoid possible confusions with word "object" which is internally reserved here and there for something (for example, in POVRay SDL itself), all elementary objects in scene file are called <i>"thingies"</i>, and their union - <i>"thething"</i>.</p>
<h2>POVRay header</h2>
<p>Exported POV file header contain minimal information required by POVRay, like explicitly setting common rendering options. Meaning of settings is well described in POVRay documentation.</p>
<h2>Predefined objects, properties and modifiers thereof</h2>
<p><span class='pre strong'>#declare thingie_<span class='em'>n</span> =</span> Defines thingie nature - sphere, cube, pyramid, etc. Size of the thingie is 1.0, and thingie is centered at 0.0. You can add your own thingies to the scene, following that rules. You can also edit existing thingies properties globally in this section.</p>
<p><span class='pre strong'>#declare thingie_finish_<span class='em'>n</span> =</span> Defines thingie finish. Default one is smooth plastic, but you can use anything else. Surely, using POVRay include files is also possible.</p>
<p><span class='pre strong'>#declare thingie_normal_<span class='em'>n</span> =</span> Defines thingie surface normal modifier. Default one have zero intensity to simplify the picture appearance. Remember that normal may be rotated and moved on a per thingie basis later (see <span class='pre'>normal_move_rnd</span> and <span class='pre'>normal_rotate_rnd</span> below), so any "elongated" patterns will be giving interesting results.</p>
<h2>Global modifiers for all thingies in the scene</h2>
<p><span class='pre strong'>#declare thingie_texture_2 = texture{}</span> Defines texture overlay <span class='pre'>thingie_texture_2</span>, applied above generated texture of each thingie, thus giving the capability to build layered textures. Default exported example overlay is completely transparent and therefore invisible gradient, just edit one of its control points to opaque to get a feeling of what it's all about.</p>
<p><span class='pre strong'>#declare yes_color = 1;</span> Switch defining whether source per-thingie color is taken or global texture applied. Default is 1, i.e. colored mosaic; 0 gives solid <i>thething</i> texture which, in combination with <span class='pre'>scale_map</span>, may give interesting pseudo-heightfield effects.</p>
<p><span class='pre strong'>#declare cm = function(k) {k}</span> Color modifier. Transfer function(k), by default output = input, changing it to something like <i>{k+0.1}</i> or <i>{0.9*k}</i> may be useful for a quick fix of poor color scene.</p>
<p><span class='pre strong'>#declare f_value =</span> Input: float number. All thingies colors are specified as <span class='em'>rgbft</span> (red, green, blue, filter, transmit); while <span class='em'>rgb</span> is set according to source image pixel color, filter component value is set to <span class='pre'>f_value</span> globally. Default is 0.0 (completely opaque), you may change it to turn <i>thething</i> into glass.</p>
<p><span class='pre strong'>#declare t_value =</span> Input: float number. Transmit value of <span class='em'>rgbft</span> (red, green, blue, filter, transmit) vector above. Default is 0.0 (completely opaque), you may change it to turn <i>thething</i> into something transparent.</p>
<p><b>Note:</b> POVRay mosaic programs do not directly translate source pixel transparency into resulting thingie transparency. Instead, they use source pixel transparency for thingies dithering: if source pixel is completely opaque, resulting thingie is created, if source pixel is completely transparent, no thingie created, if source pixel is partially transparent, program compares source pixel transparency with random value to decide whether create thingie or not.</p>
<p><span class='pre strong'>#declare evenodd_rotate =</span> and <span class='pre strong'>#declare evenodd_offset =</span> - Specific to <b>44zaika</b>. Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Provides even/odd thingies rows offset for a brick wall pattern, and rotation for some patterns.</p>
<p><span class='pre strong'>#declare evenodd_transform = transform { }</span> - Specific to <b>63zaika</b>. Describes (in general form) even/odd thingies rows transform for some patterns.</p>
<p><span class='pre strong'>#declare scale_all =</span> and <span class='pre strong'>#declare rotate_all =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Specific to <b>44zaika</b>. Provides starting values for thingies rescaling and rotation. Included into the scene to simplify 44zaika output tune up. Not generated by other zaikas since it's less useful (what one may expect from sphere rotation?), and you can do it while defining thingie (some builtin thingies contain overall transforms already).</p>
<h2>Map functions for all thingies in the scene</h2>
<p>It is important to understand the idea of "<span class='strong'>mapping</span>" applied in these programs. The idea is that some thingie property (size, for example) is made dependant on some function. At the moment of writing this function is image brightness, therefore thingie size can be made varied with source image pixel brightness.</p>
<p>Since version 1.6.19, all predefined maps are replaced with spline function, set in <span class='pre strong'>#declare Curve = </span> section. Visually spline description looks like table of <span class='pre'>0.0, <0.0, 0></span> elements, where first number correspond to input brightness value, second number correspond to output value which this input will be recalculated to, and third number is temporarily unused. In default export five points linear spline is set, which means input=output, i.e. no map change is applied. You can both edit existing control points and add new ones, just be sure to always have 0 and 1 endpoints defined (working with undefined functions will make POVRay either render garbage or refuse rendering).</p>
<h2>Selecting variants</h2>
<p><span class='pre strong'>#declare thingie = thingie_<span class='em'>n</span></span> Switch for choosing one of predefined objects <span class='pre'>thingie_1</span>, <span class='pre'>thingie_2</span> etc. to be used for building <i>thething</i>. At the moment of writing there are 7 predefined objects available. You can also insert some external object from external .inc file here, just remember that they are supposed to fit the cube of 1, 1, 1 size.</p>
<p><span class='pre strong'>#declare thingie_finish = thingie_finish_<span class='em'>n</span></span> Switch for choosing one of predefined finishes <span class='pre'>thingie_finish_1</span>, <span class='pre'>thingie_finish_2</span> etc. to be applied to every thingie.</p>
<p><span class='pre strong'>#declare thingie_normal = thingie_normal_<span class='em'>n</span></span> Switch for choosing one of predefined normal modifiers <span class='pre'>thingie_normal_1</span>, <span class='pre'>thingie_normal_2</span> etc. to be applied to thingie.</p>
<p><span class='pre strong'>#declare map = function(c) {map_<span class='em'>n</span>(c)}</span> Switch for choosing one of predefined mapping functions <span class='pre'>map_1</span>, <span class='pre'>map_2</span> etc. to be applied when calculating map-dependant properties of every thingie.</p>
<h2>Per-thingie modifiers</h2>
<p>Different settings listed below map different thingie properties to this function.</p>
<p><span class='pre strong'>#declare move_map =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Thingie will be moved away from origin proportionally to map and <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> components. Intended use is moving thingies along <span class='em'>z</span> to add some depth to otherwise flat <i>thething</i>.</p>
<p><span class='pre strong'>#declare scale_map =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Thingie will be rescaled proportionally to map and <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> components. At the moment of writing scaling is subtractional - any component values higher than 0.0 will make "bright" thingies smaller.</p>
<p><span class='pre strong'>#declare rotate_map =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Thingie will be rotated around X, Y and Z axes proportionally to map and <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> components. Note that normal is rotated together with its parent thingie.</p>
<p>Beside regular component of the map, there are components randomly generated by POVRay during rendering.</p>
<p><span class='pre strong'>#declare move_rnd =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Settings control the range of per-thingie effect (that is, setting value is multiplied by random value within 0..1 range). Effect is added to <span class='pre'>move_map</span> above. Intended use is small randomization of <span class='em'>z</span> position to break monotonous shading patter of regular structure. However, nothing can stop you from unintended use.</p>
<p><span class='pre strong'>#declare rotate_rnd =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Settings control the range of per-thingie effect. Effect is added to <span class='pre'>rotate_map</span> above. Intended use is randomization of non-spherical thingies (like <span class='pre'>thingie_5</span> or <span class='pre'>thingie_6</span>) appearance.</p>
<p>Beside per-thingie thingie modifiers, there are per-thingie thingie surface normal modifiers listed below.</p>
<p><span class='pre strong'>#declare normal_move_rnd =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Effect is randomized movement of normal related to thingie to break "perfect clone" thingie appearance.</p>
<p><span class='pre strong'>#declare normal_rotate_rnd =</span> Input: <span class='em'>x</span>, <span class='em'>y</span>, <span class='em'>z</span> vector. Effect is randomized rotation of normal related to thingie center.</p>
<h2>Random seed</h2>
<p><span class='pre strong'>#declare rnd_1 = seed(<span class='em'>int</span>);</span> Seeding POVRay random generator for all the randomized effects above. At the moment of writing all randomization procedures use one random sequence <span class='pre'>rnd_1</span> thus eliminating any cross-references between thingies properties. Seed value is generated from your system timer during program execution. That is, seed value changes between program starts but gets fixed once you press "Save" button, making re-rendering of exported scene reproducible. If you want to re-randomize the ready scene, simply change <span class='em'>int</span> value to any other integer number.</p>
<h2>Presets</h2>
<p><span class='pre strong'>// #include "preset.inc"</span> Obviously, you can override any setting above by including it into <span class='pre'>"preset.inc"</span> file (include is commented out by default). There are sample preset files in the project, containing descriptions of additional thingie geometry and scene settings. Using external presets simplifies tweaking complex settings when trying different scene variants: instead of editing/undoing/redoing numerous changes in a main scene file, you may simply have a set of presets and switch them with one line.You may even redefine transfer functions via presets, just don't forget to <span class='pre'>#undef</span> global one in preset before <span class='pre'>#declare</span>'ing it locally again (some preset sample contain the example).</p>
<p>This is the end of description of <span class='strong'>POV Mosaic</span> programs settings you are supposed to know.</p>
<h2>Addendum: Prerequisites</h2>
<p><span class='pre strong'><a href='https://gitlab.com/drj11/pypng'>PyPNG</a></span> compact PNG I/O module download.</p>
<p><span class='pre strong'><a href='https://www.povray.org/download/'>POVRay for Windows</a></span> official download.</p>
<p><span class='pre strong'><a href='http://megapov.inetart.net/povrayunofficial_mac/finalpov.html'>POVRay for Mac</a></span> unofficial download.</p>
<p style='text-align: center; font-size: 10pt;'>© 2024 <a href="mailto:ilyarazmanov@gmail.com">Ilya Razmanov</a></p>
</body>
</html>