Getting started

First of all, create a text file (we'll use myscene.osm) and open it in your favourite editor. Now, lets create our first geom. Geoms define all of the physical objects in a scene, including lights. For now lets create a sphere and take a look at the OSM code:

(make-sphere '(0.0 0.0 0.0) 10.0)

This creates a sphere centred at 0.0,0.0,0.0 with a radius of 10 units. As it stands this isn't particularly useful since it will just be created then instantly discarded, so lets give it a name:

(define sphere1 (make-sphere '(0.0 0.0 0.0) 10.0))

This defines a symbol 'sphere1' which evaluates to our sphere geom.

Next we need a transformation to give this sphere. Since we want to keep this simple we'll just define an identity transform (and bind it to the symbol 'identity'). Don't worry about this command yet, rest assured we'll come back to it later when we want to instance and move/rotate geoms.

(define identity (make-transform '(0.0 0.0 0.0) (make-quaternion 1.0 0.0 0.0 0.0) ) )

Ok, now we need a material. Lets create a simple red diffuse material (and again bind it to a name):

(define material1 (make-material (make-surf "lambertian" (make-rgb 1.0 0.0 0.0)) ) )

Whoa! A lot goes on there. Lets break it down a bit.

(make-rgb 0.9 0.0 0.0)

This function creates a spectrum from R,G,B components. In this case it is a (very) red colour.

(make-surf "lambertian" ...)

This function creates a surface function, the first parameter ``lambertian'' says we want a pure diffuse surface. The second parameter is a spectrum or texture which gives the surface a colour.

The final part is make-material. We now need to combine these three things into a primitive which we can actually add to the scene:

(define sphere1_prim (make-primitive sphere1 identity material1 ))

As you can see make-primitive simply takes a geom, transform and material and returns a primitive (here bound to sphere1_prim).

The next step is to create a light source so we can actually see our sphere:

(define light_mtl (make-material (make-surf "lambertian" (make-rgb 0.2 0.9 0.2)) (make-emittance "diffuse" (make-rgb 1.0 1.0 1.0)) ))

(define light1 (make-light (make-sphere '(0.0 75.0 0.0) 2.0) light_mtl identity))

This creates a white spherical light source (explained in more detail later).

Now lets build a scene with our sphere and light:

(define scene (make-scene '(sphere1_prim) '(light1) ) )

The quotes here are very important, they prevent the OSM interpreter from trying to evaluate the following list (in other words, make-scene takes two lists of things). Without the quotes the interpreter would attempt to find a procedure bound to 'sphere1_prim' and since that is bound to a primitive it would raise a nasty exception.

Next we need a rendering algorithm:

(define surface-integrator (make-si "direct" scene 4))

I won't explain this too much yet, just accept it does direct lighting.

Now we need to create a camera to actually look at the scene:

(define view (make-view '(100.0 60.0 0.0) '(0.0 10.0 0.0) '(0.0 1.0 0.0) ) )

(define camera (make-pinhole-fov view 0.035 40.0 40.0 128 128))

The make-view function takes three vectors (note the quotes again, vectors are typically represented by lists), an 'eye', a 'focus' and an 'up'. The eye is the position we're looking from, the focus is the point we're looking at and the up vector gives an indication of which way should be up. The make-pinhole-fov call makes a pinhole camera with focal length 0.035, an X FOV of 40 degrees, a Y FOV of 40 degrees and it presumes an image 128x128 pixels in size.

Finally, lets render our scene:

(define filename "myscene.hdr")

(save-hdr filename (render surface-integrator camera 128 128 16 scene ) )

The render call takes a rendering algorithm, a camera, an image size, a number of samples to take per pixel and a scene.

You can try this out with:

opath myscene.osm