=== Using the database from Python (for programmers or advanced users) ===
The normal method for accessing image data on disk is using the read_image, read_images and write_image methods, for example:

{{{#!python
# e2.py
img=EMData()
img.read_image("test.hdf",5)  # reads the 6th image from test.hdf (first image is 0)
img.write_image("test2.hdf",-1)   # appends (-1) the image to the end of test2.hdf
img_list=EMData.read_images("test.hdf",range(50))   # reads the first 50 images from test.hdf into a list of EMData objects
n=EMUtil.get_image_count("test.hdf")   # counts the number of images in test.hdf
}}}
When writing to a (typically) 8 bit file format, like JPEG, PNG, PGM, the floating point values in the image need to be converted to an 8 bit scale. By default this is done with an algorithm that exludes outliers (ie - it doesn't span the full range of the image). To override this behavior, set the dictionary elements "render_min" and "render_max" on the image to be saved, and the specified range will be used instead. Here is a simple example:

{{{
a=test_image()
a["render_min"]=a["minimum"]
a["render_max"]=a["maximum"]
a.write_image("a.png")
}}}
File i/o can also be performed with databases, such as :

{{{#!python
img.read_image("bdb:test",5)
img.write_image("bdb:test2",-1)
}}}
However, this is not the preferred mechanism for using the database interface, since there are many more powerful operations which can be performed. Such as:

{{{#!python
e2.py    # This implicitly performs a 'from EMAN2db import *', which opens the local environment: DB=EMAN2DB.open_db()
testdb = db_open_dict("bdb:test")       # this opens a specific database in the local directory called "test"
testdb[0]=test_image()    # stores an EMData object in the 'test' database
img=testdb[0]             # This reads the EMData object back from the database
testdb.set_attr(0,"mykey",5.5)   # This sets an attribute "mykey" on EMData keyed 0 in database 'test'
                                  # This operation is MUCH faster than doing the same thing with any
                                  # flat file
testdb.get_attr(0,"mykey")       # This retrieves an attribute of image 0 from database test without
                                  # loading the image data
testdb["testimg"]=test_image()   # Keys in the database need not be integers, though the
                                  # read_image, etc. methods can only access integer keys
testdb["alist"]=[1,2,3,4,5]      # You can also use the 'test' database to store arbitrary other
                                  # metadata, not just images. This assigns a list to key 'alist'
db_close_dict("test")             # While database will be cleanly closed automatically, except for
                                  # cases where python is forcibly terminated (^c is ok), it isn't
                                  # a bad idea to close them if you know you won't use them again
}}}
Basically, each database object can be treated as a python dictionary. Any Python object that can be pickled (almost any python object) can be stored as a value in these dictionaries. It is even possible to mix images of different sizes within a single object.

The attribute mechanism (set_attr, get_attr) is tied into the EMData object attribute dictionary. That is, the following operations are functionally equivalent, but the second version is MUCH faster.

{{{#!python
img=testdb[0]
img.set_attr("mykey",5.5)
testdb[3]=img
# OR
DB.test.set_attr(0,"mykey",5.5)
}}}
Unlike python dictionaries, if a value in the database is an object, changing the object does not result in writing the change back to the database, unless you explicitly write it again. For example:

{{{#!python
# With a dictionary
test={1:["a","b","c"],2:3}
test[1][1]="c"
print test[1]
["a","c","c"]
# With a database
testdb = db_open_dict("bdb:test")
testdb[1]=["a","b","c"]
testdb[2]=3
testdb[1][1]="c"    # This effectively does nothing
print testdb[1]
["a","b","c"]
# To make the above actually work
d=testdb[1]
d[1]="c"
testdb[1]=d
}}}
You can write/read the full header for an EMData object inexpensively with:

{{{#!python
testdb[2]=test_image()
hdr=testdb.get_header(2)   # returns the equivalent of get_attr_dict on an EMData object
#If DB is associated with the disk database, get header requires an argument (image number).
hdr["apix_x"]=2.0
testdb.set_header(2, hdr)    # hdr can be either a dictionary or and EMData object
}}}
There is a small cost associated with opening each database, so it is generally a good idea for performance purposes to open the database and only close it if you aren't expecting to use it again for some time.

==== Clusters/MPI ====
Multiple processes/threads ''on a single machine'' can safely have the same database open at the same time (reading and writing). The databases (based on BerkeleyDB) support record-level locking. If one process is writing to a record and another process simultaneously tries to read the record, the read operation will block until the write completes. On a single machine the databases coordinate with each other using the database cache in /tmp which '''MUST''' be on a locally mounted filesystem (not NFS).

'''Multiple processes accessing (reading and writing) to a single file from multiple machines on a network-mounted filesystem IS NOT SAFE, and may result in unpredictable errors.'''

If you need to directly read a database on a node other than the node which is coordinating all write operations, you must open the database with caching disabled, or you may observe strange inconsistencies in the data where the local cache disagrees with the current database contents. To open the database with caching disabled:

{{{#!python
# YOU MUST DO THIS BEFORE OPENING ANY DATABASES ON NON-WRITE NODES
import EMAN2db
EMAN2db.BDB_CACHE_DISABLE=True
}}}
In addition, any database which is currently open on the writing node, and has recently been written to may not be properly readable on the other nodes. All write operations must be completed and the databases closed before opening them on other nodes.

The 'standard' parallelism mechanism in EMAN2 will be an encapsulation and distribution approach where reads/writes are synchronized through a single 'master' node. Finer grained MPI processing will also be supported, but less generally. SPARX is using a different approach.