Download Project Documentation (, 10.4 MB) - Taxon Studios

sandpaperleadSoftware and s/w Development

Oct 31, 2013 (3 years and 9 months ago)

250 views


 
 
OsteoScope
 
An  Exploratory
 
Master’s
 
Research  Project  on  Incorporating  CT
-­‐
Based  3D  
Models  into  an  Interactive  Application
 

Project  Documentation
 













Agnes Chan

(1T3)



2

Table  of  Contents
 
Credits  &  Acknowledgements    
 
 
 
 
 
 
 
 
   
5
 

Project  Overview    
 
 
 
 
 
 
 
 
 
 
   
6
 
OsteoScope  

 
A  Working  Prototype
 
Project  Development    
 
 
 
 
 
 
 
 
 
 
     
6
 
Design
 
Experiment
 
Integration
 
Feedback
 
Working  Prototype    
 
 
 
 
 
 
 
 
 
 
   
7
 
CT  Scan  to  3D  Application  Workflow
 
Prototypal  Specimen    
 
 
 
 
 
 
 
 
 
 
   
9
 
Problems  with  Raw  CT
-­‐
Derived  Mod
els    
 
 
 
 
 
 
 
   
9
 
Software    
 
 
 
 
 
 
 
 
 
 
 
 
   
9
 
The  Workflow    
 
 
 
 
 
 
 
 
 
 
 
   
10
 
Workflow  Tutorials    
 
 
 
 
 
 
 
 
 
 
   
10
 

Workflow  Tutorials
 
Isolating  Tissue  &  Generating  Raw  Surface  Mesh  

 
OsiriX  (32/64
-­‐
bit)
 
Database  Interface
   
 
 
 
 
 
 
 
 
 
 
   
11
 
Importing  Scan  Files
 
 
Impo
rting  DICOM  Files
   
 
 
 
 
 
 
 
 
 
 
     
12
 
Importing  JPEG  Files
   
 
 
 
 
 
 
 
 
 
 
     
13
 
Workstation  Interface
   
 
 
 
 
 
 
 
 
 
 
   
14
 
Isolating  Bone
   
 
 
 
 
 
 
 
 
 
 
 
   
15
 
Determining  Bone  Density
   
 
 
 
 
 
 
 
 
 
     
16
 
Methods  for  Isolating  Bone  by  Pixel  Value
   
 
 
 
 
 
 
 
     
16
 
Method  1:  
Isolating  Specific  Individual  Bones  (ROI  Grow  Region  Method)
 
 
 
 
 
     
17
 
Method  2:  Isolating  all  Bones  (Pixel  Value  Method)
   
 
 
 
 
 
 
     
20
 
Generating  Surface  Mesh
   
 
 
 
 
 
 
 
 
 
   
21
 
Exporting  Surface  Mesh
   
 
 
 
 
 
 
 
 
 
 
   
22
 

 

3

Model  Optimization  &  Retopology  

 
3D
-­‐
Coat
 
(v3.7)
 
3D
-­‐
Coat  Interface
   
 
 
 
 
 
 
 
 
 
 
   
23
 
Viewport  Functions
 
Keyboard  Navigation
 
Retopo  Room
 
AUTOPO
   
 
 
 
 
 
 
 
 
 
 
 
 
   
26
 
Importing  a  Mesh  for  AUTOPO
 
AUTOPO  Parameters
   
 
 
 
 
 
 
 
 
 
 
     
26
 
Intermediate  Resolution
 
Approximate  P
olycount
 
Smoothing
     
 
 
 
 
 
 
 
 
 
 
 
     
27
 
AUTOPO  Parameters  Summary
   
 
 
 
 
 
 
 
 
     
27
 
Manual  Settings
   
 
 
 
 
 
 
 
 
 
 
     
27
 
Density  Modulator
 
Edge  Flow
 
AUTOPO  Calculation  Process
 
AUTOPO  Mesh
   
 
 
 
 
 
 
 
 
 
 
 
   
29
 
Generating  Additional  AUTOPO  Meshes  of  the  Same  Model
 
Saving  your  3D
-­‐
Coat  File
   
 
 
 
 
 
 
 
 
 
 
   
30
 
Exporting  a  Retopo  Mesh
   
 
 
 
 
 
 
 
 
 
   
30
 
 
Editing  the  OsteoScope  Application  in  Unity
 
Introduction  to  Unity    
 
 
 
 
 
 
 
 
 
 
   
31
 
Basic  Overview  of  Unity  Editor  Layout
 
Scene    
 
 
 
 
 
 
 
 
 
 
 
 
     
32
 
Game
 
Hierarchy    
 
 
 
 
 
 
 
 
 
 
 
     
33
 
Project  (Assets)
 
Inspector    
 
 
 
 
 
 
 
 
 
 
 
     
34
 
Console
 
Setting  Up  OsteoScope  as  a  New  Project  in  Unity
 
Setting  Up  a  New  Project  in  Unity      
 
 
 
 
 
 
 
 
   
34
 
Importing  
OsteoScope  Working  Files
 
Unity  Packages  
 
 
 
 
 
 
 
 
 
 
 
 
     
35
 
Importing  the  OsteoScope  Unity
 
Exporting  Unity  Packages
 
OsteoScope  Project  A
ssets
 
Fonts    
 
 
 
 
 
 
 
 
 
 
 
 
     
36
 
guiSkins
 
Icons
 

4

Materials    
 
 
 
 
 
 
 
 
 
 
 
     
37
 
Models
 
Plugins
 
Prefabs
 
Scenes
 
Scripts    
 
 
 
 
 
 
 
 
 
 
 
 
     
38
 
OsteoScope  GameObject  Hierarchy  and  Scripts
 
Creating  and  Editing  Scripts      
 
 
 
 
 
 
 
 
 
   
38
 
Implementing  Scripts      
 
 
 
 
 
 
 
 
 
 
   
40
 
OsteoScope  GameObjects  and  Scripts
 
scriptMaster    
 
 
 
 
 
 
 
 
 
 
 
     
40
 
camTargetMaster    
 
 
 
 
 
 
 
 
 
 
     
41
 
python
-­‐
cranium
 
scriptSlaves
 
viewingRig    
 
 
 
 
 
 
 
 
 
 
 
     
42
 
Main  Camera
 
How  to  Incorporate  a  Different  Cranial  Model  into  OsteoScope    
 
 
 
   
42
 
Building  a  Ve
rsion  of  OsteoScope  as  a  Web  Application    
 
 
 
 
 
   
49
 



5

Credits  &  Acknowledgements
 
A Master’s Research Project


Submitted in conformity with the requirements for the degree of

Masters of Science in Biomedical Communications (MScBMC)


Offered through the

Institute of Medical Science, Faculty of Medicine

University of Toronto Mississauga


©2013 Agnes Chan




Agnes Chan, MScBMC candidate, BSc

Website: http://www.taxonstudios.com

Email: agnes
.chan@taxonstudios.com


Project Supervisor

Dave Mazierski, BScAAM,
MSc, CMI


BMC Committee Member

Shelley Wall, AOCAD, MScBMC, PhD


Content Advisor

Robert Reisz, BSc, MSc, PhD


Special thanks to:

Jodie Jenkinson, BA, MScBMC, PhD

Michael Corrin,
BFA, BA, BSc, MScBMC

Jessie Maisano, BA, MPhil, PhD

Timothy Rowe, BSc, MSc, Ph
D




6

Project  Overview
 
OsteoScope  

 
A  Working  Prototype
 

OsteoScope was firs
t conceived as an interactive 3D digital tool to visualize palaeontol
ogical cranial
specimens. It was based on

the potential learning and research advantages in combining CT

imaging
data
, which are objective digital representations of physical specimens, with interactive 3D technology
such as gaming engines
. The goal was

to produce a virtual reality environment
,

which augments the
ways in which the specimen can be visually ma
nipulated.

Project  Development
 
In collaboration with
a
content expert, vertebr
ate paleontologist Dr. Reisz,

BMC

committee members,
Prof. Dave Mazierski and Dr. Shelley Wall, and BMC New Media lecturers Prof. Michael Corrin and Dr.
Jodie Jenkinson, a workin
g proto
type of OsteoScope

was developed
using Unity, a 3D gaming engine
and development software
.
As much of this project was experimental


adapting existing technologies
for alterative purposes


an
iterative

process of

design,
experiment
,
integration,
a
nd
feedback process

was followed
to build up
and continually revise
the fun
ctions

of
the application.



Design
 
The first stage is con
ceptualizing what function
s
should

be

include
d

in the application. It is at this
stage that we also discussed the importan
ce of each function. Due to the complexity of the initial
conceptualization of the project and the limited tim
e available for development, it was necessary
to
prioritize the functions according to importance. For example, the basic navigation functions wer
e
essential, while the ability to change th
e colour of the model was

ultimately not included in the
application.

Experiment
 
In order to tackle the various technological challenges

associated with dev
eloping different function
s,
it was essential break up th
e project into individual component
s and develop each function separately.
Each function

was first built as a proof of concept within Unity to develop the required scripts and
programming strategies.

Integration
 
Once it has been shown through a proof

of concept that a function

is possible, it was

incorporate
d it
into the

main OsteoScope project.

Feedback
 
New

functions

were continuously presented
to the content expert,
committee, profess
ors, and peers
to gain feedback
on how to improve them
.

Design
Discuss what
visualization
function to
include & why it
would be useful

Experiment
Explore
technological
aspects of
function

Integration
Incorporate
function into
application

Feedback
User tests &
progress
meetings to
improve function


7

W
orking  Pr
ototype
 
The final working prototype represents
numerous
repetitions of the iterative process

to build
up the
number of

function
s in

the application. Below are screenshots of OsteoScope and
a summary of the
function
s that were
included.


This is the basic
interface of the application. The navigational menu (
orbit
,
zoom
,
explode
) is located
that the top of the viewport. Users can activate these functions by clicking on the icon, or by using
k
eyboard shortcuts (
instructions

are available

via a pop
-
up menu
).

T
he icon colour changes when it is
clicked on, and the button background colour
changes when a particular nav
igational function is
activated
.

These colour changes provide visual aids for which function is currently active, especially
when the user uses both

the buttons and keyboard shortcuts interchangeably.



This screen shot demonstrates the
explode

function, one of the key features of this
application. Users can move the individual bones
of the cranium apart to reveal internal structures.
They can also bring the cranium back into the
intact position.




8


Here, the user has

changed

the camera
target

from the centre of the cranium
/viewport

to a
specific bone (in this case, the green bone)
. They

then used the
ruler tool

to set two
markers

on
that bone, and find the
linear distance between
the two markers
.











Users

are also able to
toggle the vis
ibility of
each individual bone
. When a bone is togg
led
off, the user can vary its opacity

from 0
-
50%,
enabling the context of the entire cranium to be
retained if desired,

while examining components
of the cranium that are not normally visible in the
inta
ct cranium.









Lastly, users can

hide

the menus

when they are
not in use
,

to
so that they do not obscure the
viewport.















9

CT  Scan  to  3D  Application  Workflow
 
A number of difficulties were encountered
the process of
incorporating a 3D model
derived from CT
s
cans into our Unity application
.

As the result of experimenting with different softwares and methods,
a workflow was developed to optimize raw CT
-
derived 3D models such that they could be brought
into an end
-
product 3D application.

Prototypal  Specimen
 
Originally, scans of fossils specimens from Dr. Reisz’s lab were going to be used in the application,
but it became apparent the similarity between fossil specimens and their surround
ing

rock matrix
rendered them too difficult to isolat
e without expert knowledge

of the specimens

within the timeframe
allotted for the project.


It was decided by the committee that

scan of an extant o
rganism
would be used instead to develop
the prototypal application
.
DigiMorph, a digital library of 3D morp
hological images at the University of
Texas at Austin
, generously offered the use of one of their scans
. A scan of a Burmese python (
Python
molurus
)
1

cranium was chosen, because the bones of a snake cranium are relatively unfused.

Pro
blems  with  Raw  CT
-­‐
Deri
ved  Models
 
In addition, surface meshes extracted from CT scans are disorganized in terms of polygon geometry,
and consist of too many polygons to be used immediately in end
-
product visualizations, such as real
-
time render

3D applications

or animation. Ther
efore, an intermediate optimization step is required to
prepare the CT
-
derived model such that it can be incorporated into a 3D application.


Software
 
This workflow involves the use of these four applications:



OsiriX

32/64
-
bit

DICOM viewer for 3D
medical image files (e.g. MRI, CT)

Similar software: MicroDICOM, Amira DICOM



Pilgway
3D
-
Coat

v3.7

V
oxel sculpting & retopology too
l

Si
milar software: Pixologic Z
Brush



Maxon
Cinema 4D

R14

3D modeling, animation and rendering application

Similar
software: Autodesk Maya
, Blender



Unity

v4

Cross
-
platform 3D gaming engine & developer

Similar software: Unreal Engine








1

NSF grant IIS
-
0208675 to T. Rowe and DigiMorph.org


10

The  Workflow
 
Using the python cranial model as the prototype, this was the workflow that was developed for
processing the
CT scan

into a usable 3D model that can be incorporated into a 3D application:



A DICOM viewer/workstation,
OsiriX
, was used to initially process the CT scans; the cranial bones
were isolated from other tissues, and a raw surface mesh was generated of the bony
tissue. The raw
mesh was exported from OsiriX into
3D
-
Coat
, which has an auto
-
retopolog
y

(AUTOPO) function that
simultaneous optimizes mesh geometry and reduces polygon count. The retopologized model was
then brought into a 3D modeling and animation softwa
re,
Cinema 4D
, to fix unwanted arti
facts from
the AUTOPO process,
further refine the model
, and separate the model from a single mesh to multiple
mesh objects representing individual bones or group of bones
. Finally, the model was imported into

Unity
, wher
e the viewing application was simultaneously being developed
.

Unity permits
directly
importing

Cinema 4D
’s proprietary files; the model could
be modified in Cinema 4D

after it has been
imported into Unity
, and changes will automatically update to the impor
ted version in Unity.

Workflow  Tutorials
 
The applicability of this workflow extends beyond creating 3D biological models for use in 3D
applications. The retopologization and optimizing of CT
-
derived models can be more generally used to
render complex raw
surface meshes more usable

for various visualization purposes,

and reduces f
ile
size. The following section

describe, in detail, the workflow fo
r the first two steps of the workflow:
isolating a specific tissue type and generating a raw surface mesh of tha
t tissue using OsiriX, and
optimizing and retopologizing the raw mesh in 3D
-
Coat.



CT Scan
Processing
Raw 3D model
Retopology
& Optimization
Retopologized
model
3D Application
Refined
model
Manual
Refinement

11

Workflow  Tutorials
 
Isolating  Tissue  &  Generating  Raw  Surface  Mesh  

 
OsiriX
 
(32/64
-­‐
bit)
 
Database  
Interface
 

When you first open OsiriX, you will see the database interface.
A
library
of scan databases that have
been exported will appear in the central menu

(
red
)
. When you click on a dataset, a preview of
individual scans within that database will appear

(
blue
)
.
Clicking on a scan will allow you to preview
and scrub through
the images slices of that scan

(
green
)
.




12

Importing  Scan  Files
 
Importing  
DICOM
 
Files
 
OsiriX accepts DICOM (.dcm) files, which is the standardized format for producing, storing, and
distributing

medical imaging files
2
.




To import a DICOM dataset from your computer
, click

the

Import

icon
at th
e top of the
database



Alternatively,
you can
go to:


File <

import <

Import Files…


Select the folder that
contains your DICOM
(.dcm)
files. If your da
taset contains multiple scans, select
the parent folder of all individual scans. By doing so, all the individual scans will
be listed as

same
series within the OsiriX database.


You may choose to
link the files from their current location on your computer
or copy them to the
OsiriX application library. I recommend copying the links to prevent having multiple copies of the same
scan files on your computer.





Once imported, you can access your dataset in the database viewer within OsiriX.


 



2

DICOM Brochure (2013).
NEMA
. Accessed 8 July 2013 at
http://medical.nema.org/dicom/geninfo/Brochure.pdf.


13

Importing  JPEG  
Files
 
Alternatively, OsiriX also accepts image datasets that consist of sequential JPEG images. Once
imported, OsiriX will read the dataset as DICOM.


To import JPEG series, you will
first
be required to install

an OsirX plugin (
JPEG to DICOM
). To install
the plugin
, go to
:


Plugins < Plugins Manager < JPEG to DICOM < Download and Install


Once the plugin is installed, you can then import your JPEG dataset

by going to
:


Plugins < Database < JPEG to DICOM


Select the folder that contains your JPEG image ser
ies; the folder name will be the scan name within
the OsiriX database. You may change the patient name to one that is meaningful for your scan.


Once imported, your dataset will appear in the database viewer within OsiriX.


Note: If you acquire your scan a
s a JPEG series rather than a DICOM, make sure you have the field
of reconstruction for your scan. This data will be necessary for any 3D data manipulation.


The f
ield of reconstruction parameters

are as follows
:



Pixel X resolution



Pixel Y resolution



Slice

interval


 

14

Workstation  Interface
 

To use a scan dataset, double
-
click on it within the Database view.
A new window will open


this is
the workstation interface that allows you to view and manipulate your scan.

The scan will appear in the
main viewport.



Note: The free version of OsiriX supports a limited number of slice images per scan. If you are
using this
version, you may be prompted to select a subset of the slices to be displayed.




15

The slider above the viewport allows you to scrub the slices of
your scan. Various tools are available in
the menu bar above the slider. Take note of the mouse button tools (you may hover over these in the
interface to see their function):




Isolating  Bone
 
In this section, we will discuss how to bone from a CT scan,
but the procedure is applicable for all
tissue types.



C
T scans are essentially a sequence

of cross
-
sectional X
-
rays, such that the dataset is a series

of
images that represent a 3D volume when stacked.

X
-
ray images

are the result of density differ
ences
within the scanned object. Highly dense materials, such as bone,
block most

of the X
-
rays and are

represented as white regions on the image
. Less dense materials, such as soft tissue,
block some

X
-
rays and tend to appear in shades of grey. Air
allows all
X
-
rays

to pass through
, and appears

black on
the image.


 

16

Determining  Bone  Density
 
With this in mind, we can isolate different tissues based up
on their specific density. Bone
, being one
of the
densest tissues in the body, is

relatively easy to distinguish
on CT scans.


To begin, we first need to approximate the range of density values that represent the bones in our
scan. Under ROI

tools, select the Oval tool.


Enclose a bony region on an image slice, ensuring that the circle only encompasses bone. Take
note
of the min and max values. Sample several bony regions; the lowest min and highest max values will
be the approximate density value range for the bones in your scan.

Methods  for  Isolating  B
one
 
by  Pixel  Value
 
In order to generate a surface mesh of just

the bone, we need to isolate it from a
ll other tissues in the
scan. There are two
two methods to do this, depending on if you want to isolate a specific bone
(Method 1) or if you want to collectively isolate all bones (Method 2).


In processing the

p
ython

cranial CT data,
both methods

were tried
. Method 1
was initially used
in an
attempt to sort and separate the bones within OsiriX. However, Method 2
was ultimately used
in order
to ensure that all cran
ial bones are represented in the

3D model, and to separ
ate the bones at a later
step using different software, namely Cinema 4D since it is an optimized environment for 3D modeling.


 

17

Method  1:  Isolating
 
Specific  Individual
 
Bones
 
(ROI  Grow  Region  Method)
 
This method is for isolating specific bones
, but not all

of them,

within a scan containing multiple
bones. Once you have determined your min and max values for bone:


ROI < Grow Region (2D/3D Segmentation)


Note: If your scan was imported as JPEGs, you will be prompted
at this point
to input the field
of
reconstruction
:



Scrub to a slice in which your bone of interest appears. Within the
Segmentation Parameters

menu,
select the following options:

For algorithm, select



Threshold (lower/upper)


For the threshold values:



Lower Threshold: the predetermined

min value



Upper Threshold: the predetermined max value



When
the parameters have been set, click on your bone of
interest in the scan; this will be the starting point for the 3D
grow region. A transparent colour representing a Region of
Inte
rest (ROI)
will appear over the

bone, encompassing the
area defined by the lower/upper threshold values. You may
tweak these values at this point to optimal
ly enclose the

area
of interest.

When satisfied

with the ROI
, click
Compute
.




18


When the region propagation is

complete, you can scrub through your scan to see
that all areas with
the same density range and

in contact with
your starting ROI are now defined as part of the
same ROI
. If you notice that unwanted areas have been selected, you may use the
eraser

option of
the
Brush ROI Tool

to delete those areas from your ROI.


You may repeat this step to generate other ROIs within your scan, for example, if you wish to isolate
multiple distinct bones.


Once you have checked that the ROI properly represents your

bone o
f interest throughout your scan
(making sure that your ROI is selected)
, go to:


ROI < Set pixel values to


Use the following settings:



If current value is larger than: lower threshold
value for 3D Grow Region



If current value is smaller than: uppe
r threshold
value for 3D Grow Region



To this new value:
2000


Hit
OK
.


You will notice that all the pixels enclosed by your ROI
wil
l appear white acco
rding to your new value of 2000,
underneath the ROI colour.









19

Now, we want to set the pixel value to
all non
-
ROI areas to black
; go to
:


ROI < Set pixel values to




If current value is larger than:
-
3000



If current value is smaller than:
3000



To this new value:
-
3000


Hit
OK
.














Now, we have our ROI represented by one pixel value (2000, white) and non
-
ROI regions represented
as another pixel value (
-
3000, black). Remember
the

pixel value

you set for the bone ROI

for the next
step.




20

Method  2:  Isolating  all  Bones
 
(Pixel  Value  Metho
d)
 

Note: Skip this

section if you have already completed Method 1


This method does not use a particular Region of Interest (ROI), but simply selects

and isolates

all
tissues that fall within a given density range. This method i
s useful if you wish to hav
e a complete of all
the bones in a scan.


Once you have determined the min and max pixel va
lues that represen
t bony tissue, delete the Oval

you used to determine the pixel values (click + delete). Then
, go to
:


ROI < Set pixel values to





If current value

is larger than:
min value



If current value is smaller than:
max value



To this new value: 2000


Hit
OK
.


You will notice that all the pixels
that represent bone in
your whole image series

will appear white according to
your new value of 2000.







Now,
we want to set the pixel value to all non
-
ROI areas to black:


ROI < Set pixel values to





If current value is larger than:
-
3000



If current value is smaller than:
1999



To this new value:
-
3000















21



Now, we have our bones represented by one
pixel value (2000, white) and all other tissues
represented as another pixel value (
-
3000, black). Remember the pixel value you set for the bone for
the next step.


Generating  Surface  Mesh
 
To generate the surface mesh:


3D Viewer < 3D Surface Render


A new

Surface Rendering

window will open, and a dialogue box for setting up the surface r
ender will
automatically pop up:


For

the

best mesh quality,
set all options to the
maximum. For the
First Surface
, set the pixel value for
the one we set for the bone in
the previous step (2000,
unless you chose another value).


Hit
OK
, and wait for the surface

rendering process to
complete (This might take some time due to the high
resolution settings).









22

A 3D model representing the bony tissue of your scan will
appear

in the viewport:




Exporting  Surface  Mesh
 

To export this mesh, click on
Export 3D
-
SR

in the top menu
.
Export the file as .obj,
which is an acceptable format 3D
-
Coat, which is the next step of our process.






23

Model  Optimization  &  Retopology  

 
3
D
-­‐
Coat
 
(
v3
.7
)
 
3D
-­‐
Coat
 
interface
 
Viewport  Functions
 

3D
-
Coat’s main menu bar is

located immediately above the viewport. The right side contains the most
basic tools for manipulating the viewport: the display and navigational options. To operate these
funct
ions, you click the icon and drag your mouse.





View functions

(
Icons
1
-
3)

o

Brightness: The amount of ambient light in the scene

o

Contrast: The difference between light and shadow areas

o

Light position: The position of the ambient light in the viewport



Nav
igation

functions

(
Icons
4
-
6)

o

Orbit

o

Pan

o

Zoom




24

Keyboard  Navigation
 
You may navigate the 3D
-
Coat viewport using
the same

keyboard commands as Cinema4D and a 3
-
button mouse:


Orbit:

Option + LMB

Pan:
Option + Scroll button

Zoom

(Dolly)
:

Option + RMB


Note:
When using a Mac

(OSX 10.7 Mountain Lion)
, make sure that your mouse is configured
so that the scroll button functions as Mouse Button 3 and is not linked to
Miss
i
on Control

functions
.


To change mouse button settings, go to:


System Preferences < Mission
Control


Make sure that none of the Mouse Shortcuts are mapped to Mouse Button 3 (which is the scroll
wheel button).




25

Retopo  Room
 

The left side of the main menu bar is for selecting between 3D
-
Coat’s six primary functionalities

(
red
)
.
The room in which we are interested in for our purposes is the
Retopo

room.


Once inside the Retopo room, the retopology tools will appear on the left side of the viewport

(
blue
)
.
These tools are for manual retopology, where the user manually places polygo
nal faces
on the surface

of
a reference model to create a new
retopologized mesh.
These

tools

will not be discussed as they
are not a part of the

workflow
, but note that these tools are may be useful for fine
-
tuning your
AUTOPO
mesh.


On the upper right si
de of the viewport, there are
two tabs: UV preview and Groups

(
green
)
. UV
pre
view provides a quick reference

of
retopology mesh during and after it has been generated
.


Groups is where your retopologized meshes are housed. A group is created by default wh
en
you enter
the Retopo room. If you’re doing a manual retolology, you may create multiple groups to represent
different mesh objects. For example, if you were retopologizing an animal model for animation, you
may want the body and limb as separate mesh ob
jects. AUTOPO meshes will automatically be
stored
here as a single group object.



 

26

AUTOPO
 
AUTOPO (Auto
-
Retopology) is a proprietary, algorithm
-
based function in 3D
-
Coat
where the computer
automatically generates a retopologized mesh based on a series of
parameters defined by the user.

Importing  a  M
esh  for  AUTOPO
 
To begin the AUTOPO process, we first import the model t
hat we wish to be retopologized:


File < Import < Import for AUTOPO


3D
-
Coat accepts a number of common 3D file formats, including .obj and
.fbx.


After you have selected your object, a dialogue box will appear over the viewport for you to input the
AUTOPO settings.


Note: You normally do not see your model appear in the viewport immediately following import.
In the background, 3D
-
Coat automat
ically converts your model into a voxel (volume
-
based)
model from a polygonal, surface
-
based model.


AUTOPO  Parameters
 

There are three user
-
defined numerical parameters

with

which AUTOPO will use to generate the
retopologized mesh:


Intermediate  resoluti
on
 

This parameter is for is an initial mesh that is generated
during the AUTOPO process, upon which the final mesh
will be based.

For our purpose of modeling biological
specimens, we want a high intermediate resolution in
order to retain as much detail of

our original model.
However, extremely large values may cause the
software to crash or not complete the AUTOPO process
at all.


For the python model,
the AUTOPO process

was successfully ran

with
an intermediate resolution of
up to 5,000(x1,000). Further t
rials will be required to for a better idea of an upper threshold.


Approximate
 
polycount
 
This parameter defines the targeted final polygon count for the retopologized mesh.
A greater value
will result in a more complex, detailed model.


When determining
this value, consider the final destination for your model. For example, if you are
planning to incorporate the model into a real
-
time 3D engine such as Unity, you may have to limit the
pol
ycount for optimal performance.



27

Smoothing
 
The smoothing parameter d
etermines the degree to which you wou
l
d like
AUTOPO to smooth out
noise and details on the original model. Since we wish to maximally capture the nuances of our
biological specimens, we always set this parameter to 0 for no smoothing.

AUTOPO  Parameters  
Summary
 
From
experimental AUTOPO trials
of the python model
in 3D
-
Coat,
it was

determined how each factor
affects the qualit
y of the

retopologized model. In general, there is a trade
-
off between model quality
and AUTOPO processing time.


Greater intermedia
te resolution



More detailed model

Better fidelity to original



Longer AUTOPO time

Bigger file size

Greater polycount



Less smoothing




Manual
 
S
ettings
 
Density
 
Modulator
 

Using Density Modulator, you may opt to define areas of the model in
which you would like greater
polygonal density generated by manually painting on the model’s surface. For example, you may find
that with a few AUTOPO trials that some details in a certain area are not being capture
d
, and you may
want to try doubling the p
olygon density over that area.




28

Edge  Flow
 

Edge flow allows you to draw a path on the model where you would like UV map seams to occur.
AUTOPO will automatically generate seams if you do not define any
, but if you have specific locations
you would like f
or your UV seams, you may define them here.


AUTOPO  Calculation  Process
 
Once you hit
Next

in the Edge Flow dialogue box, it will disappear and the AUTOPO process will
begin. As of 3D
-
Coat v3, there is no progress indicator for the AUTOPO process. Instead,
the system
wait cursor will appear. This is normal, and AUTOPOs with high
-
resolution parameters can take over 1
hour. Let the process run.


Here are
the AUTOP
O process duration times for the

python
trials. These numbers are
by no means
definitive and the
duration time will depend on the original model
’s

complexity, but will give you some
idea of how long to expect the AUTOPO process should take with

a

given
set of
parameters.


Trial

Intermediate
Resolution (x1000)

Approximate
Polycount

Additional
Smoothing

Final
Polycount

AUTOPO
Time

1

500

10,000

2

9,312

4 min

2

500

20,000

2

19,152

7 min

3

500

25,000

2

24,127

12 min

4

500

35,000

2

33,849

9 min

5

500

35,000

0

33,375

23 min

6

500

50,000

0

48,087

33 min

7

750

50,000

0

48,465

31 min

8

1,000

75,000

0

72,376

25 min

9

5,000

75,000

0

73,162

50 min




29

AUTOPO  M
esh
 

After the AUTOPO process is completed, you will see that a mesh has appeared over your original
voxel model. The polygon statistics for the retopologized model will appear at the bottom of the
viewport

(
red
)
; it will give you counts for the
total poly count, and number of each polygon type (tris,
quads, and N
-
gons).


Your retopologized mesh will appear as
an object under the Groups tab at the upper right of the
viewport

(
blue
)
. As well, your ori
ginal voxel
-
converted model is located under the VoxTree at the lower
right of the viewport

(
green
)
. You may toggle the visibility of these objects, change their names, or
delete them within these menus.



 

30

Generating  A
dditional
 
AUTOPO  Meshes  of  the  Same  
M
odel
 
You may wish to generate

several iterations of the AUTOPO process with d
ifferent parameters to find
an optimal retopologized mesh or your original. To run another AUTOPO process of the same model,
right
-
click on the original model under VoxTree

and select
:


AUTOPO < AUTOPO


You will go through the same set of dialogue box
es as with the previous AUTOPO.


Once the second AUTOPO mesh has been generated, it will appear as
a separate object within the Groups menu.
We recommend a workflow
where you
generate and
store multiple AUTOPO meshes within a
single 3D
-
Coat file. That way, you will have access to all iterations for
easy
comparison
.

 
 
Saving  
your  3D
-­‐
Coat  F
ile
 
To save your 3D
-
Coat file
, go to
:


File < Save


Your file will be saved at your selecte
d location as a .3b file along with a .jpg image. As with any
project, we recommend frequent, iterative saving of your file, especially following AUTOPO processes
that take hours to complete.


Exporting  a  Retopo  M
esh
 
When

export a retopologized mesh,
you m
ust delete all other objects in the Groups menu except
for the object you wish to export
.

Otherwise, 3D
-
Coat will export a single object containing all
objects within Groups. For this reason, ensure that your file has bee
n saved before exporting a mesh;
th
en, go to:


File < Export retopo mesh


Export your model as your chosen 3D object file format. We recommend .obj, since it is compatible
with most 3D applications.




31

Editing  the  OsteoScope  Application  in  Unity
 
The purpose of this section of the documentation is to provide the basic understanding of Unity and
the OsteoScope project so that someone who has never used Unity can quickly begin to work with the
OsteoScope development files.
In the following sections,
I provide a primer for Unity’s development
environment and a brief overview of OsteoScope’s project structure
, as well as step
-
by
-
step
instructions on how to incorporate a different cranial model into the OsteoScope’s current framework
and building out a U
nity application.

It is not necessary to read over every section, especially if you
have some prior knowledge

of Unity.

Introduction  to  Unity
 
Unity is a cross
-
platform 3D game developer and engine; developers can build games

(or other
applications)

within the Unity editor environment, and then easily output the game to different
platforms including web, PC/Mac, game consoles, and mobile devices. The editor application comes
in free and paid license versions; the free version is adequate for the full

development of games, but
has some feature and customization limitations.
OsteoScope was developed usi
ng the free version
of Unity 4.1.5
; the project files can only be edited using this or newer version of Unity
.


Basic  Overview  of  Unity  Editor  Layout
 
Th
is layout of the Unity Editor is a customized version of the
2 by 3 layout
. Premade layouts may be
selected from the top
-
right dropdown menu. They layout may customized clicking and dragging

32

menus to different positions, resizing menu, and opening addition
al menus under

Windows
. For this
particular layout, I changed the
Project

menu
view from two
-

to a
one
-
column layout

by clicking on
the dropdown button a
t the top
-
right of the Project m
enu. I also added a
Console

menu to have quick
access to any scripting errors as I develop.

Scene
 
This window depicts the scene you are currently
editing.
Unity games are built as a sequence of
scenes; you may think of a scene as a level
within a game, with all associated
GameObjec
t
s
such as characters, ca
meras, landscape
elements, etc. All
GameObject
s in a scene are
listed in the
Hierarchy

menu. To place standard
Unity
GameObject
s into the scene, select the
desired object from the
GameObject

menu. To
place a custom
GameObject

from
your
Project
(Assets)

library, simply drag the object’s name
into the scene; custom
GameObject
s include
imported 3D models and prefab 3D objects built
within Unity.


Navigating the Scene is the same as most 3D modeling applications:

Orbit:

Option + LMB

Pan
:
Option + Scroll button

Zoom (Dolly):

Option + RMB

Game
 
This window enables you to preview the current
scene of your game

as if it has been built
. The
Game window is controlled by the set of buttons
at the top
-
centre of the Unity editor. In Play
Mode, yo
u may make changes to GameObject
properties in the Inspector, but
these changes
will not be saved

after exiting Play Mode (you
also cannot save your scene when during Play
Mode).







Note: OsteoScope was designed at a player resolution of
1024 x 576. To

ensure that the entire play is
visible in Play Mode, select Maximize on Play so that the scene will play in full screen.


 

33

Hierarchy
 
As previously mentioned, this menu lists all
GameObject
s in the current
scene.
A
GameObject

is

any object

that can be placed in a scene
;
different
GameObject
s have different properties that can be viewed in
the
Ins
p
e
ctor

window
, but all
GameObject
s have an associated
Transform

component
, which indicates the position and rotation of the
object
.


Each
GameObjec
t

has an active/inactive state that can be toggled in
the
Inspector

menu
, by checking/unchecking the box to the left of the
GameObject

name
.



GameObject
s  Hierarchies  and  Scripts
 
The way to make anything “work” in Unity is to create scripted functions, and attach
an instance

of

these scripts to
GameObject
s. This is why the relative relationships of

GameObject

in the hierarchy
are

important, because properties or scripts attached to

“parent” objects affect its “children” objects.

As with most 3D applic
ation, you may create Empty (e.g.

“Null”)
GameObject
s t
o

act as parent script
containers for children objects.


The parent
-
child hierarchical relationship becomes critically important i
f you use script commands
where one script “talks to” another script. For example, the “Broadcast Message” command activates
a function in another script; for this to work, the “Broadcast Message” command script must be
attached to a parent object in order

to activate a function on a script attached to a child object.

Project  (
Assets
)
 
The
Project
assets window houses a library of all the editable files in
your game/application. These include imported models, scripts,
scenes, custom GUI skins, and prefabs.

You may rename assets or
change the file structure of your assets library
at any time
without
disrupting

their linkages in the Hierarchy as long as you make
these
changes within the Project
menu in Unity

(rather than outside of Unity);
however if you chan
ge a script’s name, remember to also change any
references to that script in other scripts

(errors will appear in the
Console if there are script name inconsistencies)
.










34

Inspector
 
The Inspector allows you to examine the properties of a
GameObject

o
r asset, including a list of scripts attached to it a
GameObject
. If your
script has public variables, you may modify these variables on the
instance of the script attached to a particular
GameObject
; this enables
you to, for examp
le, set different names f
or each cranial bone in

the
Labels script without having to create a new script for each bone.

 
 
 
 
 
Console
 
The Console display
feedback from your application as you are
developing it. White speech bubbles indicate feedback logs that from
debugging code in the scripts. Yellow triangles are warnings for
potential areas of problem in the code. Red octagons indicate
critical
coding er
rors that must be fixed; the application cannot be previewed
in Play Mode or built if there are coding errors. The Console is quite
“smart” in that it will indicate in which script

the problem is occurring,
and will attempt

to diagnose the error for you.

S
etting  Up  OsteoScope  as  a  New  P
roject  in  Unity
 
Setting  Up  a  New  P
roject  in  Unity
 
In order to open the OsteoScope working files, you must first create a new project in Unity. Open the
Unity editor application, and go to:


File < New project…




A dialogue
box will open up to select the file directory for your
new project. Following Unity best practices, once you set up
the file location for your project
you should not move
the
project file or its contents

to avoid breaking important file
linkages, so consid
er this the permanent location of your
project as you are developing it. If you frequently change
computers, I recommend placing your project on an external
hard drive.


Click
Create Project
, and Unity will automatically set up
subfolders and required file
s within your main project folder.


35

Importing  Oste
oScope  Working  F
iles
 
Unity  Packages
 
The OsteoScope working files are bundled as a
Unity Package

in the DVD accompanying this
manual. Unity Packages

may be considered portable file bundles, and
are t
he best p
ractice ways of
moving
assets between projects. Unity has a built
-
in set of packages that include commonly used
GameObject

and scripts

(available under
Assets < Import Package
)
; additional packages are
available

or free download or purchase from

t
he Unity
Asset

Store

(
Window < Asset Store
)
.

Importing  the  OsteoScope  Unity  Package
 
To import the OsteoScope, or any other custom Unity Game Package, go to:



Assets < Import Package < Custom Package…


Find the OsteoScope Unity Package file

on the DVD (
osteoscope
-
v
1.2.5
-
assets.unitypackage
), and
double
-
click on it.
A dialogue will open up, listing all the OsteoScope assets in a hierarchical form:


You may pick and choose which files to import
from

a Unity Package. In this case, we want to import
all files; all files should be checked by default, so click
Import
.

The imported files will now appear
under the Project tab within the Unity Editor.

Exporting  Unity  Packages
 
As previously mentioned, you sh
ould never move your project files from their originally established
locations
; Unity projects have critical background file linkages, and disrupting these linkages can
result in a total and irreparable corruption of your project.


I
f you would like to rel
ocate a project or bring assets of one project to another,
instead of moving a
project file from your system file browser
you should export the assets as a custom Unity Package:



Assets < Export Package…




36


Select the assets you would like to export, mak
ing sure the
Include Dependencies

is checked. Once
you create this package, you can transfer your project assets to an existing or new Unity project.
Object propertie
s and hierarchy relationships from the old project will be retained in the imported
scenes.

OsteoScope  
Project  Assets
 
This section describes the assets
in OsteoScope’s library

(the files listed in the
Project

menu)
.

These
are the elements of the application that are customizable.


To import assets into the Project library, you can simply
drag files

from your system file browser

into
the Project menu within Unity. Alternatively, you may copy files into the assets folder of your project
files using your system file browser. However,
be careful not to modify any other files
outside of
the ass
ets folder

in the project to avoid corruption.

Fonts
 
This folder contains c
ustom fonts for the GUI
.

Fonts are implemented by modifying font pro
perties of
GUI Skins using the I
nspector.

guiSkins
 
This folder contains c
ustom skins for GUI elements. New skins
may be created under:



Asset < Create < GUI Skin


Once a skin is created, it may be edited using the Inspector.
GUI Skins may
be used to modify a set of
GUI styles

in a script.

In this version of OsteoScope, GUI Skins were primarily used to optimize text
size and spacing for different GUI elements on different scripts.



37

Icons
 
These are icons that are used in the GUI. They were created in Adobe Illustrator, exported as .png files
and imported into Unity.

To specify an icon for a GUI element, it must be defi
ned as a
2D Texture

variable in the script. Then, in the Inspector, drag the desired icon into the variable.


Materials
 
Materials are the surface textures/skins of the 3D models in the project. When you import a 3D model
into Unity, any associated materials will be imported to the
Project folder as well
.


Models
 
This folder contains the 3D cranial models associated with the

project. For OsteoScope, the only
imported 3D model is the python cranial model
.

Details on
bringing in a new model into OsteoScope

are available in the
How to Incorporate a Different Cranial Model into OsteoScope

section below.


Plugins
 
Plugins are a set

of Unity scripts that have been developed by other users to enable a certain function
for your Unity application. The Unity Asset Store
(
Window < Asset Store
)
contains many free

and paid
plugins; if applicable
, they prevent you from having to script those

functions from scratch.


OsteoScope uses only one plugin, iTween. iTween enables smooth transform animations, and is
utilized in the “Change camera target” function, in which the camera orbit target changes from the
centre of the viewport to a
specified

b
one. Documentation for the usage of iTween can be found at:
http://itween.pixelplacement.com/documentation.php

Prefabs
 
Prefabs are reusable GameObjects. When you place a prefab into a scene
, an instance of it is created.
Modifying a prefab will also modify all instances of it.


All imported 3D models, including the python cranial model, are essentially prefabs.

T
he Prefabs folder
in this project contains two objects,
markerA

and
markerB
. The
se are the spherical objects that are
instantiated on the python cranial model to define the linear distance on the model for measurement in
the Ruler Tool.


Both of these objects were initially created as GameObjects within Unity:



GameObject < Create Ot
hers < Sphere


To convert a GameObject into a Prefab, drag it from the Hierarchy menu into the Project menu. The
GameObject’s name in the Hierarchy will then turn blue, to indicate that it is now an instance of a
prefab.

Scenes
 
As described before, a Scene

is a particular set
-
up of GameObjects and their associated properties
within a Unit
y game that is being developed.
This version OsteoScope consists of only one scene
(although you can conceivably build multiple scenes with different cranial models that can be selected
from a “main menu” scene). As I developed OsteoScope, I used mainly scenes as a means of
versioning in

the development process by duplicating scenes to retain a back
-
up version prior to
major changes; this is done in the
Assets

library (under
Scenes
), as Unity scenes are considered
assets.



38

To implement this workflow, when you wish to start modifying Osteo
Scope, I suggest first creating a
copy of the template scene in the Scenes folder, and modifying the copy rather than the original.
Create a copy of your current scene if you anticipate making a major change to the project so that you
can always revert to
an older version if necessary.

Scripts
 
Scripts are the set of codes that enable all functionalities within a Unity game/application. GUI
elements
and functions are also encoded in scripts.
Unity supports a number of scripting languages;
OsteoScope is
entirely scripted using JavaScript (with the exception of the iTween plugin, which is
coded in C#).


In order to modify OsteoScope func
tionalities, you understand the basics of coding with JavaScript. If
you do not have any prior experience with JavaScript

but would like to learn the basic essentials to be
able to use Unity, I suggest the following online tutorial on
http://www.lynda.com
:



Unity 3D 3.5

Essential Training

Chapter 4. Introducing Unity Scripting

Chapter 13
.
Creating Game GUIs


These two chapters are primers for creating the most basic functions in Unity, as well as how to use
scripts to create GUIs.


Unity provides extensive documentation on scripting functions that can serve as a guide for how to
approach
certain functions for your application. The scripting reference is available at:
http://docs.unity3d.com/Documentation/ScriptReference/
.


A GUI
-
specific scripting reference is available at:
http://docs.unity3d.com/Documentation/Components/GUIScriptingGuide.html


The scripts that were used in the developme
nt of OsteoScope will be described in the following
section (Hierarchy). Since scripts must be attached to a GameObject in the scene to be activated, it
will be easier to explain how each script works in relation to OsteoScope’s GameObject hierarchy.

Osteo
Scope  GameObject  Hierarchy  and  Scripts
 
Below is a list of OsteoScope’s GameObject hierarchy, and the scripts associated with each
GameObject:


script
Master          
Master  Script,  Keyboard  Instructions
 
camTargetMaster          
Cam  Target  Master
 
camTarget
 
python
-­‐
cranium
 
frontal_postfrontal_parietal,  
etc.
     
   
Explode,  Cam  Target,  Label
 
scriptSlaves        
 
Components  Toggle,  Measure
 
viewingRi
g      
   
Orbit
 
backLight
 
frontLight
 
Main  Camera      
   
Cam  Zoom
 


39

Creating  and  Editing
 
Scripts
 
By default, scripting in
Unity is accomplished using a separate software called MonoDevelop, which is
bundled with the Unity developer software when you download it. When you open a script in Unity, it
will automatically open in MonoDevelop.


To create a new JavaScript script, go
to:



Assets < Create < JavaScript


The same menu is also available if you right
-
click in the
Project

menu.
The new script will appear in
the Projects menu, where you may edit the file name.


To edit an existing script, double
-
click
on it within the
Project
menu, or the
reference to it within the
Inspector
.















It will open up in MonoDevelop, where
you can view and edit the code.



40

Once you save a script in MonoDevelop, the changes will be examined by Unity, and any coding
errors will be indicated in the
Console
.

Remember that
Unity
cannot

play a scene or build the
application if there are scripting errors
.


To facilitate the use of
OsteoScope scripts by other developers, I made notes regarding version
changes and in
-
line comments within all the scripts. Comments are non
-
coding text within the script,
and appear green when viewed in MonoDevelop; multi
-
line comments are wrapped by
/* *
/
, and
single
-
line comments begin with
//
. As
you code, it is helpful to leave comments for yourself and
others who may view your script, especially as the script becomes long and complicated.

Implementing  Scripts
 
In order to implement a script, an instanc
e of it
must be attache
d to a GameObject in the scene.


To attach a script to a GameObject, simply drag
the script from the
Project

menu onto the
GameObject in the
Hierarchy

menu;
alternatively, if the GameObject is currently
active in the
Inspector
, you
may also drag the
script into the GameObject’s properties menu in
the Inspector.


To deactivate a script instance, you may
uncheck it from the GameObject properties
within the
Inspector

(the checkbox next to the
script name)
.
If you want to completely remo
ve a
script instance from a GameObject (e.g., if you
have made a new version of the script and no
longer require the old one), you can right
-
click on
the script in the Inspector, and select
Remove
Component
.

 
 
OsteoScope  GameObjects  and  Scripts
 
The follow
section provides a summary of OsteoScope’s GameObjects and their associated scripts.

scriptMaster
 
scriptMa
ster is a null object

(known as
an

Empty Object in Unity)

that is the parent GameObject to
every other GameObject in the OsteoScope project.

For this
reason, scripts attached to this object
can potentially
have the highest
control

of any script

attach to any other GameObject in the hierarchy.
There are two scripts attached to it:

Master  Script
 
This script provides upstream control for a number of other scripts
that are lower in the hierarchy,
including all the navigation function scripts (
Orbit

Script
,
Cam Zoom

Script
,
Explode

Script
),
main
menu functions (
Labels

Script
,
Measure

Script
,
Cam
Target

Master Script
) and the GUI menus for
those functions. For that reason, it is the most complex script in the project; take caution when editing
this script, as it affects every
nearly every other

script.



41

It has a number of variables that can be edit
ed in the Inspector, including two custom GUI skins, and
all the icons for the navigation and main menus.

Keyboard  Instructions
 
Script
 
This script is for the pop
-
up GUI menu that displays the instructions for keyboard navigation. It also
contains the code
for the copyright box.

camTargetMaster
 
camTargetMaster is a null object that
contains a script (
cam

Target

Master

Script
) to
communicate
with

the downstream
cam

Target

S
cript
.
It is a child of the
scriptMaster

because it is controlled by
the
Master Script
,

but is parent to all other GameObject in the hierarchy.

Cam  Target  Master  Script
 
The function of this script is to change the camera target to a specific bone or back to the viewport
centre. When active, it calls upon on the
Cam Target Script

of the bone
that the user clicks on, and
moves the
camTarget

GameObject to become a child of the selected bone. The
viewing
Rig

orbits
around
camTarg
et
. When
camTarget

becomes a child of a bone, it adopts the position of that parent
object; therefore, the camera appear
s to orbit around that bone.

python
-­‐
cranium
 
This GameObject is an instance of the python cranium 3D model imported from Cinema 4D. It is a null,
parent object of individual GameObjects, each representing a bone or group of bones of the python
cranium. The
parent cranium GameObject itself has no scripts attached, but each cranial bone
GameObject has three scripts instances:

Explode  Script
 
This script enables the explode navigation function. The explode function works by identifying the
transform position of
the GameObject it is attached to (i.e. one of the bones), and then moves the
bone along a trajectory that is a multiple of the starting (x, y, z) position.

The maximum explode
distance and explode speed can be modified in the Inspector.

Cam  Target  Script
 
This script identifies the transform position of the bone GameObject it is attached to, which the
camTargetMaster
script retrieves when it is active and that bone is clicked on, and moves the
camTarget

GameObject to that position as a child of the selected

bone.

Label  Script
 
This script contains a variable to customize the name of each individual bone, and reveals a label
containing the bone name when the bone is hovered over. Each bone’s name can be edited under the
Labels Script properties in the Inspecto
r.

scriptSlaves
 
scriptSlaves is a null object that holds two scripts controlled by Master Script, but whose functions are
not specific to a particular GameObject.

Components  Toggle  Script
 
This script contains the GUI and functionality o
f the Components Men
u, enabling

selected bones’
visibilities to be toggled from 100% opacity to 50
-
0% opacity. Bones that are unchecked are also
functionally disabled


markers of the Ruler Tool will pass through these bones, the camera target
cannot be moved to that bone, an
d labels will not appear when that bone is hovered over.

Measure  Script
 
This script is for the Ruler Tool functionality. The
measure function works by instantiating

(“make
appear”) two markers onto the surface of a bone

GameObject, and determining the line
ar distance

42

between these two markers. The GameObjects that represent the markers can be set in the Inspector.
The markers are coded to adhere to the surface of the bone object, and to move with the bone when
the cranium is exploded.

viewingRig
 
viewingRig
is a null object that is the parent object of the two light objects in the scene, and the Main
Camera. The Orbit Script is attached to the viewingRig so that the lights orbit synchronously with the
camera while the cranial model remains static; this gives
the illusion that the cranium is orbiting and is
illuminated by a static light source.

Orbit  Script
 
This script is a modified ver
sion of a Unity standard script, MouseOrbit (available at
Assets <
Standard Assets < Scripts
), which orbits the camera around a

target object


in this case, the
camTarget

object, which by default is located at the centre of the viewport with the cranium model.
When the camTarget object moves to a bone, the viewingRig in turn orbits around that bone.

Main  Camera
 
The Main Camera de
termines how the user views the scene
. T
he Game menu represents what is seen
through the Main Camera, and is also how the application will appear once it is built.

Cam  Zoom  Script
 
This script is a camera script that enables the user to zoom in and out of t
he scene via the Main
Camera. The camera itself does not move, rather it is a camera effect.

The zoom speed, minimum and
maximum zoom distances can be modified in the Inspector.

How  to  
Incorporate  a  D
ifferent
 
Cranial  M
odel  
in
to  OsteoScope
 
With the current
project set up
, you

can
(relatively)
easily incorporate a
different

cranial model into
OsteoScope w
ithout having a deep understanding of the
project files
, and only changing one script
.
The foll
owing instructions assume
prior knowledge of Unity and the
OsteoScope project files as
described in the above sections; please refer to them if you encounter something unfamiliar at any
point.

1.  Set  up  OsteoScope  as  a  new  project  in  Unity
 
Please refer to the relevant section above for detailed instructions.

In th
e
Projects

menu, open the
template scene (
00
-
osteoscope
-
v1.2.5
-
template
).

2.  Import  
the  new  cranial  model  into  Unity
 
Import the 3D file of the new cranial model into Unity by dragging the
file from your computer’s file browser into Unity’s
Project

menu;
a
ssociated materials will automatically be imported as well.














43

The model should be set up such that each cranial component is a separate mesh object
within the
file, which represents the entire cranial model.

All materials and texturing should be done in the 3D
modeling software prior to importing into Unity.
For this example, we will use a grayscale duplicate of
the original python model.
The screenshot
below

demonstrates the how the pytho
n model was set up
i
n Cinema 4D:


Supported  3D  formats
 
Unity supports a number of standard 3D formats, including .obj and .fbx. It also supports proprietary
3D files from Autodesk Maya (.ma) and Maxon Cinema 4D (.c4d). The advantage of importing models
in those proprietary f
ormats is that you can continue to modify the model in the modeling software.
Unity will reimport the model every time the file is resaved in the external software, which is a more
efficient workflow than having to manually reimport the model each time cha
nges are made.


Note: When you import a .c4d model, Unity will open Cinema 4D in the background,
and convert the file from .c4d to
.fbx.
As of August 2013,
Unity
is not incompatible with
the newest version
of Cinema 4D (R14), and crashes if you attempt to
import a model
that is specified to be opened with R14.


To remedy this problem in Mac OSX, you may change the default program for opening
the 3D model as an older version of Cinema 4D (e.g. R13), given that you have an older
version installed on your comp
uter.

Right
-
click on the file in Finder, and choose Get
Info.

Under “Open With,” select other other version of CINEMA 4D.app.


Otherwise, you will have to export your model as an open file type (.obj or .fbx), before
importing it into Unity.




44

4.  Disable  
the  current  cranial  model  in  the  Hierarchy
 
Click on the
current cranial model (the
python model
)
, and uncheck the box next to its name

in the
Inspector

to disable it.

A disabled object will disappear from the Scene

and Game windows
, and its
name will appea
r grayed out in the
Hierarchy
.


You may also delete the original model from the Hierarchy, since we no longer need it
.

5.  Create  an  instance  of  the  new  cranial  model  in  the  Hierarchy
 

Drag the new model from the Project menu into the Hierarchy.
It should

be in the same place as the
python model in the hierarchy

(as a child of
camTargetMaster
). In the Inspector, make sure that its
Transform position is at (0, 0, 0). Adjust the scale as necessary so that the model is entirely in view
through the Main
Camera, as indicated in Game menu.




45

6.  Change  the  Skull  variable  for  the  Master  Script  to  the  new  cranial  model
 
Select
scriptMaster

in
the Hierarchy
, and drag the instance of
the new model into the
Skull

variable.















7
a
.  Add  a  Mesh  C
ollider  
component  
to  every  bone  object  of  the  cranial  model
 

Select

all the bone objects in the
Hierarchy

(select the first object, then hold Shift and click on the last
object)
.
Keep all bone object
s

selected for the all of Step 7
.
T
hen, go to:


Component < Phy
sics < Mesh Collider


Adding this component

enables the bone objects to respond to mouse clicks and hovers.


46

7b
.  Attach  the  following  three  scripts  to  every
 
b
one  object  of  the  cranial  model
 
Drag

the following three scripts
from the
Project < Scripts

into the
Inspector
:

Label

Script
,
Cam
Target Script
,
Explode

Script

7c.  Deactivate  the  Label  Script
 
We want labels to be turned off
by default when the application

starts; uncheck the box next to Label
Script.

7d
.  Apply  the  custom  GUI  skin  to  the  Label  Scr
ipt
 
Drag

labelsSkin01

(
Project < GUISkins
) into the
Custom Skin

variable of the
Label Script

8
.  
Input  the  correct  label  name  for  each  bone  object
 
Click on a

bone in the
Hierarchy
, and in the
Inspector
, open
the
Label Script

property. For the variable
Bone

Name
, type in
the name of the bone as you would like it to appear for the
bone’s label.

Repeat for each bone.














10
.  Modify  the  Components  Toggle  Script  to  
reflect  the  new  cranial  model
 
This is the most difficult part and potentially confusing p
art of the project.

Open the
Components
Toggle Script
, and

l
ook for the
/*EDIT

BEGIN
*/

and
/*EDIT

END
*/

comments to guide you as to which
code sections must be changed.


To begin, determine the number of bone objects that your cranial model consists of (i.
e., the number
of child objects it has).

Each bone will be identified by a numerical value in the code.

Using the python
model as an exa
mple, there are 18 bone objects, and the
“frontal_postfrontal_parietal”

bone will
subsequently be identified as
“bone01”
.


Note: Punctuations are very important when scripting; a missing or incorrect character can corrupt the
whole script. Take care to follow the format of code lines exactly as they are in the OsteoScope scripts.
Whenever possible, copy and paste existing l
ines of code and change only what you need

to
.




47

This code section identifies the visibility toggle
state for each bone; by default, all bones visibility
is true.
Modify the
bone#Visible

variables to
reflect the correc
t number of bones in your
model.


For

example, if your new model has 15 bone
objects, make sure you have 15 lines of this
code, with a unique bone# for each variable to
represent each unique bone object. In the
subsequent code sections, ensure that you also
have 15 lines/blocks of code with t
he same
bone#’s.



This code section assigns a label text for
each bone component. It should be the
same as the label you assigned to each
bone as the Bone Name variable of the
Label Script.

Modify the
bone#Label

variables to reflect the correct number o
f

bones and names of your model
.







This code section identifies the bone
GameObject associated with each bone
variable in the script. Modify the
bone#

variables to reflect the correct number of
bones and
exact file name

of your bone
objects
as they app
ear in the hierarchy.




48

This code section draws a GUI toggle for
each bone object.

Modify the
bone#Visible

variables to reflect the
correc
t number of bones in your model.


If you need to add additional
buttons, you
will need to adjust the vertical posit
ion of
the button by changing the second
number in
Rect()
.



You may additionally need to extend the height of the scroll view area to accommodate for more
buttons; if so, adjust the last number in the section
Rect()

in this line of code (currently 400).



Finally, this code section assigns the
visibility function for each bone. Each
bone should be represented by a block of
code like this, with
the correct
identification number associated with that
bone:


Ensure that every bone in the model is
accounted f
or.






11
.  Preview  the  application  in  Play  Mode,  and  ensure  that  there  are  no  functional  or  labeling  errors
 
Go through the following checklist to make sure that the application is correctly adjusted for the new
model:



Explode the model

o

All the bone
objects explode as expected



Labels

o

The bone are correctly labeled



Change Camera Orbit Target

o

The camera moves to and revolves around the each bone correctly when selected



Components menu

o

There is only one toggle button for each bone, and every bone is repr
esented by a
toggle button

o

The labels for each toggle button is correct

o

Each bone can be toggled on/off

o

Labels do not appear for bones that have been toggle off

12
.  Build  the  application
 
The next section will describe how to build a
version of OsteoScope

a
s a web application
.




49

Building  a  version  of  OsteoScope  as  a  web  application
 
When you are ready to export (or “build”) the project as a working application, go to:



File < Build Settings



In the pop
-
up menu, under
Scenes in Build
, add
the current scene
to the build (of course, make
sure the current scene is indeed the one you
would like to build). Under
Platform
, select Web
Player. Then, click on
Player Settings…


















You will notice that in the Inspector, a
PlayerSetting

menu will appear. The important settings to change are:



Product name


This will be the web page name
of your Unity web application, and cannot be modified
once it has been built



Resolution


OsteoScope was built for a player
resolution of 1024 width and
576 height


After changing these settings, hit
Build & Run

in the
Build Settings

menu. You will be prompted to specify a
file name and location for the build;
the file name will
be the .html and .
unity3d of your application, which
should not be modified
after they have been created
.




50

Hit
Save
, and your application will be built. The build web application will consist of two files with the
same name:


To run the application, open the .html file in a browser, either locally on your computer, or as a
remot
ely web page if you have placed the application on a server. The html page will load the Unity
Web Player, and run the application contained in the .unity3d file. In order for the Unity web
application to run,
the .html and .unity3d files must

always kept
be in the same location
.
Additionally, the computer from which you are running the Unity web application must have a working
Internet connection, even if you are opening the .html file from a local source.