diff --git a/examples/demos/bbox.py b/examples/demos/bbox.py
index 1e4215f456887ce75341d2a2ac6ff8074dc6a054..fa85b9a26676e876beb53f44494b44db108ff19a 100644
--- a/examples/demos/bbox.py
+++ b/examples/demos/bbox.py
@@ -1,17 +1,26 @@
-sdh=io.LoadPDB('sdh.pdb')
+# This code example shows how to calculate and display an oriented bounding box 
+# that contains all the atoms of an entity.
+
+# remove all objects from scene, just in case
+scene.RemoveAll()
+
+# Load sdh molecule
+sdh=io.LoadPDB('data/sdh.pdb')
+# Select backbone atoms of residues 99-128, which form a helix.
 helix=sdh.Select('rnum=99:128 and cname=A and aname=CA,C,N,O')
+# create a graphical representation of the helix and render it with simple 
+# lines.
 go=gfx.Entity('helix', gfx.SIMPLE, helix)
+# add it to the scene
 scene.Add(go)
 
+# calculate the bounding box for the helix
 bbox=mol.BoundingBoxFromEntity(helix)
 
-def RenderBBox(bbox):
-  bb=gfx.Cuboid('xxx', bbox)
-  bb.SetFillColor(gfx.Color(0.5, 0.8, 0.5, 0.2))
-  scene.Add(bb)
+# create a graphical representation of the bounding box and add it to the scene
+bb=gfx.Cuboid('xxx', bbox)
+bb.SetFillColor(gfx.Color(0.5, 0.8, 0.5, 0.2))
+scene.Add(bb)
 
-print 'Center:',(helix.GetGeometricStart()+helix.GetGeometricEnd())*.5
-  
-RenderBBox(bbox)
+# center the camera on the graphical object
 scene.center=go.center
-print 'Demo2: Translucent bounding box around an OpenStructure entity'
diff --git a/examples/demos/charmm_trj_blur.py b/examples/demos/charmm_trj_blur.py
index eedba6bb32e05392775aca4ada5a6459316ba500..8edfdc0c2768007b83698acf22cd8f2caa012da7 100644
--- a/examples/demos/charmm_trj_blur.py
+++ b/examples/demos/charmm_trj_blur.py
@@ -1,33 +1,45 @@
 # trajectory generated by Raimund Dutzler
 from PyQt4 import QtCore
+scene.RemoveAll()
+
 
 class Anim(QtCore.QTimer):
-    def __init__(self,cg,go):
-        QtCore.QTimer.__init__(self)
-        self.cg_=cg
-        self.go_=go
-        self.frame_=0
-        QtCore.QObject.connect(self, QtCore.SIGNAL("timeout()"), self.OnTimer)
-        
-    def OnTimer(self):
-        self.step()
+  """
+  Timer used to animate the trajectory on screen. Each time the OnTimer
+  method gets called we advance the trajectory by one step and render
+  the scene on the screen.
+  """
+  def __init__(self,cg,go):
+      QtCore.QTimer.__init__(self)
+      self.cg_=cg
+      self.go_=go
+      self.frame_=0
+      QtCore.QObject.connect(self, QtCore.SIGNAL("timeout()"), self.OnTimer)
+      
+  def OnTimer(self):
+    self.frame_=(self.frame_+1)%self.cg_.GetFrameCount()
+    self.go_.BlurSnapshot()
+    self.cg_.CopyFrame(self.frame_)
+    self.go_.UpdatePositions()
         
-    def step(self):
-        self.frame_=(self.frame_+1)%self.cg_.GetFrameCount()
-        go.BlurSnapshot()
-        self.cg_.CopyFrame(self.frame_)
-        go.UpdatePositions()
 
-cg = io.LoadCHARMMTraj("sample.pdb","sample.dcd")
+# load CHARMM trajectory from sample.pdb and sample.dcd
+cg = io.LoadCHARMMTraj("data/sample.pdb","data/sample.dcd")
+# create graphical representation of the entity
 eh=cg.GetEntity()
+# we don't want to display the hydrogen atoms, so select everything that is 
+# not a hydrogen and pass that view to the gfx.Entity() constructor.
 ev=eh.Select("not ele=H")
 go=gfx.Entity("mol",gfx.SIMPLE, ev)
+# enable the blur effect
 go.SetBlur(True)
 
+# add it to the scene for rendering
 scene.Add(go)
 scene.SetCenter(go.GetCenter())
 scene.AutoAutoslab(True)
 
+# create an animation timer and start it
 anim=Anim(cg,go)
 print 'Demo 6: Import of a CHARMM trajectory. Type anim.stop() to halt animation, anim.start(100) to start it again with stepsize 100!Starting animation now....'
 anim.start(50)
diff --git a/examples/demos/conservation.py b/examples/demos/conservation.py
index 8399ef05bf7560dd9a0b6e079fb7712008a15ad9..8ecce056648e082f70cd4f16f6ea5b7cd0ab3077 100644
--- a/examples/demos/conservation.py
+++ b/examples/demos/conservation.py
@@ -1,22 +1,27 @@
 from ost.seq import alg
+scene.RemoveAll()
 #-------------------------------------------------------------------------------
 # Loading structure and alignment
 #-------------------------------------------------------------------------------
-m=io.LoadPDB('sh2.pdb')
+m=io.LoadPDB('data/sh2.pdb')
 mp=m.Select('ishetatm=false')
-aln=io.LoadAlignment('sh2.aln')
+aln=io.LoadAlignment('data/sh2.aln')
 aln.AttachView(0, mp)
+
 #-------------------------------------------------------------------------------
 # Calculate conservation of alignment
+# First we set all properties to zero, then let alg.Conservation assign the
+# conservation scores to the residues
 #-------------------------------------------------------------------------------
 for r in m.residues:
   r.SetFloatProp('cons', 0)
 alg.Conservation(aln)
+
 #-------------------------------------------------------------------------------
 # Setup Graphical Objects for Rendering
 #-------------------------------------------------------------------------------
 g=gfx.Entity('SH2', m)
-s=io.LoadSurface('sh2.vert')
+s=io.LoadSurface('data/sh2.vert')
 gs=gfx.Surface('SH2-surf', s)
 scene.Add(gs)
 scene.Add(g)
@@ -36,9 +41,11 @@ g.SetRenderMode(gfx.CUSTOM,
                 m.Select('ishetatm=true'))
 g.SetColor(gfx.YELLOW, 'ishetatm=true')
 
-
+#-------------------------------------------------------------------------------
+# Create alignment viewer and show it on the screen
+#-------------------------------------------------------------------------------
 seq_viewer=gui.SequenceViewer()
 seq_viewer.AddAlignment(aln)
 seq_viewer.Show()
 
-print 'Colouring the active site according to the level of conservation found inthe sequences shown in the sequence viewer. Highly conserved regions are shown in blue, variable regions in red.'
+
diff --git a/examples/demos/gfx_mapslab.py b/examples/demos/gfx_mapslab.py
index 3174677a8d0c3d55b7bdb003ec774c3f91cad170..de59b2e5d1df8ee8386ae75921543139bddefde6 100644
--- a/examples/demos/gfx_mapslab.py
+++ b/examples/demos/gfx_mapslab.py
@@ -1,5 +1,9 @@
 import math,random
 from ost import img
+
+# remove all objects from scene, just in case
+scene.RemoveAll()
+
 vmax=-10000.0
 vmin=+10000.0
 mh=img.CreateMap(img.Size(32,32,32))
@@ -45,6 +49,7 @@ go1.SetLineWidth(1.5)
 scene.Add(go1)
 scene.SetCenter(go1.GetCenter())
 
+
 go2 = gfx.MapSlab("slab",mh,geom.Plane(go1.GetCenter(),geom.Vec3(0.0,0.0,1.0)))
 scene.Add(go2)
 go2.ColorBy(gfx.YELLOW,gfx.GREEN,0.2,0.8)
diff --git a/examples/demos/load_and_display.py b/examples/demos/load_and_display.py
index 382197ea7822ee2506125236722f7a0569bbb423..be2783a00f0a7c6c048580ccd0200f95d4c0d919 100644
--- a/examples/demos/load_and_display.py
+++ b/examples/demos/load_and_display.py
@@ -1,5 +1,7 @@
+# remove all objects from scene, just in case
+scene.RemoveAll()
 # Load chain A of SDH
-ent=io.LoadPDB('sdh.pdb', restrict_chains='A')
+ent=io.LoadPDB('data/sdh.pdb', restrict_chains='A')
 
 # create graphics object
 go=gfx.Entity('SDH', ent)
diff --git a/examples/demos/rendermodes.py b/examples/demos/rendermodes.py
index b45cd500cfde0531f35754b90486ba413fb3c233..a7d08937dbf14f950349f6f68b50222a51c5649e 100644
--- a/examples/demos/rendermodes.py
+++ b/examples/demos/rendermodes.py
@@ -1,5 +1,12 @@
-# load pdb file
-eh=io.LoadEntity("sdh.pdb")
+# This script shows how to switch between different render modes 
+# programmatically and change render options.
+
+
+# remove all objects from scene, just in case
+scene.RemoveAll()
+
+# load pdb structure
+eh=io.LoadPDB("data/sdh.pdb")
 
 
 sdh_go=gfx.Entity("SDH2", eh.Select("cname=A"))
@@ -9,7 +16,7 @@ scene.CenterOn(sdh_go)
 
 def Tube():
   sdh_go.SetRenderMode(gfx.TUBE)
-  sdh_go.GetOptions(gfx.TUBE).SetTubeRadius(0.8)
+  sdh_go.tube_options.SetTubeRadius(0.8)
   # apply color gradient for the atomic bfactors
   sdh_go.ColorBy("abfac",gfx.BLUE,gfx.RED)
   # and apply radius gradient as well 
@@ -32,15 +39,15 @@ def Cartoon():
   sdh_go.SetColor(gfx.Color(1,0,0),"rtype=E")
   sdh_go.SetDetailColor(gfx.Color(1.0,0.8,0.2),"rtype=E")
   # these are the default params for the rendering
-  #sdh_go.GetOptions(gfx.HSC).SetArcDetail(4)    # circular profile detail
-  #sdh_go.GetOptions(gfx.HSC).SetSphereDetail(4) # sphere detail
-  #sdh_go.GetOptions(gfx.HSC).SetSplineDetail(8) # segments between backbone atoms
-  #sdh_go.GetOptions(gfx.HSC).SetTubeRadius(0.4) # coil radius 
-  #sdh_go.GetOptions(gfx.HSC).SetTubeRatio(1.0)  # coil axial ratio
-  #sdh_go.GetOptions(gfx.HSC).SetHelixWidth(1.1)   # helical width
-  #sdh_go.GetOptions(gfx.HSC).SetHelixThickness(0.2)   # helical thickness
-  #sdh_go.GetOptions(gfx.HSC).SetStrandWidth(1.2)  # strand width
-  #sdh_go.GetOptions(gfx.HSC).SetStrandThickness(0.2)  # strand thickness
+  #sdh_go.cartoon_options.SetArcDetail(4)    # circular profile detail
+  #sdh_go.cartoon_options.SetSphereDetail(4) # sphere detail
+  #sdh_go.cartoon_options.SetSplineDetail(8) # segments between backbone atoms
+  #sdh_go.cartoon_options.SetTubeRadius(0.4) # coil radius 
+  #sdh_go.cartoon_options.SetTubeRatio(1.0)  # coil axial ratio
+  #sdh_go.cartoon_options.SetHelixWidth(1.1)   # helical width
+  #sdh_go.cartoon_options.SetHelixThickness(0.2)   # helical thickness
+  #sdh_go.cartoon_options.SetStrandWidth(1.2)  # strand width
+  #sdh_go.cartoon_options.SetStrandThickness(0.2)  # strand thickness
 
 Cartoon()
-print 'Demo 5: Type Spheres(), Tube(), Trace(), or Cartoon()\n to switch render modes'
+
diff --git a/examples/demos/the_hammer.py b/examples/demos/the_hammer.py
index 7db8abab34478c27382e5c6c96fc7dc780ad5d9b..f6c77ebca38b663fd03b5e922604ccb3a3ef73e8 100644
--- a/examples/demos/the_hammer.py
+++ b/examples/demos/the_hammer.py
@@ -1,6 +1,10 @@
 from PyQt4 import QtCore
 import math
 from ost import qa
+
+# remove all objects from scene, just in case
+scene.RemoveAll()
+
 class Anim(QtCore.QTimer):
     def __init__(self, a, b):
         QtCore.QTimer.__init__(self)