Skip to main content
Sign In

imstack

top | Installing | Launching | Using | Menus | Advanced

Written by:

Ernesto Salcedo, PhD

Senior Instructor, University of Colorado Anschutz Medical Campus

Supported in Part by the Rocky Mountain Taste and Smell Center

latest version: 02–20–2016

imstack Overview

imstack is a light-weight image stack viewer for MATLAB that supports:

  • slice scrubbing by scrolling or arrow key press

  • color stack viewing

  • mask overlay (by channel)

  • biological image formats (such as confocal stacks) using Bio-Formats (requires the MATLAB bioformats toolbox to be installed)

  • loading image stacks from the command window

  • basic image processing including thresholding and simple morphological operations (requires Image Processing Toolbox)

  • script interface

  • dataset building for data analysis

MATLAB toolbox requirements

  • Image Processing Toolbox

Incorporated Mathworks File Exchange Toolboxes

Tested On

MATLAB 2015b

Installing imstack

top | Installing | Launching | Using | Menus | Advanced

To install:

  1. Navigate to the MATLAB folder in the MATLAB Current Folder Window

  2. Run these three MATLAB commands in the command window:

unzip('https://dl.dropboxusercontent.com/u/10600990/site/MATLAB%20functions/imstack.zip')
addpath(fullfile(pwd,'imstack'))
savepath

Installing the Bioformats Toolbox

Bio-Formats is a Java library for reading and writing biological image files developed by Open Microscopy Environment (OME). It is especially useful for opening image stacks created in proprietary image formats (e.g. *.lif or *.oib) created by the various microscope manufacturers.

The bioformats toolbox is a MATLAB toolbox that can interface with the Bio-formats Java library.

To install, you can either:

  1. Follow the instructions on OME MATLAB bioformats toolbox page

  2. OR, try this set of MATLAB commands

unzip('http://downloads.openmicroscopy.org/bio-formats/5.1.7/artifacts/bfmatlab.zip')
addpath(fullfile(pwd,'bfmatlab'))

Note, option 2 might not get you the latest version of the bioformats tool.

Launching imstack

top | Installing | Launching | Using | Menus | Advanced

Loading Stack From File

  1. In the MATLAB command window, type:

    imstack
    
  2. A Listbox will pop-up. Select the type of image stack you want to load dataset loaded should read in the command window.

2a - Note, if you select “bioformats,” a new figure window will pop up that will allow you to select the specific image stack you want to load (many confocal file formats contain multiple image stacks within one file). In this “Bioformats” Window, simply click on the image projection of the stack that you want to load. Clicking on another projection will load that dataset in the connected imstack window.

Loading a Stack From the Workspace

You can also pass an image stack from the workspace to launch imstack as follows:

imstack(img_stack)

imstack will then launch and display the passed-in image stack.

NOTE: Color image stacks must have the following 4D formatting: (Rows,Columns, Channel, Slice). More than three color channels are supported. See the data structures section for more information.

Using imstack

top | Installing | Launching | Using | Menus | Advanced

When you launch imstack, you should see a window similar to the following:

imstack Interface

  • Window Title. In this example, the title is “IMSTACK | 6 | 12 | 2604 K5rTA…”. The 6 and 12 indicates that the sixth slice in an image of 12 slices is currently being displayed. After the |12| is displayed the user-set title of the image stack.

  • Slice scrubbing. To see all the slices in the image stack, scroll up and down using the mouse (or trackpad). Alternatively, click on the up and down arrows

  • Pixel info: Bottom left corner. Indicates the coordinates and intensity of the pixel indicated by the mouse arrow

  • Comparing stacks: you can use multiple instances of imstack to compare different image stacks. Simply launch a new imstack and load a different stack

Contextual Menu

Right click on the image to bring up a context menu:

  • Copy Pixel Info: copies to the clipboard the info of the current pixel indicated the mouse arrow tip

  • Auto Contrast improves image contrast (especially useful for dim images). Note, this will affect the reported pixel information

  • Crop Stack: allows you to crop the stack after you drawing a bounding box around the region that you want to keep

  • Inspect pixels: brings up the Image Processing Toolbox Pixel Region Tool

  • Show Matrix View: changes the coordinates of the pixels to match matrix coordinates instead of image coordinates

  • Change orthogonal view: changes orientation of image stack (so you can view the stack on the side, etc.)

ROI functions

In addition to the standard figure tools included in the toolbar, there are several ROI tools available, as depicted by the following icons:

The basic functionality of these tools is provided by Yi Sui’s addroitool File Exchange Toolbox.

To use, click on one of the above icons and draw on the displayed image. Basic information such as mean, std, max, and min of the pixel intensity inside the ROI will be overlaid on the image. Note, this information is only relevant to the section that was being displayed when the ROI was drawn.

You can also right click on the ROI for addition functionality

In addition to the built-in functions included with addroitool, the following ROI tool contextual menu items are included with imstack:

  • Section - Erase Mask: zeros all MASK positive pixels inside the the ROI

  • Section - Add Mask: creates MASK positive pixels inside the ROI

  • Stack - Zero mask INSIDE ROI: zeros all positive pixels inside the ROI throughout the entire MASK

  • Stack - Zero mask OUTSIDE ROI: zeros all positive pixels outside the ROI throughout the entire MASK

top | Installing | Launching | Using | Menus | Advanced

File Menu

The File Menu is broken down into three sections.

Top Section

Menu items that open different Image Stacks formats. The accelerator key shortcut, C-O, is set to the last menu item used in this section.

Central Section

Menu items providing an interface to load and save “Datasets.”

Datasets are generated after using the Count Tool. Datasets have a table data structure. They are NOT the image stacks. “Export Dataset as…” saves the dataset as a *.csv format that can be opened by Microsoft Excel.

Bottom Section

Menu items providing a useful interface between imstack and the workspace. You can also save the MASK to hard disk.

View Menu

The View Menu provides some of the standard View Menu tool items (such as Figure, Camera, and Plot Edit toolbars) along with imstack-specific tools to visualize your data:

  • Show Montage: displays a montage of all the image slices in a single window

  • Show Max Projection: Shows a single Projection image of either the Image Stack or of the Mask (if available). Overlays channels if it is a color stack.

  • Projection - Split Channels: For color stacks only. Shows a projection of each channel in a separate subplot.

  • Isosurface - Mask: generates an isosurface of the MASK (after thresholding) for all channels. Uses a default isovalue of 0.5.

Channels Menu

Only appears for color stacks. Select the channel you want to display in imstack

“All” is the default option.

Mask Menu

Only appears after you have used the threshold tool.

Mask Menu Items

  • None: do not display the mask

  • Mask: Only display the mask (do not display the image stack)

  • Blend: Generates a pseudo color overlay of the mask on the image stack. Works for single channel display only (eg. Switch to the Red channel in a color stack if you want to see the overlap between the Red and the Mask). The mask is shown in green and the image stack in magenta

  • Outline: Similar to Blend, but displays an outline of the mask on the grayscale view of the image stack

Tool Menu

The tool menu contains the tools used to process the image stack. Exactly how these tools work depends on the tool script selected in the “Set Tools script” submenu.

The menu items contained in this submenu point to the script folders contained in the imstack/scripts file path. These scripts are designed to be modified by the user.

To create your own toolset, simply add a new folder in the imstack/scripts directory. Script Files called “thresh”, “segment”, and “count” will automatically be linked to the “Threshold…”, “Segmentation tool…”, and “Count Tool…” menu items in the Tool Menu.

A default set of scripts is included with imstack to illustrate how the process works.

EXAMPLE: Using the Castillo_Sonic_LOF

The following example details a custom script set developed for an in-house image processing project. This set of script is included with imstack.

To start, set the Tools Script to “castillo_sonic_lof”

Segmentation Tool

This tool establishes the region of interest that you want to process in the image stack.

  1. Select the “Segmentation Tool” from the Tools Menu (C-R)

  2. Click on the center of the tastebud. You can scroll change slices to make sure you are in the center. Double click on the cross-hair when you have it where you want it.

  3. An ROI rectangle should now appear. Resize this box to your specifications. BE CAREFUL. You should only resize the box once, so make sure you have the size rectangle that you want to use for all tastebuds.

  4. Drag inside the ROI box to move its location

  5. Double-click inside the ROI box to set its position

  6. A “SEGMENTATION captured” notification will appear in the MATLAB Command Window

  7. A Mask Menu will now appear in the menubar (if there wasn’t one already)

  8. Optional: To see the segmentation rectangle: (1) Change the channel to “Red” in the Channel Menu and (2) select “Blend” from the Mask Menu. Scroll through the stack

Threshold Tool

  1. After setting the Segmentation ROI, launch the Threshold tool from the tools menu or by clicking on C-T:

  1. In this popup window, there should be ONE row for each CHANNEL of the image stack.

  2. Adjust the Factor for each channel by fractional increments (e.g. 0.5 or 1.25). This will adjust the threshold level used by the automated thresholding script (Otsu’s method)

  3. Adjust bwareaopen to adjust the pixel size of the noise you want to remove (typical range for this project: 50 –100). Any connected components smaller than indicated pixel size will be eliminated from the thresholded image

  4. In the Channel Menu, change the channel display back to “All” if you have not done so already. The Threshold tool works only on the channel(s) selected in the Channel Menu

  5. Click the “Update” button to apply the threshold

  6. A threshold view of the image stack should now be displayed. Notice a Mask Menu should now appear (if it hadn’t been present previously)

Count Tool

Use the count tool to perform image analysis. The type of analysis performed is determined by the count script. For example, the castillo_sonic_lof script, counts the number of thresholded pixels that are found inside the ROI rectangle set by the Segmentation tool.

To bring up the count tool, click on the “Count Tool” button in the Threshold tool window or Select the Count Tool Menu Item from the Tools Menu (C-Y)

Using the Group Tool

The first time you use the count tool, you need to set up the grouping variables. Clicking on the “Group Tool” button. This will bring up the Groups Setup dialog window

  1. Enter the number of Groups that you have (for example: gender, treatment) and the maximum number of Categories per group. For example, the group “gender” would have two categories: Male and Female. The category treatment could have three categories: Control, Half Dose, Full Dose. So, in this example, we would enter 3 as the maximum number of Categories. Click OK.

  2. Next, enter the name of each group.

  3. You should now see a window like this. In the top table, enter the names of the categories for each group.

Note, the bottom table displays the category last selected in the top table. Whatever is displayed in the bottom table will be added to the count.

Using the Count Tool
  1. Click the “Count” button. You should now see a row of data in the top table of the Count Tool Window.

    Notice that full dose and female have been added to the count
    Notice that “full dose” and “female” have been added to the count
  2. Click on “Add” to add the last row of counts to the dataset.

    Note the data is now added to bottom table, which represents the dataset..

  3. Use the “Remove” any rows incorrectly added to the dataset

  4. Save the analyzed data to file by selecting “Save Dataset” in the File Menu of the imstack window.

When you add the first row of data to the bottom table in the count tool, imstack creates a new variable called DATASET. You can save this DATASET to the hard drive using the relevant menu items in the imstack File Menu.

Analyzing the Next Image stack

  1. Load a new image stack to imstack by selecting the appropriate image projection in the Bioformats window or by opening an new confocal file using “File:Open bioformats” in the imstack window.

  2. Repeat the Segmentation, Threshold, and Count steps

  3. A row to the dataset will be added for each image stack analyzed.

  4. Don’t forget to regularly save the dataset (File:Save Dataset)

Reloading the Dataset

If you quit MATLAB for the day, you can restart your work the next day by:

  1. Launching imstack

  2. Loading a confocal file

  3. Loading the saved dataset by selecting the “File:Load Dataset” menu item from the imstack window

  4. Setting the “castillo_sonic_lof” script in the “Tools:Set Tools Script” menu of the imstack window

Advanced

top | Installing | Launching | Using | Menus | Advanced

data structures

User Data

The imstack UserData that contains relevant information about the image stack. Explore the user data by saving to the workspace using the relevant File Menu commands or by entering the following in the command window:

ud = get(imgcf,'UserData')
Default Fields
  • StudyPath: the path of the image stack
  • StudyDescription:
  • SeriesDescription: ‘Confocal’
  • StackSize: the dimensions of the image stack
  • PixelMax: maximum intensity of a pixel in the entire stack

Internal Use

  • hmf: handle to imstack figure
  • hcmenu: handle to contextual menu
  • himage: handle to displayed image
  • path: Structure containing directory paths for imstack reference
  • SectionIndex: section currently being displayed in imstack
  • SectionCount: the number of sections in the stack
  • DisplayPlane: plane selected by “Orthogonal View” contextual menu item. Default = “transverse”
  • DisplayImAdjust: adjust contrast of image display (toggle using “Adjust Contrast” contextual menu item)
Stack Dependent Info

if available

  • PixelSpacing: physical dimensions of a pixel in x and y

  • SliceThickness: physical thickness of a slice

  • BitDepth

Color Stack Fields
  • ChannelCount: the number of channels
  • ChannelName: the names of each channel (instrument dependent, eg. Leica/ALEXA 546)
  • ChannelRGB: A Nx3 array containing RGB info, where N is the number of channels
  • ChannelRGBName: A cell array of RGB color names (e.g. “red, green, blue”)
  • ChanelSelected: The channel selected in the Channels Menu.
  • ChannelIdx: The index of the channel selected in the Channels Menu

appdata

The following data is stored in the main imstack window as MATLAB Figure appdata

IMGS

A 3- or 4D matrix of the image stack dataset. A 4D matrix contains channel information in the third dimension

  • Indices in the 3D matrix are formatted as follows

IMGS(rows, columns, section)

  • Indices for 4D matrix are configured as follows:

IMGS(rows,columns, channel,section)

e.g. the red channel image stack from a 4D matrix can be accessed as follows:

IMGS = getappdata(imgcf,'IMGS');
RED = squeeze(IMG(:,:,1,:));

MASK

A binary matrix (logical array) that contains the output from the threshold command.

MASK must have the same dimensions as IMGS.

You can load a mask stack with an image stack from the workspace by typing the following command in the workspace

imstack(IMGS,[],MASK)

DS

Stores the image processing dataset collected after using the count tool. DS is a table variable. You can access the DS dataset using the following command:

DS = getappdata(imgcf,'DS');

tool_handles

A structure containing all the relevant information for the image processing tools (e.g. Threshold, Segment, and Count)

ht = getappdata(imgcf, 'tool_handles')

ht = 

    tool_names: {'count'  'thresh'  'segment'}
     tool_path: '/Users/ernesto/Dropbox/Public/M…'
         count: [1x1 struct]
       segment: [1x1 struct]
        thresh: [1x1 struct]
        tool_h: [1x1 struct]

Keyboard Shortcuts

On mac and pcs, the keyboard shortcuts differ in the modifier key used to in the shortcut.

So, C stands for either Control (PC) or Command​​