{
 "metadata": {
  "signature": "sha256:56ed6dc37d0e2622868db8e07ae2934ead3b433509b39f10c9b82d60518a0b76"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Mayavi tips\n",
      "===========\n",
      "\n",
      "Introduction\n",
      "------------\n",
      "\n",
      "Here are general tips on how best to use !MayaVi2.\n",
      "\n",
      "Scripting MayaVi2 effectively\n",
      "-----------------------------\n",
      "\n",
      "Here are a few tips showing how to script mayavi2 interactively and\n",
      "effectively.\n",
      "\n",
      "### Drag and drop object\n",
      "\n",
      "Running the contour.py python script example, you should get:\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps1.png)\n",
      "\n",
      "First, enable python shell clicking on Python in the \"View\" menu. A\n",
      "python shell should appear at the bottom of the !MayaVi2 window:\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps2.png)\n",
      "\n",
      "Then drag any object from the tree view on the left and drop it on the\n",
      "python shell and you'll get the object. Say you want to get the Outline\n",
      "module:\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps3.png)\n",
      "\n",
      "Now, you can use your object following two ways: typing directly in the\n",
      "python shell or using the explore() method.\n",
      "\n",
      "### Typing in the python shell\n",
      "\n",
      "You can create an instance of your object in the python shell window.\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps4.png)\n",
      "\n",
      "Note that you benefit of \"word completion\" in this python shell, ie a\n",
      "little window popups letting you choose the name of the expected object\n",
      "or method.\n",
      "\n",
      "Thus, you can display the RGB values of the outline color for instance:\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps5.png)\n",
      "\n",
      "However, find out objects or methods can be not so easy: you may not\n",
      "know how they depends from each other. An easier way is using the\n",
      "explore() method.\n",
      "\n",
      "### Using the explore() method\n",
      "\n",
      "Simply type"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "explore(_)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "or"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "explore(foobar)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "if you have previously defined it:\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps6.png)\n",
      "\n",
      "Then, you get the following window:\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps7.png)\n",
      "\n",
      "Considering the last example, about the color of the outline module, you\n",
      "can unfold the \"tree\" and thus, get the info you need:\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/ps8.png)\n",
      "\n",
      "Very powerful, isn't it ! :-)\n",
      "\n",
      "You can also work in the pyhon shell, create your objects and so on...\n",
      "\n",
      "### Working in the python shell\n",
      "\n",
      "On the embedded Python shell in the !MayaVi2 application, the name\n",
      "'mayavi' is bound to the !MayaVi scripting interface which can be used\n",
      "to script mayavi easily as shown here:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "e = mayavi.engine # Get the MayaVi engine.\n",
      "mayavi.new_scene() # Create a new scene\n",
      "# [...]\n",
      "mayavi.save_visualization('foo.mv2')\n",
      "mayavi.load_visualization('foo.mv2')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Note that the Mayavi engine lets you script mayavi in powerful ways. For\n",
      "example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "e = mayavi.engine"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Here 'e' is the running Engine instance (mayavi/engine.py) and has the\n",
      "same hierarchy that you see on the mayavi tree view. For example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "e.scenes[0]             # --> first scene in mayavi.\n",
      "e.scenes[0].children[0] # --> first scene's first source (vtkfile)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Another example, just run examples/contour.py and type/cut/paste the\n",
      "following to get the scalar cut plane module:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "e = mayavi.engine\n",
      "s = e.scenes[0].children[0].children[0].children[-1]\n",
      "# Think scene.datafile.module_manager.last_module"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It is possible to use Mayavi2 from within\n",
      "[IPython](http://ipython.scipy.org) and script it. You must first start\n",
      "IPython with the '-wthread' command line option. Here is an example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.app import Mayavi\n",
      "m = Mayavi()\n",
      "m.main()\n",
      "m.script.new_scene() # m.script is the mayavi.script.Script instance\n",
      "engine = m.script.engine"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In the above, 'm.script' is the same as the 'mayavi' instance on the\n",
      "embedded shell.\n",
      "\n",
      "If you are writing a stand-alone script to visualize something like the\n",
      "scripts in the examples/ directory, please use any of the examples as a\n",
      "template.\n",
      "\n",
      "Save snapshots\n",
      "--------------\n",
      "\n",
      "Saving snapshots within a python script is very easy:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "s = script.engine.current_scene\n",
      "s.scene.save('test.jpg', size=(width,height))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You can also save images in a lot of others format: !PostScript (ps),\n",
      "Encapsuled !PostScript (eps), PDF (pdf), Bitmap (bmp), TIFF (tiff), PNG\n",
      "(png), !OpenInventor (iv), Virtual Reality Markup Language (wrl, vrml),\n",
      "Geomview (oogl), !RenderMan RIB (rib), Wavefront (obj).\n",
      "\n",
      "The obvious corollary of saving snapshots is saving a lot of snapshots\n",
      "in order to make a movie for example, without !MayaVi2 window popup for\n",
      "each snapshot recorded.\n",
      "\n",
      "The answer is straightforward (only under UN\\*X boxes): use the 'X\n",
      "virtual framebuffer'.\n",
      "\n",
      "The following lines give you the trick. You can improve it, of course,\n",
      "scripting it in shell, python, and so on.\n",
      "\n",
      "`*\u00a0create\u00a0your\u00a0X\u00a0virtual\u00a0framebuffer\u00a0with\u00a0the\u00a0following\u00a0command:\u00a0'xvfb\u00a0:1\u00a0-screen\u00a00\u00a01280x1024x24'.\u00a0It\u00a0will\u00a0use\u00a0the\u00a0display\u00a0#1,\u00a0with\u00a0a\u00a0size\u00a0of\u00a01280x1024\u00a0and\u00a024\u00a0bit\u00a0depth\u00a0color;`\n",
      "\n",
      "`*\u00a0export\u00a0your\u00a0display:\u00a0'export\u00a0DISPLAY=:1'\u00a0(sh/bash\u00a0syntax)\u00a0or\u00a0'setenv\u00a0DISPLAY\u00a0:1'\u00a0(csh/tcsh\u00a0syntax)`\n",
      "\n",
      "`*\u00a0run\u00a0your\u00a0!MayaVi2\u00a0script\u00a0as\u00a0usual;`\n",
      "\n",
      "`*\u00a0once\u00a0finished,\u00a0and\u00a0all\u00a0your\u00a0snapshots\u00a0have\u00a0been\u00a0created,\u00a0don't\u00a0forget\u00a0to\u00a0kill\u00a0the\u00a0X\u00a0virtual\u00a0framebuffer\u00a0and\u00a0reset\u00a0your\u00a0display\u00a0to\u00a0its\u00a0previous\u00a0value.\u00a0If\u00a0not,\u00a0you\u00a0won't\u00a0be\u00a0able\u00a0to\u00a0see\u00a0your\u00a0movie\u00a0;-)`\n",
      "\n",
      "Enabling alpha transparency in the colormap\n",
      "-------------------------------------------\n",
      "\n",
      "Drag the module manager to the python shell and you will be able to\n",
      "enable alpha transparency in the colormap via:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "dragged.scalar_lut_manager.lut.alpha_range=(0,1)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Set MayaVi2 session colors\n",
      "\n",
      "Run !MayaVi2, go to \"Tools\" menu then \"Preferences\" then \"TVTK Scene\".\n",
      "\n",
      "Suppose that you want to change background color: click on \"Background color\" tag.\n",
      "\n",
      "Here, you can choose a predefined color, or click in the square to set your RGB value, for instance.\n",
      "\n",
      "![](files/attachments/MayaVi_Tips/setcolors.png)\n",
      "\n",
      "Also, if you want to set foreground color, it will be applied for all modules and filters, i.e. outline color, text color, labels axes, and so on.\n",
      "\n",
      "Your preferences will be saved in a !MayaVi2 configuration file, so you'll get these colors each time you run a !MayaVi2 session.\n",
      "\n",
      "= Writing VTK data files using TVTK =\n",
      "\n",
      "Coming soon...\n",
      "\n"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}