This is a quick start up guide for AstroBlend - how to download and install things, and what sorts of data AstroBlend is expecting. For more tutorials please see the tutorials. Tutorials 1 & 2 are probably enough to get you up and blending.

Setup AstroBlend

First, fork AstroBlend on Bitbucket using Mercurial. Or download the repo following this link.

MAKE SURE YOU ARE USING THE stable2 BRANCH. If you are using mercurial, cd to your astroblend directory and do:

hg update stable2

You should see the following in your astroblend folder:

  README.md : the README file for bitbucket.org
  science/ : holds the main science library and its classes
  utils/ : contains changemtl.py which will change the headers of OBJ files if you move 
      them from one computer to the next so that they are still pointing to the correct 
      material files (MTL files), and Blender will thus still plot their colors correctly
  yt_files/ : contains several yt files used to generate typical OBJ files
  exampleScripts/ : some example scripts

Download and Modify Blender

Now you need to download Blender. The AstroBlend library is currently using version 2.72, which can be found here. An older version of AstroBlend used 2.69, which can also be forked if necessary, but no promises on how up to date it is! Versions up to 2.76b are being tested currently (see below for modifications in changing the OBJ exporter).

To use the full capabilities of the OBJ exporter from yt in AstroBlend, you'll want to modify a few lines in the Blender OBJ importer and exporter.

FOR VERSION 2.70-2.74: For the importer, on my Mac I modified the file "/Applications/Blender2.72/blender.app/Contents/Resources/2.72/scripts/addons/io_scene_obj/import_obj.py", in the function "create_materials" as follows:

# ...

                 elif line_lower.startswith(b'tr'):  # translucency
                     context_material.translucency = float_func(line_split[1])
                 elif line_lower.startswith(b'tf'):
                     # rgb, filter color, blender has no support for this.
                     pass
                 elif line_lower.startswith(b'em'): # MODIFY: ADD THIS LINE
                     context_material.emit = float_func(line_split[1]) # MODIFY: THIS LINE TOO
                 elif line_lower.startswith(b'illum'):
                     illum = int(line_split[1])

# ...

For the exporter, on my Mac I modified the file "/Applications/Blender2.72/blender.app/Contents/Resources/2.72/scripts/addons/io_scene_obj/export_obj.py", in the function "write_mtl" as follows:

# ...

            elif mat.specular_intensity == 0:
                fw('illum 1\n')  # no specular.
            else:
                fw('illum 2\n')  # light normal
            fw('em %.6f\n' % mat.emit) # MODIFY: ADD THIS

        else:

# ...

FOR VERSION 2.76: For the importer, on my Mac I modified the file "/Applications/Blender2.76/blender.app/Contents/Resources/2.76/scripts/addons/io_scene_obj/import_obj.py", in the function "create_materials" as follows:

# ...

                    elif line_id == b'tf':
                        # rgb, filter color, blender has no support for this.
                        pass
                    elif line_id == b'em': # MODIFY: ADD THIS LINE
                        context_material.emit = float_func(line_split[1]) # MODIFY: THIS LINE TOO
                    elif line_id == b'illum':
                        illum = int(line_split[1])

# ...

You will also need to comment out the following line:

# ...

                        emit_value = sum(emit_colors) / 3.0
                        if emit_value > 1e-6:
                            # We have to adapt it to diffuse color too...
                            emit_value /= sum(context_material.diffuse_color) / 3.0
                        ########### COMMENT ME ######## context_material.emit = emit_value

                        if not do_ambient:
                            context_material.ambient = 0.0

# ...

For the exporter, you can use the method described in the section about the exporter for versions 2.72-2.74.

Or, for version 2.76 of Blender, you can download the import_obj.py file here.

Create AstroBlend Data Files

First, you probably want to have some data to manipulate. The tutorials will discuss how to access different data sets, but in general there are two ways to get data into AstroBlend.

(1) Read in data via a text file. This is currently what is done with SPH simulations. However, this can be memory intensive for very large data sets. Furthermore, for AMR codes, you would need some pre-formatting to have such data be useful visually.

(2) Use pre-fab isosurface files which for our purposes are stored as OBJ or Wavefront files. A few examples can be found in the Data Section. An easy example to use to start with might be the yt Galaxy Isodensity Contours.

(3) Use yt to create OBJ files from AMR data which can then be imported into Blender. A blog post on how to use yt to do just this can be found here.

(4) Call yt directly from Blender with AstroBlend to create surfaces or 3D scatter plots for SPH simulations. More on that in this tutorial on surfaces and this tutorial on SPH data.

AstroBlend support for codes is an ongoing process, please find your code below to see if its supported.

Code/Formatyt Surface SupportAstroBlend Surface SupportSPH Support
FLASHYYNA
EnzoYYNA
AthenaYYNA
ArtioNNA - just loadsNA
FitsNNA - just loadsNA
GDFNNA - just loadsNA
MOABNNA - partial loadingNA
SPH Text FilesNNYes (see here)
TipsyNNY

Final Steps

Almost there! Just two more things you should do:

(1) Start by looking at the first tutorial - Getting to Know Blender which will show you the basics of navigation.

(2) Then follow up this with checking out the second tutorial - Simple Rendering which will show you how to render an image and will talk a bit about camera positioning and moving objects around.

(3) If you want to use yt directly in Blender with AstroBlend check out the third tutorial - Calling yt Directly.

Now you are ready to check out the Tutorials to see how to get this library working for you, or find some inspiration over at the Gallery of images and movies!

Also check out the example scripts and example blend files to get some other ideas of how to use AstroBlend.