Introduction

It's silly to store gigabytes of pixel data in a relational database. Instead, OME stores this pixel data in something called a "repository." In the original builds of OME version 2.0, this repository was just a folder in the server's local filesystem, which the OME server code assumed it had complete control over. However, it quickly became apparent that this solution wasn't optimal, especially once work progressed on the client-side user interfaces, which didn't necessarily have convenient access to the server-side filesystem.

Therefore, OME version 2.2 contains a new component called the image server. The image server is a separate, standalone C program (omeis) which is designed to do one thing and do it well: stream pixel data off of a hard disk onto a network connection as fast as possible.

Currently, this means we're in a period of transition, where the server's repository can either be a local folder or a reference to an image server. Most of the underlying server code supports both (via the OME::File and OME::Image::Pixels interfaces and the OME::Tasks::PixelsManager class). However, there are three notable exceptions, which are in various stages of being fixed:

1. The Web UI can only import images into a local repository, and not into an image server. (Remedying this is a high priority and is happening presently.)
2. The Java API code can only retrieve image pixels from an image server, and not from a local repository. (This will never be changed.)
3. The CLIHandler in the analysis engine only works with local repositories. Eventually it will make temporary local copies from the image server for legacy command-line routines, but this has not been implemented yet. It will probably not be implemented until after the April release.

Whether you're using a local folder or image server for your repository is entirely defined by the single Repository attribute in the database. (Technically, it's possible to have more than one Repository defined, but right now, it's really only useful to have one.) The Repository semantic type defines three elements which are important to us: IsLocal, Path, and ImageServerURL.

If the IsLocal element is true, then the installation uses a local folder for its repository. In this case, the Path element contains the local filesystem path to the repository folder. If, in Java, you try to grab some pixels for a Pixels attribute which lives in this repository, then the ImageServer class should throw an ImageServerException.

If the IsLocal element is false, then the installation uses an image server for its repository, and the ImageServerURL element contains the HTTP URL which can be used to access this image server. In this case, the Web import interface will fail, in a possibly dramatic fashion.

Switching to OMEIS

Based on everything described above, it is not possible for Java code to view images from a fresh OME installation, without a slight tweak to the database. Namely, you must edit the Repository entry to point to a valid image server.

I'm not going to describe how to install the image server. That's out of the scope of this document. If executives often ask for a 10,000-foot view, here is the view from lunar orbit:

cd src/C/omeis & make & cp omeis /usr/local/apache/cgi-bin

Pray that nothing goes wrong.

Once you've got the URL to an image server, you need to go in and edit the Repository attribute using your best friend, psql. The attribute will live in the REPOSITORIES table, and there should be only one, so the following should work perfectly:

update repositories
set is_local = false,
    image_server_url = 'http://wherever/your/image/server/is';

I'll point this out one more time, because I like to hear myself talk: Once you execute this statement, the Web import UI will no longer work. Isn't it great to have this much power at your fingertips?

Once you've got yourself set up with an image server repository, you can import images using the ImportEngine.pl command-line tool. (It can be found in the src/perl2/OME/Tests directory.) This tool accepts a -h option to print out a help message, but usually you'll just need to execute something similar to the following:

perl src/perl2/OME/Tests/ImportEngine.pl /tests/image1.r3d /tests/image84.stk

If you executed your UPDATE statement correctly, and your permissions are set up properly for your image server installation, then the images will be imported into the image server, and the statistics chain will be executed on those images. Your Java code should then be able to access the pixels for that image. And, the Web UI for displaying (not importing) images should also still work.