CAT.mcr Help Contents

1.0 Introduction

1.1 Description
1.2 How it works
1.3 Contents
1.4 Where do I find updates?

2.0 Getting Started

2.1 Usage of the CAT() macro
2.2 The CAT_Save() macro
2.3 The CAT_Load() macro

5.0 Working with meshes (i.e. Poser)

5.1 The inside_vector affair

Thank you for downloading this include file! I started this project some years ago, but at last have became in the almost-finished macro file and documentation you see before you.

To contact the author about this file (suggestions, corrections, questions, donations), write me at CAT_MCR [at] persistencia.orgCAT_MCR [at] persistencia.org

Also note that english is not my mother tongue, so it's likely you'll find any kind of grammatical or syntactical crimes on the next lines, be patient, please. I hope to not commit too much "all-your-base-are-belong-to-us", anyway, should be nice to count with some help on this matter. (gratitude guaranteed).

The CAT macro file is included with the documentation inside the sourcecodes folder, also can be downloaded from here.

Puede consultar una version en español de esta documentación usando su dedo indice (o lo que prefiera) para hacer click aquí.

1.1 Description

This macro lets you convert shapes, CSG objects or mesh objects (like Poser characters) into a new cell-based object for The Persistence Of Vision Raytracer (POV-Ray™), using a technique vaguely similar to Computerized Axial Tomography - CAT could mean also Cell's Automatic Transposition.

The macro wrappers included in the macro file let you easily save-convert and load-render CSG shapes or mesh objects without the need of learn to handle a lot of arguments.

1.2 How it works

The input-object is subdivided in slices (floors) by intersecting it with a thin box which is displaced up by a while-loop (inner macro Scanner()). Then the macro shoots a matrix of intersection test against every slice using the trace() function and writes the location of an occupied cell as a parameter of a inner macro (the C() macro) in a user defined file. On the render step a previously stored datafile is included invoking the C() macro with the Cell_Shape parameter to form the new output-shape.

1.3 Contents

The include file contains:

A CAT macro for save/load data-file.
A pair of wrapper macros to handle more easily the CAT macro.

1.4 Where do I find updates?

Check at The Cat Macro webpage at: www.persistencia.org/cathelp/cat.html
Check the povray.general news group from the news.povray.org news server.
Email me at CAT_MCR [at] persistencia.org

2.0 Getting Started

Copy the macro file into POV-Ray's include directory or the directory where you intend to use it. After that, just include the file like so:

#include "cat.mcr"

2.1 Usage of CAT() macro

Before using the macro you must have previously declared the object that will be "scanned":

#declare MyThing = object {...} ;

then you can invoke the CAT() macro using the following parameters:

OBJ - name of the previously declared object that will be converted
Subd - Number of vertical subdivisions, (slices or floors) in wich we will replace the object by cells.
Surfacells - on means that only the cells placed on the surface will be parsed and saved in a file, while off means that the macro calculates and save in a file every cell inside the object.
Status - take this as a #switch parameter; 0 means that the object will be parsed and data file stored on a file - while 1 means that the macro reads the data file and render the result in the same place the original object were.
"File_name.ext" - A filename string to store or read the data.
Cell_Shape - well, here is where your creativity takes part. Cell_Shape is a #switch directive that contains 20 presets of cell-shapes, from plain spheres to randomized combinations of boxes and cylinders, blobs, etc...
Cell_Scale - set the radii of cells multiplying its size by this value.

// CAT (OBJ,Subd,Surfacells,Status,"File_name.ext",Cell_Shape,Cell_Scale) CAT (My_Thing, 40, off, 0, "test01.txt", 0, 0)
/* We invoke the CAT macro to scan My_Thing object
in 40 "slices" and process every cell inside, then save data in "test01.txt" then... */

CAT (My_Thing, 0, 0, 1, "test01.txt", 0, 1)
/* ...we invoke the CAT macro for read "test01.txt" and render some little spheres */

Note that in this example we are invoking two times the same macro; first for parsing and writing a file, and a second one for render results, but you needn't to do this everytime you want to use the macro, spending time in parsing once and again the same data. It would be more efficient (time saving) if you only change the Status parameter depending the step of your work, but... Why should we take the risk of mix-up the parameters and overwrite the same output-file reusing parameters that will not take in count? (i.e. Cell_Scale and Cell_Shape doesn't affect anything when we're writing datafile, while OBJ, Subd and Surfacells are sparing our precious code when we're render the stored data-file). It's time to meet the macro wrappers.

2.2 The CAT_Save() macro

This macro will pass only four parameters to CAT() macro:

OBJ - Name of the previously declared object,
Subd - Number of vertical subdivisions,
Surfacells - (on) Process only those cells which are on the surface, (off) or everyone inside the object?
"File_name.ext" - a Filename string for saving data.

// CAT_Save (OBJ,Subd,Surfacells,"File_name.ext") CAT_Save (My_Thing, 35, off, "test05.txt")
/* We invoke the CAT_Save macro to scan My_Thing
in 35 "floors" processing every cell and save data in "test05.txt" */

2.3 The CAT_Load() macro

This one just load our stored data-file and then selects the cell-shape and its radius. So we'll need only these parameters:

"File_name.ext" - a filename string for loading data
Cell_Shape - select the cell-shape that will form the new object
Cell_Scale - multiplies the cell-shape's radius by this factor

// CAT_Load ("File_name.ext",Cell_Shape,Cell_Scale) CAT_Load ("test05.txt",14,1.25)
/* We invoke the CAT_Load macro loading "test05.txt",
then we select the 14th preset-cell-shape and re-scaling its radius to 1.25 */

3.0 Cell_Shape reference

All the Cell_Shape presets included on CAT() macro are:

The Cell_Shape code can be taken as an example for add new cells.

Note: if you wish to custom yourself this section, keep in mind that the 13th preset must be always a blob object due to it's particular syntax.

4.0 Tutorial : Basic example

Let's explore some basic examples to see how parameters works (click on images):

First we define a very simple background and declare an object (My_Thing) placing it on the right side.
Source : CAT_examp_01.pov
Then we invoke the `CAT_Save()` macro by including "cat.mcr" in our scene. Let's save the result of subdividing it in 20 slices, processing every cell inside the object and write data to "test01.txt" . mmmmh... note that no result is still visible...
Source : CAT_examp_02.pov
Let's see the new shape calling to `CAT_Load()` macro and placing it balancing our composition on the left. Oh! Itsn't terrific?</ironic>
Source : CAT_examp_03.pov
Once scanned and converted the original object, we needn't it anymore in our scene. So let's remove any reference. We can also reuse the same datafile with different `Cell_Shape` values...
Source : CAT_examp_04.pov
...or the same `Cell_Shape` with different `Cell_Scale`.
Source : CAT_examp_05.pov
Note that the cells' radii is determined by floor's thickness, which is obtained from: Height_of_Object / N-Subdivisions. So: objects of different height and equal `Subd` value will result in cells of different radius, no matter the value of `Cell_Scale` that we use. (Remember: `Cell_Scale` multiplies the radius of the cell, it doesn't fit for setting a certain radius). Note also that floor's thickness is used in the calculation of matrix's size to determine the number of cells in every slice.
Source : CAT_examp_06.pov

5.0 Working with meshes (i.e. Poser)

By default, the CAT() macro doesn't work with imported meshes from Poseray (or others) because these objects doesn't have a defined 'inside', so they can't be processed in the intersection calculation. Let's see what do the POV-Ray™ documentation says about this:

3.4.2.3.1 Solid Mesh
Triangle mesh objects (mesh and mesh2) can now be used in CSG objects such as difference and intersection, because, after adding inside_vector, they do have a defined 'inside'. This will only work for well-behaved meshes, which are completely closed volumes. If meshes have any holes in them, this might work, but the results are not guaranteed.

Knowing this, remind that we MUST add the inside_vector keyword and a 3D vector to your include file to work with meshes. So... let's take a look to a typical include file generated by Poseray:

Before...	After...
`// [...] #include "untitled_pov_mat.inc" #declare Untitled=mesh2{ vertex_vectors{ 18909, <-0.0070828,0.435842,-0.01579>, ... ... ...} uv_mapping }`	`// [...] #include "untitled_pov_mat.inc" #declare Untitled=mesh2{ vertex_vectors{ 18909, <-0.0070828,0.435842,-0.01579>, ... ...} inside_vector <0,1,0>uv_mapping }`


union	before inside_vector	after inside_vector

That's all, just add your inside_vector vector before using a mesh on the CAT() macro and get some fresh cells.

VERY VERY VERY IMPORTANT: Ignore or forget this section will dramatically raise up the parsing time without obtain results.

5.1 The inside_vector affair

The problem with inside_vector is that results are not guaranteed. Depending on the vector used the macro fails and render too much unexpected cells aligned to inside_vector. Tip: Low-res models seems to work better (but not always) than Hi-res.

In this example the right shape (from a Hi-res P6 character) shows too much cells than the left one (Poser 4).

Tip: Edit de include file and find the "wrong" cells. Clean them.

6.0 Speed considerations

Keep Subd value under 90. Our brain don't need more than a few details to compose an object.
Take care of the output files you are saving. The macro adds output data to an existing file, it doesn't erase or overwrite previous files.
Surfacells on will take more time on parsing, but less time on render. While Surfacells off takes less time on parsing, but more render time.
Obviously, do not use the CAT_Save() macro on a complex scene with focal_blur, radiosity or area_lights. A simple scene without lights is enough for convert shapes.