CellViewer
Throughout the MIEN documentation, the Cell Viewer will often be referred to as CV, and the syntax CV->Menu->Option will be used to mean "Select the choice named 'option' from the menu named 'Menu' in the menubar on the Cell Viewer window".
Starting CellViewer
Start the GUI using the command mien -a data. Optionally, you can append the name of one or more data files to open at the end of the command.
Loading data
If you didn't pass in the names of any data files, there are two other ways to load data into CV; Drag and Drop, and the File menu.
To load data by drag and drop, drag a local file from your Desktop or from a graphical file manager, and drop the file onto the black graphing area in the center of the Data Viewer. Dropping files here will cause CV to open them in append mode. This means that the data in each file will be concatenated with any data that is currently open in CV.
To load from the File menu, use File->Load, File->Append, and File-Append Subset. Each of these commands will open a file dialog where you can select a file to open, and will import data from that file. In the case of "Load", these new data will replace any existing data. In the case of "Append" they will be concatenated with the existing data. "Append Subset" allows you to choose parts of a complex document for import, rather than importing the entire contents. "Load" is exactly equivalent to "New Document" followed by "Append", so if you would like to "Load Subset", just call "New Document" before calling "Append Subset".
If you attempt to load data and nothing displays, check your terminal for error messages. If the file loaded correctly, but no elements display, you may have a file with no anatomical elements, or you may have your display filter set not to show the elements. Use CV->Display->Filter to change the filter. First, try selecting all element types in the filter.
Types of data to open
Cell anatomy data can be downloaded in Neurolucida or SWC format from several databases, including http://jazz.msu.montana.edu/publicrecon/cells and http://neuromorpho.org/neuroMorpho/index.jsp
Cell Viewer can read output written into "ascii" format by Neurolucida version 7.
Navigating in CV
The core of CV is a MIEN GL graph widget. This is the black area that takes up most of the CV window. Most of the viewpoint navigation used in CV is actually provided by the graph itself (and will therefor be the same for any MIEN extension GUI that uses a GL Graph). Some extensions also provide navigation functions.
The View Volume. Perspective, and Depth of Field
CV is designed primarily for viewing microscopy data, and as a result, it has some behaviors that are different than most other 3D graphics applications. The main difference is that CV does not simulate perspective in an image. This means that the displayed width of an object doesn't depend on the depth of that object in the image. As a result, a 2D projection through the image is an accurate 2D projection (unlike in a perspective image), but there are fewer visual depth cues.
Also, CV supports a "depth of field" setting, which determines how many different depths can be displayed at once. By default, this is set very large, so all objects can be seen. If you reduce it, you will see a horizontal slice through the image, which can be "focused" up and down, much as you would focus through the depth of an object under a microscope.
Any scene displayed by CV is contained in a rectangular-prismic "view volume" positioned somewhere in space. What you see in the scene is determined by the relationship of this volume to the spatial locations of the displayed elements. CV describes the view volume using the following parameters:
viewpoint: a 3-vector indicating the location of the camera
forward: a unit vector (in 3D) indicating the direction the camera is pointing
up: a unit vector indicating the roll orientation of the camera
extent: a scalar indicating the width, and height of the view volume
depth: a scalar indicating the depth of the view volume (the depth of field)
CV provides camera controls, but some of the most commonly used and intuitive controls (such as "orbit") are designed to be "model-centric" (meaning that they do something to the thing you are looking at, rather than the place you are looking from. Under the hood, though, all navigation is implemented by changing the parameters of the view volume, and most measurements are based on them as well, so to understand exactly how commands work (for example in order to figure out why a command didn't do exactly what you wanted), it can be helpful to think about how the view is represented.
Directions in the 3D scene will be referred to as horizontal (left/right), vertical (up/down), and depth (forward/back). In the first standard view, horizontal corresponds to the X axis, vertical Y, and depth Z. Axis coordinates are absolute, however, and "horizontal", etc, are relative to the camera. Horizontal always refers to your left and right on your screen, vertical to your up and down, and depth to into and out of the screen.
Graph navigation
Key Bindings
A major difference between CV and many other viewers is that navigation is keyboard-centric, rather than mouse-centric. Many typical navigation tasks are performed using keyboard shortcuts. As of the time of this writing, the graph key bindings are as follows:
f1 - open the graph configuration menu.
f2 - save a view preset
1, 2, 3 - set the z, x, and y axis standard views
4 - redraw the scene
5 - set the view to a user defined preset (if there is at least one)
"-" - zoom out (increase extent, displaying more objects)
= - zoom in (decrease extent, displaying less, and making displayed objects bigger)
_ - reduce depth of field
+ - increase depth of field
r - move the camera forward (towards the scene, or to lower depths - this is equivalent to "focusing down" in a microscope)
f - move the camera backward (to higher depths - equivalent to "focusing up")
q - roll the camera clockwise (this rotates the image counter-clockwise around the center of the image on screen)
. - roll the camera counter-clockwise
a, d, w, s - orbit the scene.
These functions simultaneously translate the camera, and rotate it so that it continues to "look at" the same point. The camera will make a circular orbit around the center of the view volume. The effect on the scene is that the image spins around, without translating. Note that the orbit is around the center of the view volume, which is determined not only by the 2D center of the screen, but also by the depth of field. Only the point at the center of the volume remains "fixed" at the center of an orbit. The standard views set the camera position and depth so that the center of the image is at the center of the set of displayed objects, so orbiting around a standard view tends to work very well. Orbiting around a custom view may cause objects of interest to swing out of view, event when they are centered on screen, because they are not centered in depth. To improve the behavior of orbit, adjust the depth of field (with _, +) or depth position (with r, f).
A, D, W, S - pan the camera left, right, up, and down. Panning is one maneuver that is more commonly done with the mouse, as described below, but it can be done, coarsely, with these keys also.
arrow keys - rotate the camera. Pressing an arrow key rotates the cameras line of view in the direction of the arrow. This will cause a displayed scene to move in the opposite direction, and will also change the project of the scene that you see. Many people find camera rotation confusing to navigate with and prefer to use orbit commands, but if you are used to navigating 3D scenes, you can "drive around" a scene using these rotations and forward/back (r/f).
The precision of navigation keypresses can be changed by changing the "resolution" parameter in the graph configuration menu.
Mouse behaviors
Right clicking on the graph re-centers the view so that the point you clicked on becomes the center of the view volume in the horizontal and vertical dimensions. This is the usual method used for precise panning in CV. Right-clicking has no effect on the depth of field or depth position.
Left-clicking measures the location of a point. The point is marked with a dot, and CV prints the location of the point as 3 vectors position, forward, and up. The position of a left-clicked point is placed on the front surface of the view volume. If you left click a second time, CV also prints the distance between this click and your last. If you did not issue any graph movement commands between the clicks, this distance will be measured in the current horizontal/vertical plane of the graph, so a pair of left-clicks can be used to measure 2D projection distances in any particular projection.
Shift-left click selects a point in a Cell object. See object selection.
Shift-right click selects a point in a Fiducial object (See object selection).
CV Menu Commands
If you are using Mac OS, read note about Mac menu behavior.
CV has 6 menus: File, Display, Selection, Extensions, Spatial, and Python. Each is described in its own section below.
File Menu
Many of the functions in the CV file menu are standard to MIEN GUIs, and are described here.
The Apply Filter to File function is CV specific. This function removes elements from the current document if they are not currently visible in CV. Elements that will be removed include any top-level element that can't be displayed by CV at all, elements that have been hidden, and elements that are not displayed under the current display filter (display filters are described in the next section).
Display Menu
Select Plots
Opens a menu where you can pick a set of individual elements to display. Only the elements you select will be visible.
Group Plots
Select plots to place in a display group. This function opens a dialog similar to Select Plots, where you can select elements to include in a group. You also need to enter a name for the group. Plot groups can be manipulated in some ways as though they are single plots. For example, you can change the color of every plot in a group with one command. By default, display groups are assigned when CV loads multiple spatial objects from a single file. Each object is assigned to a group named after the source file. This way, if you concatenate objects from several data files into one MIEN document, and each data file described many spatial objects, you can quickly do tasks such as "hide all the objects from file 2" or "show the objects from file 1 in red". If you want to change the membership of such a group, or make your own, use this function.
Hide/color Groups
Select a plot group, and set the display status for that group. You can change whether it is displayed at all, and in what color it is displayed.
Change Background Color
Open a dialog for setting the color of the graph background. Use the "browse" button in the dialog to pick a color using a GUI color browser. If you want to enter the color numerically, note that this dialog expects a 3 element list of numbers specifying RGB values. Unlike MIEN 2D graphs, these RGB values are on the range 0 to 1 (so [0,0,0] is black and [1,1,1] is white).
Replot
Redraw the elements in the document. Note that this is not the same as graph hotkey "4". Hitting "4" redraws the image, but it won't reflect changes to the document, such as addition of new elements that are not yet displayed. This function re-constructs the whole scene. Normally, this should be done automatically, but if an edit to the document is not reflected in the CV display, this function may fix things.
Filter
Set up a display filter. You may choose one or more element types to display. To remove a filter, re-select this function and select all element types. If there is an active filter, only elements of the indicated types will be visible.
Data Editor
Launch the MIEN XML editor for the current document.
Selection
This menu provides functions for selecting regions in an anatomical cell model. It will only be useful in documents that have Cell elements. Many of the functions depend on having one or more points in the cell model selected, as described in the object selection section. In principal, all of these functions should work in documents containing multiple cell models, but they are only tested in documents containing a single detailed cell model. Some errors may crop up in compound documents, particularly if you place selection points in two different cells, and try to use functions (such as "Select Path") that try to find a connected route between these points.
Clear Selection
Remove any selection. This includes selected sections, and selected points. Most selection commands are additive, so to move a selection from one region to another, you will need to clear the previous selection before making a new one.
Show Selection
Highlight selected sections, and display dots at selected points. Selections are automatically highlighted when you make them, but other display actions may remove the highlighting. This function restores it.
Export Point
This function requires that the current document contain some elements that require point references (these include recordings, and stimulus elements, such as iclamp). If there are several of these elements, you will be asked to pick one from a list. Also, you will need a selected point (if there are several, the most recently selected one is used). The selected element has its point reference set to the selected point. The main use of this function is to graphically place recording and stimulating "electrodes".
Import Point
This is the inverse of "export point". It gets a point from an element with a point reference, and sets it as the most recently selected point.
Select Section
Add the section containing the most recently selected point to the list of selected sections
Select Radius
Enter a number, and add all sections within that distance of the most recently selected point to the list of selected sections. Distance is calculated along neural processes, not through empty space. The function also allows you to select only in the proximal, or only in the distal, direction from the selected point.
Select Distal
Add the section containing the most recently selected point and all distal sections to the selected section list. Distal sections are those listed as "children" of the current section (those farther away from the cell root, which is usually the cell body). Select Distal is recursive and branch following, so all distal sections are selected, out to the tips of processes.
Select Proximal
Select sections proximal to the section containing the most recently selected point. These are the "parents" of the current section. Select proximal is recursive, but there are no branches. It will select a chain of sections, connecting the current section to the cell root (inclusive: both the section containing the current point and the root are selected).
Invert Selection
Select every section in the current cell that is not currently selected, and de-select every section that is.
Select Path
This requires two selected points. It selects every section that would be passed through by traveling from one point to the other, within the cell. The selection includes the sections containing both end points.
A Note about sections
Selection in CV depends on the structure of a Cell element through the arrangement of Sections and the choice of a cell root. MIEN represents cell morphology using the concept of a morphological "section" as different from an anatomical point, or an electrical compartment. This is similar to the representation used by the Neuron simulation environment, and different then the representation used by GENESIS and other tools. By default, a Section is an unbranched cell process. If you load morphology data into CV, Sections are assigned in this way. Consequently it is possible to have very large sections, if a cell has few branches. Many of MIENs built-in functions for editing cells operate on sections, including CV's selection tools. The result may be that you can't always select what you want. For example, if you have a long unbranched axon, you select a point in the middle, and you "Select Distal" the whole axon is selected, both distal and proximal to your selected point. This happens because the whole axon is a single section (since it is unbranched). Currently, the only solution to this issue is to edit your model to split the axon into two or more sections.
CV determines distal and proximal based on the cell root. This is the only section in a cell that has no parent section. Sections in a cell are arranged in a tree structure, with each section having zero, one, or more children, and a single parent, except for the root section, which has at least on child, and no parent. In most cases it is possible to express the same cell morphology using more than one tree, by choosing different roots. The anatomical concept of distal and proximal will only match the behavior of CV if the root section is also the cell body. What section is root depends on the method of digitizing, and, for many methods, the order of digitization. For example, a model imported from a Neurolucida file will have the root section assigned as the section containing the first point the Neurolucida user clicked on when digitizing. If this isn't the cell body, you may want to edit the model to change the root section to the cell body.
MIEN should provide functions for splitting sections and re-assigning the cell root quickly. Previous version offered these functions as built-in CV commands. Future versions will offer them as CV Extensions. As of the time of this writing, the functions are in the middle of being ported from built-in to extension, and the current release of MIEN doesn't offer them at all. This issue will be resolved as soon as possible.
Extensions
This menu provides access to several functions for managing extensions, and to functions that are provided by installed CV extensions.
HelpForSpatialFunctions
Prints the documentation strings of all installed Spatial extension functions that have documentation
Reload Extensions
Reloads the CV and SPATIAL extension blocks. This is only useful if the code defining one of these blocks is changed. This will not register new blocks that have been added (to do that, you need to restart CV), but it will cause existing extension functions to change behavior if the code defining them has been edited. This is mostly useful to developers who are debugging extensions, or to research programmers who like to do data analysis "by the seat of their pants".
For other functions in this menu, you will need to see the CV extension documentation
Spatial
This menu provides spatial data processing functions, including some defined by MIEN, and those defined by any loaded extensions. See the MIEN SPATIAL documentation, or the documentation for the relevant block for usage of each function.
The layout of the menu is analogous to the DV DSP menu
Python
The menu lets you launch Python interactive sessions that interact with the CV gui. See the general-purpose gui documentation.
Object Selection
CV supports two kinds of object selection, cell and fiducial selection, using different mouse clicks (shift-left for cell, and shift-right for fiducial). Other element types, such as spatial field and image objects can't be mouse-selected. The two types of selection are handled separately. If you shift-left-click on a fiducial line, the nearest point in a cell element will be selected, even if it is quite far away.
CV keeps a list of the most recently selected points, which is used with the functions in the Selection menu. These points are cell selections only. Currently the only uses of fiducial selections are for measurement, and for interactive identification of landmarks by the user.
Selection of either type of object works in the following way:
The point that is selected is the one with the shortest distance to a line drawn from the point of the mouse click, through the view volume, perpendicular to the front plane of the view volume (eg perpendicular to the screen). Consequently depth has no effect on selection, only distance from the click point as projected into the horizontal/vertical plane of the viewer.
Only visible objects inside the view volume can be selected. Hidden plots, or objects outside the depth of field will not be selected. Objects that are set as visible, and currently in the view volume may be selected, even if they are not actually drawn due to being occluded by another object.
Because of the first property, you might select a point that is behind the object you are looking at. If you have trouble with this in a dense scene you can zoom in to get better resolution. You can also use the first property. Hide plots you don't want to select, or reduce the depth of field. Orbiting the scene may also help you to find a viewpoint where the objects you want to separate are clearly separated in the plane of the image.
Fiducial selection
Fiducials are spatial annotations to an anatomical data set, which indicate the locations of anatomical landmarks. They are typically used to provide a comparable reference frame for data collected in different experiments. They can also be used to mark regions of interests, such as regions of a network that are hypothesized to have a particular function.
MIEN represents all fiducials as a elements of type Fiducial. These elements contains point data and optional labels. They also have an attribute called "Style" which determines how they are displayed. Fiducial styles include lines, spheres (points with an optional diameter), and labeled points (points with a textual label attached to them).
Fiducial selection treats all fiducial styles the same, and searches through all the visible fiducials in the document. Thus, if you click part way between a line fiducial and a labeled point, you could select either one - you will get whichever is closer.
When you select a fiducial, a single point within the fiducial gets selected. Note that line fiducials are drawn as lines, but are really composed of a list of points. If you click on the line between two points, the nearest of the points is selected. This could be some distance from the point you clicked on (also, if there is another fiducial nearer than either point, you will select that one - selection doesn't care that you clicked exactly on the line, it only knows about actual points in the data sets).
CV will mark the selected point with a (temporary) dot, and print information about the point. This information will look something like this:
The first three numbers are the X,Y,Z coordinates of the point. The fourth number (in brackets) is the diameter associated to the points (depending on how they were digitized, even some line and label fiducials will have diameter information, although it is not used for anything). The first word in parentheses is the name of the fiducial object containing the point. This name could be used to find the fiducial element in the XML editor, or using a script. The number in brackets after the name is the index of the selected point in the fiducial's spatial data array. In the above example, this is the 24th point (since Python counts from 0) in a line fiducial. If the fiducial is a member of a display group, the final set of parentheses displays this group name. This line is in display group 7.
If you have previously selected a fiducial point, CV will also print something like:
Distance from last point: 236.4858
This is the euclidean distance, though space, between the two selected points. Unlike the behavior of a CV measurement (left-click), this distance is in full 3D, since both selected points have absolute 3D locations. This distance won't depend on any rotation or control of the display.
Cell selection
Cell elements represent the morphology of cells (usually neurons). Cells tend to be more complex than fiducials, often containing a few thousand sections and many thousand points. For performance reasons, CV will only search for selections in one cell element at a time. Typically, users will build models of different cells in separate documents, and by the time these are combined into a single document, cell selection won't be needed anymore. If you do need to select a cell point in a document, you can, but CV will ask you to choose which cell to select in from a menu when you make a selection. If you click on a point in cell A, but say you want to select a point in cell B, you will get the closest point in B, even if it is far away.
When a point is selected, CV will push the selected point onto the list of selected points, where it can be used by the various functions in the Selection menu. CV will also mark the point with a temporary dot, and print information about the point. The point description looks like this:
The first four numbers are the same as for a fiducial selection, X, Y, Z, and D (cells always specify diameter). The string in parentheses is the name of the cell, followed (after the ".") by the name of the Section element containing the point, followed by the relative position of the point in the section. This last number is similar to the section-relative coordinates used by Neuron. It is a number between 0 and 1, indicating how far along the section the point occurs. The point above occurs about 55% of the way from the proximal end of section184 to the distal end. This measure is calculated along the inside of the section, not in a strait line through space.
View Presets
CV view presets are saved view volume descriptions that can be returned to using a single key-press. Whenever CV loads a document, it calculates and stores three presets known as the standard views in addition, users can add their own presets using the f2 menu of the 3D graph (or the "viewpoints" extension from the extension menu of CV).
Pressing f2 brings up a dialog showing the view volume parameters and a name for the new preset. You may edit the parameters if you like, but this usually isn't needed. The parameters are initialized to the current view, so you can navigate to a desired view using the GUI controls, press f2, enter a preset name, and select OK to save the current view as a preset.
Once you have presets saved, you can access them using the "5" key. If there is a single preset, pressing 5 immediately sets the view to that preset. If there are several, pressing 5 opens a dialog where you can select a preset view from a list.
You may set any number of preset views that you want. Normally, preset views are not persistent between CV sessions. To save your views, you can use the "Save Presets" option in the f1 menu. In a subsequent session, you can use "Load Presets" from the same menu to get your view presets back. (You can also use the viewpoints CV extension).
NOTE: a rather serious bug in view preset behavior was corrected in MIEN revision 654. If your presets are behaving incorrectly, try an update to the newest development revision.
Standard Views
The standard views act like view presets, but are automatically set for any document. There are three standard views, called Z, Y, and X. In a standard view, the camera is placed looking at the center of the visual scene. It is moved away along the indicated axis, far enough that all objects are visible. Depth of field and extent are set so that all objects are visible.
In the Z standard view, the camera is displaced along the Z axis, so the plane of the screen (the horizontal/vertical plane) is the X,Y plane. In the Y standard view, the screen is in the X,Z plane, etc. The Z standard view is (usually) the most similar to the view you would see in a microscope. It is sometimes referred to as plan view, and it is the default view that you will see first when opening a document in CV.
To access standard views, use the keys 1,2, and 3. "1" sets the Z view, 2 X, and 3 Y. Standard views are a good way to find the scene again, if you get "lost" while moving the camera.
Note that the center of a standard view is the center of the bounding prism containing all the displayed elements, not the origin. If you have two objects displayed at (100,0,500), and (700,10,200), the center of the plan view will be (400, 5, 350), not (0,0,0).
f1 Graph Menu
Pressing f1 in the 3D graph opens a configuration menu. This menu relates to the 3D graph itself, not to CV in particular. Features often used from this menu are being added to CV as extensions, but currently some operations you will want are only available from this menu.
Edit Global Options
Allows you to set the following properties. These can also be set (persistently) from the CV properties editor):
slices
This is an integer specifying how many facets to use in drawing curved objects (such as spheres and cylinders). Higher numbers reduce performance but make prettier pictures. Values should usually be between 6 and 24.
clearcolor
This is OpenGL's name for the color of the background. The value is a 3-list of RGB values, which are numbers between 0 and 1 (not integers between 0 and 255, as on the web). It is easier to use CV->Display->Change Background Color
resolution
This controls how much the camera moves when you press a movement key. It is a percentage, so smaller numbers cause finer movements, and larger numbers cause coarser, faster movements
Perspective
This controls whether OpenGL calculates perspective for the scene. If it is on, the viewing volume is a trapezoidal prism rather than a rectangular one. Turning perspective on in CV is almost always a bad idea, unless you are only interested in a visual effect, and not in data interpretation. Some MIEN extensions that build GUIs based on the 3D graph do use perspective, however.
Edit plot options
This allows you to change the display parameters of a plot at a very low level. The common uses, such as changing color or hiding, are much easier to access from the CV Display menu. You will need to understand the GraphGL API to set these options effectively.
Screen Shot
One of the most useful functions of this menu. It saves the current display image to a file.
Save Presets
If you have user defined view presets, this function lets you save them to a text file (The file save dialog is rather primitive, though, you will need to type a full path name unless you want to save the file in the current working directory of the Cell Viewer).
Load Presets
If you used "Save Presets" in an earlier session, reload your presets with this function.
Scale Bar
Temporarily display a line of a specified width.
Delete Plot
Remove a plot from the graph. It is probably better to do this using CV controls, such as hiding groups, setting a filter, or deleting an element from the document.
Preferences
CV->File->Preferences launches a dialog that lets you set some preferences that control how CV displays scenes.
Cell Plot Style
Determine how Cell elements are displayed. Choose one of these styles:
Frustum
Compartments of the cell are displayed as truncated cones (Frusta - similar to cylinders, except that the radius at the two ends may be different). This is the default, and usually generates the nicest images.
Line
Display a frame of lines, which ignores diameter information. This may result in faster displays, or a less visually crowded scene for very complex cells.
Mixed
Ideally this should display an optimized view of the cell using frusta, lines, and spheres. In the current release it is badly broken. Don't use it for now.
Non-Selected Plots
Determine what to do when the user selects some plots with CV->Display->Select Plots. The default value, "hide", makes all plots that were not selected invisible. The other option, "Fade", leaves all plots visible, but reduces the intensity of the non-selected ones. Fade is useful if you want to highlight some plots and see their anatomical relation to the rest of the elements.
Min Diameter
CV will assume all objects have a diameter at least this large. Usually, set this to 0 to see the actual data. If you have a number of tiny objects that you can't see in the context of a large view, you may want to set this to a larger value, resulting in a distorted view of the data, but one that makes small objects easier to see.
Line Width
CV will plot line style fiducials and cells displayed in line style using lines with this width in pixels.
graph -
The "graph -" options, perspective, slices, clearcolor, and resolution, set the same values as the global options function in the graph f1 menu. The difference is that setting these values as CV preferences is persistent. The values will remain after closing and restarting MIEN. In the case of setting them with the f1 menu, they will return to default values on a restart (or even on launching a new CV).