1.3_adding_objects_to_the_scene.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.3 Adding objects to the scene\n",
    "Librat used the wavefront <code><span style=\"background-color:lightgrey\">.obj</span></code> format.  More information on the wavefront format can be accessed <a href=>here</a>."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import os\n",
    "from run_start import *\n",
    "from hips import hips2img, hipstats\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Wavefront object syntax\n",
    "There are a number of different syntax that can be utilised to define an object.  The previous example looks like this:</p>\n",
    "<code>\n",
    "    mtllib materials.matlib\n",
    "    !{\n",
    "    usemtl white\n",
    "    v 0 0 0\n",
    "    v 0 0 1\n",
    "    plane -1 -2\n",
    "    !}\n",
    "    !{\n",
    "    usemtl white\n",
    "    v 0 0 1000\n",
    "    ell -1 30000 30000 1000\n",
    "    !}\n",
    "</code>\n",
    "### Materials library\n",
    "Before any objects can be defined a materials library is specified, this is defined by the line <code>mtllib materials.matlib</code> where the materials (or reference to them) are stored in <code><span style=\"background-color:lightgrey\">materials.matlib</span></code>.  The contents of this looks like:</p>\n",
    "<code>\n",
    "    srm white materials/white.dat\n",
    "    srm soil materials/soil.dat\n",
    "    srm leaf materials/leaf.dat\n",
    "    ...\n",
    "</code>\n",
    "<p>Using the top line as an example, srm (standard reflectance material - Lambertian reflectance (and/or transmittance) defines a single material named <code>white</code>. The (ASCII) file giving the spectral reflectance function is located at <code><span style=\"background-color:lightgrey\">materials/white.dat</span></code>. \n",
    "\n",
    "<p>The file <code><span style=\"background-color:lightgrey\">materials/white.dat</span></code> contains 2 columns: column 1 is wavelength, column 2 is reflectance for that wavelength (wavelength units are arbitrary, but we usually use nm). In this case, the file specifies:</p>\n",
    "<code>\n",
    "    0 1 \n",
    "    10000 1\n",
    "</code>\n",
    "<p>which is a reflectance of 1.0 for any wavelength (less than or equal to an arbitrary upper limit 10000). If the file specifies transmittance as well, this is given as a third column.</p> \n",
    " \n",
    "### Defining a plane\n",
    "<p>The fields <code>!{</code> and <code>!}</code> specifiy that a bounding box should be placed around objects contained within the brackets. This allows for efficient intersection tests in the ray tracing. Normally, the ground plane is defined first:</p>\n",
    "<code>\n",
    "    !{\n",
    "    usemtl white\n",
    "    v 0 0 0 <span style=\"color:green\"><i># this is the instersection <b>I</b> vector</i></span> \n",
    "    v 0 0 1 <span style=\"color:green\"><i># this is the direction <b>N</b> vector</i></span> \n",
    "    plane -1 -2 <span style=\"color:green\"><i># an infinited plane that refers (relatively) to the previous to lines </span> \n",
    "    !}\n",
    "</code>\n",
    "<p>Using the <code>usemtl</code> field, we specify the material <code>white</code>.  Next the <code>v</code> lines denotes a vertex (vector) (as in the <a href=https://en.wikipedia.org/wiki/Wavefront_.obj_file>standard wavefront format</a>) which requires 3 numbers to be given after the v giving the {x,y,z} coordinates of the vector. Note that <code>v</code> fields can specify a location or direction vector. The field <code>plane</code> specifies a scene object. <code>plane</code> is an infinite planar object. It is defined by an intersection point (location vector) <b>I</b> and a direction vector <b>N</b>. These vectors need to be defined before a call is made to the object, so in this case, we define <b>I</b> as <code>0 0 0</code> and <b>N</b> as <code>0 0 1</code> i.e. an x-y plane at z=0.</p>\n",
    "\n",
    "<p>Thus <code>plane -1 -2</code> means:\n",
    "    <i>define a plane with <b>N</b> given by the previous specified vector (<code>-1</code>) that goes through <b>I</b> given by the second to last specified vector(<code>-2</code>)</i>."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets define a Python function for quickly evaluating .obj code blocks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def run_code(code):\n",
    "    # writes code string to temporary file\n",
    "    with open('obj/obj_example.obj', 'w') as O:\n",
    "        O.write(code)\n",
    "\n",
    "    # runs start\n",
    "    cmd = \"echo 16 0 0 50000 150000 150000 216 216 1 output/obj_example.hips | \\\n",
    "           start obj/obj_example.obj\"\n",
    "    error = run_start(cmd)\n",
    "\n",
    "    # displays hips image output\n",
    "    if not error:\n",
    "        hips2img('output/obj_example.hips', stretch=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can then be executed as below "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "code = \"\"\"\n",
    "mtllib materials.matlib\n",
    "!{\n",
    "usemtl white\n",
    "v 0 0 0\n",
    "v 0 0 1\n",
    "plane -1 -2\n",
    "!}\n",
    "\"\"\"\n",
    "run_code(code)\n",
    "# the below image is all black because it is a height map of a flat surface!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding a slope\n",
    "We can add a slope to the \"ground\" surface by changing the definition to</p>\n",
    "<code>\n",
    "    !{\n",
    "    usemtl white\n",
    "    v 0 0 0\n",
    "    v 0 1 2\n",
    "    plane -1 -2\n",
    "    }!\n",
    "</code>\n",
    "<p>Here we have now defined the second <b>N</b> vector to have direction <code>0 1 2</code>.  This look like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "code = \"\"\"\n",
    "mtllib materials.matlib\n",
    "!{\n",
    "usemtl white\n",
    "v 0 0 0\n",
    "v 0 1 2\n",
    "plane -1 -2\n",
    "!}\n",
    "\"\"\"\n",
    "run_code(code)\n",
    "\n",
    "# we can also print some stats from this surface\n",
    "print hipstats('output/obj_example.hips') # min, max, mean, sd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding the <code><span style=\"background-color:lightgrey\">sphere.obj</span></code> to our scene\n",
    "In the <a href=1.2_simple_sphere_example.ipynb>previous section</a> there was a single sphere in the scene.  This achieved using:</p>\n",
    "<code>\n",
    "    !{\n",
    "    usemtl white\n",
    "    v 0 0 1000\n",
    "    ell -1 30000 30000 1000\n",
    "    !}\n",
    "</code>\n",
    "<p>Again we have specified material <code>white</code>. Here the <code>ell</code> is an ellipsoid object that refers to the previous line. Its description requires definition of: (i) the base (N.B. not the centre) of the ellipsoid (<code>-1</code> here, meaning the previously-defined vector - <code>0 0 1000</code> in this case); (ii) the semi-axis lengths in x,y,z directions (<code>30000 30000 1000</code> here).\n",
    "so:</p>\n",
    "<code>\n",
    "    v 0 0 1000 \n",
    "    ell -1 30000 30000 1000\n",
    "</code>\n",
    "<p>is in fact a spheroid of x-y semi-axis length <code>30000</code> units (arbitrary linear units) and z-semi-axis length <code>1000</code> units: a prolate spheroid that extends from -30000 to 30000 in the x- and y-directions and from 1000 to 3000 in the z-direction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "code = \"\"\"\n",
    "mtllib materials.matlib\n",
    "# the ground\n",
    "!{\n",
    "usemtl white\n",
    "v 0 0 0\n",
    "v 0 0 1\n",
    "plane -1 -2\n",
    "!}\n",
    "# the sphere\n",
    "!{ \n",
    "usemtl white\n",
    "v 0 0 1000\n",
    "ell -1 30000 30000 1000\n",
    "!}\n",
    "\"\"\"\n",
    "run_code(code)\n",
    "# now add a slope to the ground surface"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# in this example there are two spheres\n",
    "code = \"\"\"\n",
    "mtllib materials.matlib\n",
    "# the ground\n",
    "!{\n",
    "usemtl white\n",
    "v 0 0 0\n",
    "v 0 0 1\n",
    "plane -1 -2\n",
    "!}\n",
    "# the sphere\n",
    "!{ \n",
    "usemtl white\n",
    "v 0 0 1000\n",
    "ell -1 30000 30000 1000\n",
    "!}\n",
    "# the second sphere\n",
    "!{ \n",
    "usemtl white\n",
    "v 25000 50000 1000 # offset from the middle\n",
    "ell -1 10000 10000 1000 # smaller dimensions\n",
    "!}\n",
    "\"\"\"\n",
    "run_code(code)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cloning objects\n",
    "\n",
    "We can keep adding more objects to the scene, however if they are the same e.g. many spheres, then a more efficient method is to define <code>g</code> an object and then <code>clone</code> it.</p>\n",
    "<code>\n",
    "    !{ \n",
    "    \\# define <span style=\"color:green\"><i># this line is just a comment</i></span> \n",
    "    g object_name <span style=\"color:green\"><i># define an object named \"object_name\"</i></span> \n",
    "    usemtl stem <span style=\"color:green\"><i># using material stem</i></span> \n",
    "    v 0 0 0 <span style=\"color:green\"><i># the <b>I</b> vector defining the intersection</i></span> \n",
    "    v 0 10000 0 <span style=\"color:green\"><i># the <b>N</b> vector defining the direction</i></span> \n",
    "    cyl -1 -2 5000 <span style=\"color:green\"><i>a cylinder object with circumference 5000 units</i></span> \n",
    "    !}\n",
    "    !{\n",
    "    clone 0 0 0 0 object_name\n",
    "    !}\n",
    "</code>\n",
    "\n",
    "Note that comments can be added using #.  This produces a cylinder object, this is then cloned using the line:</p>\n",
    "<code>\n",
    "    clone x y z azimuth object_name\n",
    "</code>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# in this example we clone two cylinders and orientate one at -90 degress \n",
    "# azimuth and altitude (z) 5000 units\n",
    "code = \"\"\"\n",
    "mtllib materials.matlib\n",
    "!{\n",
    "v 0 0 0\n",
    "v 0 0 1\n",
    "usemtl soil\n",
    "plane -1 -2 \n",
    "!} # this is the ground this time using the soil material \n",
    "!{\n",
    "# define\n",
    "g cylinder_object\n",
    "usemtl stem\n",
    "v 0 0 0\n",
    "v 0 20000 0 \n",
    "cyl -1 -2 5000\n",
    "!}\n",
    "!{\n",
    "clone 0 0 0 0 cylinder_object\n",
    "clone 0 0 5000 -90 cylinder_object\n",
    "!}\n",
    "\"\"\"\n",
    "run_code(code)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can add more objects to the object to be cloned.  Here we define a forest of lollipops-on-sticks trees. Obviously creating a height map means we can't see the stems though! But we may use this object file in a later example. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "code = \"\"\"\n",
    "mtllib materials.matlib\n",
    "!{\n",
    "v 0 0 0\n",
    "v 0 .5 1\n",
    "usemtl soil\n",
    "plane -1 -2 \n",
    "!}\n",
    "!{\n",
    "g tree\n",
    "usemtl stem\n",
    "v 0 0 0\n",
    "v 0 .5 10\n",
    "cyl -1 -2 2\n",
    "usemtl leaf\n",
    "sph -1 5 # a sphere object defining radius\n",
    "!}\n",
    "!{\n",
    "clone 0 0 0 0 tree\n",
    "clone 10 2 0 0 tree\n",
    "clone -20 7 0 0 tree\n",
    "clone 20 -15 0 0 tree\n",
    "clone 0 20 0 0 tree\n",
    "clone -20 -20 0 0 tree\n",
    "!}\n",
    "\"\"\"\n",
    "\n",
    "# writes code string to temporary file\n",
    "with open('obj/lollipops-on-sticks.obj', 'w') as O:\n",
    "    O.write(code)\n",
    "\n",
    "cmd = \"echo 16 0 0 200 50 50 216 216 1 output/lollipops-on-sticks.hips | \\\n",
    "       start obj/lollipops-on-sticks.obj\"\n",
    "error = run_start(cmd)\n",
    "\n",
    "# displays hips image output\n",
    "if not error:\n",
    "    hips2img('output/lollipops-on-sticks.hips', stretch=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "There are a number of other examples in $BPMS/src/lib/rat/element_types.h"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}