Newsletter contents... UP

MAPSLICER: an interactive viewer for contoured map sections

Peter Briggs
CCP4 Daresbury Laboratory


MAPSLICER is a prototype interactive viewer for contoured sections through CCP4 maps, ``inspired'' by the existing CCP4 program NPO. Although it doesn't offer anything like the range of functionality of NPO, it does have some nice features, principally its ease of use for the novice.

Starting Up

The MAPSLICER interface is loosely based on the ccp4i loggraph program - on a UNIX/LINUX machine it is started from the command line simply by typing

> mapslicer map_file_name

which will automatically load in map_file_name. You can also use

> mapslicer

and then use the file browser options to open the desired map. An example of the program displaying a section from a Patterson map is shown below in figure 1.

Figure 1: Screen-shot of MAPSLICER in action.

Current Features

MAPSLICER reads in a CCP4-format map file which is sectioned in any order, and holds the whole map in memory. Once the map is inside the program it is possible to view any section along any of the principle axes x, y or z, regardless of the order of the sectioning. It is easy to change between axes and to go directly to any section within the map.

Sections can be specified in either fractional units or grid units, as can the extent viewed. The contour levels can be specified interactively, as can the on-screen scaling, and the program also offers a (limited) print facility, allowing the section to be dumped to a postscript file. All these features are easily accessible from the menu bar at the top of the window.

MAPSLICER was originally conceived to make it easier to look at Harker sections, so there is also the option to "short-cut" to Harker sections. The only drawback here is that the Harker sections are derived from the "true" spacegroup, while the map has the Patterson spacegroup - so the user must enter the true spacegroup manually first.

A bar at the bottom of the window gives basic information about the current section. Cursor feedback tells you the fractional coordinates of a particular position within the section, as well as the density at that position. More detailed information about the map or the current section can be obtained from the "Info" menu option.

Problems and missing features

MAPSLICER is still very much prototypical, so there are bound to be some problems of varying degrees both during installation and at run-time. Some major bugs have already been fixed in time for the patch release of CCP4 (4.1.1).

Other problems are less critical (for example, occassionally strange behaviour of axis labels, and limited print options) and there are some missing features - for example, you can't overlay multiple sections from the same map ("slab" option), and there is no way of colouring contours or of importing coordinates (e.g. heavy atom vectors, atom positions etc). Over time these should be fixed - meanwhile bug reports and suggestions are welcome.

How to get and install it

MAPSLICER is a TCL/Tk script, but it also needs a special version of the TCL/Tk interpreter wish, called ccp4mapwish (short and sweet!) in order to function. The source code for ccp4mapwish has been included as part of the latest CCP4 release (4.1 and 4.1.1), but it is not installed by default yet because the installation procedure has not been widely tested, and so cannot be automatically performed reliably.

You can find the code for ccp4mapwish in the $CPROG/ccp4mapwish_ directory, along with a configure script which will try and build the interpreter and then install in the $CBIN directory along with the other CCP4 programs. Instructions can be found via the documentation in $CHTML/ccp4mapwish.

IMPORTANT: there have been a number of changes to both the ccp4mapwish.c source code and to the configure script between 4.1 and 4.1.1. These changes are required to successfully compile with Tcl/Tk 8.3 (the most recent and stable version), and also to fix a bug with reading maps with non-zero starting section numbers. Please use the most recent version, or contact me if you are not sure.

ccp4mapwish has been successfully built on IRIX 6.5, Dec Alpha OSF1 V4.0, and RedHat Linux. If the build fails then please let me know and I will try to help you - all feedback is extremely useful at this early stage.

Once you have ccp4mapwish then all you need to start MAPSLICER is to invoke the mapslicer script (as described previously in ``Starting Up''). In the latest release this script is in the $CCP4I_TOP/bin directory - so it should be on your path already, provided that the CCP4I_TOP environment variable is set correctly in your ccp4.setup file. This in turn calls the Tcl code for the main MAPSLICER program, which is in the $CCP4I_TOP/mapslicer directory.

Technical Details

MAPSLICER is a TCL/Tk script which uses a set of new TCL commands implemented in the ccp4mapwish interpreter to read a CCP4 map into memory and then contour and display a specific section.

ccp4mapwish is written in a combination of C (which is required to use the TCL C library commands) and Fortran (which is required to access the CCP4 library, particularly the map reading routines). The new commands are described in the ccp4mapwish documentation, $CHTML/ccp4mapwish.html, along with a link to the document describing how to build the interpreter.

The build is complicated by the compilation requiring TCL, Tk, Fortran and X window libraries to be linked in - all of which may have different names and locations on different systems. Also, version 8.0 or better of the TCL and Tk libraries are required. However, a configure script is supplied which tries to take care of these issues for the user.

I would be happy to hear people's experiences of building and using the program, with the aim of improving future versions.

Future Developments

MAPSLICER is still in its infancy (practically embryonic in fact) and this is evidenced by the limited number of features. The most immediate aim is to fix up some of the existing features (for example printing, setting contour levels, improved drawing of axes) which are rather kronky.

Beyond that: the ability to view several sections overlayed ("slab" mode), colouring contours, read in coordinates to display atoms, peaks and vectors are all on the list. "Under the bonnet" I am also intending to rewrite the contouring routines in C, and generally to remove as much of the Fortran code as possible over time - the user probably won't see much difference, but it should hopefully make the core interpreter more portable and easier to build.


ccp4mapwish makes use of the Fortran 2-d contouring routine from NPO. Stylistically the appearance of the sections and some of the input features have also been inspired by NPO.

Liz Potterton's CCP4i libraries were used inside MAPSLICER.

Martyn Winn provided positive feedback and encouragement.

Peter Briggs, March 2001

Newsletter contents... UP