# CindyGL Tutorial - Rendering 3D Scenes

In this tutorial, we want to render a three-dimensional scene with `colorplot`

in CindyJS. We will demonstrate the basic indigents that can be used to build complex three-dimensional scenes or to investigate various rendering approaches.

We will build an applet 3d.html, which renders a 3D scene that can be rotated by dragging the mouse:

## Prerequisites

We assume that you already have seen some CindyScript and the core functionality of the `colorplot`

-command, for example in the CindyGL live coding tutorial. For the last part, it is good to know how to create your CindyJS-applets or having some experience with the CindyJS editor.

## Basic concepts of Raytracing

Let us assume that a camera is located at a particular position, for instance at `origin = [0,1,-3]`

and we are looking along the $z$-axis. For the beginning, let us try to render the plane $y=0$.

How can this be archived through a `colorplot`

on the GPU?

The key idea is that with each pixel a direction `dir`

is associated, which varies for each pixel. The pixel in the middle of the rendered screen should "look" along the z-axis, hence for it, we have `dir = [0,0,1]`

. For pixels that are slightly right of the pixel in the middle, this variable could take the value `dir = [0,0.1,1]`

, meaning that the associated direction points slightly more to the right.

More general, we can write `dir = [#.x, #.y, 1]`

, where `#`

is the coordinate of the current pixel.

We will say that behind this pixel lies a ray

`ray(t) := origin + t*dir`

This ray will eventually intersect the scene for some $t>0$. Now, if we want to render the intersection of each ray with the plane $y=0$. We can solve $(\mathrm{origin} + t \cdot \mathrm{dir}).y = 0$ for $t$ and obtain

`tfloor = -origin.y/dir.y;`

If the computed `tfloor>0`

, then the ray behind the current pixel eventually will intersect the plane $y=0$, otherwise it wont intersect it (and we will display the color of a sky, for instance). Let us put this together:

```
origin = [0,1,-3];
colorplot(
dir = [#.x,#.y,1]; //ray(t):=origin+t*dir
//intersection with floor:
//ray(floort).y=0 <=> origin.y+floort*dir.y=0
floort = -origin.y/dir.y;
if(floort>0,
[1,1,1]*exp(-|floort|*.2), //ray hits floor
[.8,.8,1]*exp(-.3*dir.y) //sky
);
);
```

## Rendering a sphere

Now, instead of the floor, let us render a sphere. For simplicity, let us display the unit sphere located at (0,0,0).

When does `ray(t):=origin+t*dir`

intersect this sphere? This can be reformulated into the solution a quadratic polynomial:

$$
\begin{eqnarray}
|| \mathrm{ray}(t) || = 1 &\Leftrightarrow& || \mathrm{ray}(t) ||^2 = 1 \Leftrightarrow \langle \mathrm{ray}(t), \mathrm{ray}(t) \rangle = 1 \\
&\Leftrightarrow &
\langle \mathrm{origin}, \mathrm{origin} \rangle + 2 t \langle \mathrm{origin}, \mathrm{dir} \rangle + t^2 \langle \mathrm{dir}, \mathrm{dir} \rangle= 1 \\
&\Leftrightarrow& a t^2 + b t + c = 0 \text{ for $a=\langle \mathrm{dir}, \mathrm{dir} \rangle$, $b=2 \langle \mathrm{origin}, \mathrm{dir} \rangle$ and $c=\langle \mathrm{origin}, \mathrm{origin} \rangle$}\
\end{eqnarray}
$$
Hence, whenever the discriminant $D=b^2-4 a c$ of the polynomial $a t^2 + b t + c$ is non-negative, the ray intersects the sphere. Scalar products can be computed in CindyScript via `*`

. The two intersection points can be computed as $t_{1,2} = \frac{-b \pm \sqrt{b^2-4 a c}}{2 a}$. This can be used for the following program that "renders" a sphere:

```
origin = [0,1,-3];
colorplot(
dir = [#.x,#.y,1];
a = (dir*dir);
b = 2*(origin*dir);
c = origin*origin-1;
D = b^2-4*a*c; //discriminant
if(D>0, //there is some intersection
[1,.3,.3], //some reddish color
[.8,.8,1]*exp(-.3*dir.y) //sky
);
);
```

How can we colorize the sphere, which now shown as a reddish circle only, properly? One trick is that the coordinate on the unit sphere itself is already the normal of the sphere at this position. The normal can be used for approximating some diffuse reflection.

```
ray(t):= origin+t*dir;
origin = [0,1,-3];
colorplot(
dir = [#.x,#.y,1];
a = (dir*dir);
b = 2*(origin*dir);
c = origin*origin-1;
D = b^2-4*a*c; //discriminant
if(D>0, //there is some intersection
normal = ray((-b-re(sqrt(D)))/(2*a));
(normal*[1,1,-1])*[1,.3,.3],
[.8,.8,1]*exp(-.3*dir.y) //sky
);
);
```

## Combining multiple elements in a scene

Now, let us combine multiple elements within one scene. For each object $i$ we compute an intersection value $t_i$, i.e. the smallest value such that $\mathrm{ray}(t_i)$ intersects the object. For the corresponding pixel, we display the object $i$ which has the smallest non-negative value $t_i$. We might also say that each object has some different color and also the normal of each object should be taken into consideration. This could be programmed in CindyScript with the following helper function that is executed for each element:

```
updatehit(t, normal, color) := if(t>0 & t < hitt,
hitt = t;
hitpos = ray(t);
hitnormal = normal;
hitcolor = color;
);
```

If `updatehit(t, normal, color)`

is called, it will update the variables `hitt`

, `hitpos`

, `hitnormal`

and `hitcolor`

whenever the current parameters correspond to the so far closest object. The variable `hitt`

has to be initialized to $\infty$, within colorplot. Since there is no Infinity in CindyScript, we just choose a large float-value such as `1e8`

=$1\cdot 10^8$. Alltogether we can use the following code to render a scene consisting of a floor and a wall:

```
light = [cos(seconds()),2, sin(seconds())-1];
origin = [0,1,-3];
colorplot(
dir = [#.x,#.y,1];
//default values (if no hit)
hitt = 1e8; hitpos = hitnormal = hitcolor = [0,0,0];
//intersect with floor
updatehit((-origin.y)/dir.y, [0,1,0], [1,1,1]);
//intersect with wall at z=4:
updatehit((4-origin.z)/dir.z, [0,0,-1], [1,1,0.6]);
lightdir = (light-hitpos)/|light-hitpos|;
max(0,lightdir*hitnormal)*hitcolor;
);
```

Furthermore, we introduced a vector `light`

, which indicates the (moving) source of the light. Click "Enter Fullscreen" if the code covers your entire screen.

We can use the same scheme to futher add the unit-sphere with center $(0,0,0)$ as follows:

```
light = [cos(seconds()),2, sin(seconds())-1];
origin = [0,1,-3];
colorplot(
dir = [#.x,#.y,1];
//default values (if no hit)
hitt = 1e8; hitpos = hitnormal = hitcolor = [0,0,0];
updatehit((-origin.y)/dir.y, [0,1,0], [1,1,1]);
updatehit((4-origin.z)/dir.z, [0,0,-1], [1,1,0.6]);
//polynomial for |ray(t)|^2=1: sphere
a = (dir*dir); b = 2*(origin*dir); c = origin*origin-1;
D = b^2-4*a*c; //discriminant of polynomial a t^2 + b t + c
if(D>0,
spheret = (-b-re(sqrt(D)))/(2*a);
updatehit(spheret, ray(spheret), [1,0,0]);
);
lightdir = (light-hitpos)/|light-hitpos|;
max(0,lightdir*hitnormal)*hitcolor;
);
```

## Moving the camera

In order to avoid a lot of distracting code, we have encapsulated the code above into a helper-function `hitray()`

that is defined as follows and returns the color based on the set variables `dir`

and `origin`

```
hitray() := (
hitt = 1e8; hitpos = hitnormal = hitcolor = [0,0,0];
//floor
updatehit((-origin.y)/dir.y, [0,1,0], [1,1,1]);
//wall
updatehit((4-origin.z)/dir.z, [0,0,-1], [1,1,0.6]);
//sphere; polynomial for |ray(t)|^2=1
a = (dir*dir); b = 2*(origin*dir); c = origin*origin-1;
D = b^2-4*a*c; //discriminant of polynomial a t^2 + b t + c
if(D>0,
spheret = (-b-re(sqrt(D)))/(2*a);
updatehit(spheret, ray(spheret), [1,0,0]);
);
lightdir = (light-hitpos)/|light-hitpos|;
max(0,lightdir*hitnormal)*hitcolor;
);
```

and the entire scene can be now rendered as

```
origin = [0,1,-3];
colorplot(
dir = [#.x,#.y,1];
hitray() //computes the color of the intersection of ray(t):=origin+t*dir with the scene
);
```

Let us move the camera! A simple way of moving the is to change the variable `origin`

. In the examples above, you could replace `origin = [0,1,-3];`

with `origin = [0,2+sin(seconds()),-3]`

for instance:

```
origin = [0,2+sin(seconds()),-3];
colorplot(
dir = [#.x,#.y,1];
hitray() //computes the color of the intersection of ray(t):=origin+t*dir with the scene
);
```

## Pointing the camera to a target

How can point the camera to a certain target coordinate? Let us introduce a second variable
`target = [0,0,0];`

and demand that `dir`

for the pixel in the middle of the screen should be the vector pointing from `origin`

to `target`

. Let us compute this vector as `mdir = (target-origin)/|(target-origin)|;`

. Further, we can compute a orthogonal basis `(v,w,mdir)`

and and set `dir = mdir + #.x*v + #.y*w;`

. In order to build such a orthogonal basis, we have a freedom in rotating `v`

and `w`

along `mdir`

.

In this context, a good orthogonal basis has the vector `w`

pointing upwards such that the vertical lines on the screen align with the vertical lines in the image (no "Dutch angle"). Such a orthogonal basis can be computed with cross-products as follows:

```
target = [0,0,0];
origin = [cos(seconds())*2, sin(seconds()/3)+2, sin(seconds())*2];
mdir = (target-origin)/|(target-origin)|;
v = cross([0,1,0], mdir);
w = cross(mdir, v);
v = v/|v|;
w = w/|w|;
colorplot(
dir = mdir + #.x*v + #.y*w;
hitray();
);
```

Once this code is executed, the target at $(0,0,0)$ remains at the center of the screen.

## Interaction with the mouse

For many visualizations, it is good to let the user how to watch something. Suppose, we want to study a particular object at the `target = [0,0,0]`

and modify `origin`

with the mouse (by dragging). How can we do this?

The aim is to build an applet such as 3d.html, which renders a 3D scene that can be rotated by dragging the mouse.

In order to build this applet we set origin to be a point on a sphere specified by the coordinates `(lambda, phi)`

:

```
target = [0,0,0];
origin = 2*[cos(lambda)*cos(phi),
sin(phi),
sin(lambda)*cos(phi)
];
mdir = (target-origin)/|(target-origin)|;
v = cross([0,1,0], mdir);
w = cross(mdir, v);
v = v/|v|;
w = w/|w|;
colorplot(
dir = mdir + #.x*v + #.y*w;
hitray();
);
```

The values of `lambda`

and `phi`

are controlled essentially via the `mousedrag`

-script. In the live-editor of the tutorial you cannot modify these special scripts.
For this purpose, you can use the CindyJS online editor available at https://cindyjs.org/editor/.
Alternatively, if you are building your own applet based on a file such as boilerplate.html, you can either add some HTML-code

```
<script id="csmousedrag" type="text/x-cindyscript">
your code
</script>
```

The `mousedrag`

script is always executed if the browser notices that the mouse is moved while the button is pressed.

In this example we have set the `mousedrag`

-script to the following:

```
d = mouse()-lastmouse;
lambda = lambda-d.x;
phi = phi-d.y;
lastmouse = mouse();
```

Which means that whenever the mouse is dragged, the distance traveled by the mouse is also subtracted to the coordinates `(lambda, phi)`

. The script should always be well defined. So, in the `mousedown`

-script we should also set

`lastmouse = mouse();`

and in the `init`

-script we should assign some starting values to `lambda`

and `phi`

.