Download MicroManager PolScope (plugin) User Manual

Pol-Analyzer User Manual, Birefringence Imaging
1|P a g e
Pol-Analyzer, OpenPolScope software for ImageJ
Last Updated: April 15, 2013; Revision 1.07
This manual was prepared with Pol-Analyzer software version 2.0
Copyright, license, and warranty/disclaimer statements at end of document.
Table of Contents
Before Installation............................................................................................................................................. 2
Installation............................................................................................................................................................ 4
Pol-Analyzer Window.................................................................................................................................. 4
Overview of Functionality and Tabs........................................................................................................... 5
Data tab............................................................................................................................................................. 5
Parameters tab............................................................................................................................................... 6
Birefringence tab........................................................................................................................................... 7
Processing tab................................................................................................................................................. 8
Options tab....................................................................................................................................................... 9
BatchMode tab............................................................................................................................................. 10
Help....................................................................................................................................................................... 11
Report tool..................................................................................................................................................... 11
ChangeLog..................................................................................................................................................... 12
About............................................................................................................................................................... 13
Copyright, license, warranty/disclaimer............................................................................................... 14
Pol-Analyzer User Manual, Birefringence Imaging
2|P a g e
Before Installation
OpenPolScope plugins come in two flavors, which are installed in different plugin folders
inside the Micro-Manager folder:
1. Pol-Acquisition plugin; after its installation into the MMplugins folder, this plugin
appears in the Micro-Manager Plugins menu. It is used to acquire PolScope images,
applying PolScope algorithms and controlling the OpenPolScope hardware attached
to the microscope.
2. Pol-Analyzer plugin; after its installation into the plugins folder, this plugin appears
in the ImageJ Plugins menu, providing functions to view and analyze PolScope data
that have been previously acquired.
The OpenPolScope software installer installs both plugins.
Software requirements:
1. Micro-Manager (tested with release 1.4.13, subsequent changes in Micro-Manager
code might result in unexpected behavior)
2. OpenPolScope software
Installer for Windows XP, 7, and Vista: LCPolScopeSetup.exe
Installer for Mac: LCPolScopeSetup.pkg
OpenPolScope software components:
Micro-Manager Plugins menu:
Pol-Acquisition, FrameAverager, TopFrame
Image J Plugins menu
PolScope: Pol-Analyzer; Birefringence; Orientation-Lines
PolScope Legacy: RatioAzimPolStackToRGB_V2; ROI_Averages_With_Lines_V1;
StackAverage_
Java Console
Minimum and recommended system requirements
•
Hardware:
1. OpenPolScope hardware, consisting of liquid-crystal (LC) universal compensator
and VariLC or equivalent electronic controller.
2. Camera, supported by Micro-Manager
3. Computer recommended 1.5GHz CPU dual core, 64-bit
4. 2 GB RAM (recommended 4 GB RAM)
5. 10 MB Hard Disk Space (additional space required for UserData)
Pol-Analyzer User Manual, Birefringence Imaging
•
3|P a g e
Software:
1. Windows XP, Windows 7, Mac (32/64 bit)
(OpenPolScope software is currently not tested on Mac)
2. Java 1.6 update 31
Note: It is recommended to increase the ImageJ memory (Edit>Options>Memory…) to a
minimum of 128MB or more if images are kept in RAM.
Guide to abbreviations
File naming
convention
SM_2012_0904_0213_5
Prefix_Year_MonthDate_HourMin_Suffix
Prefix:
SM – Sample
BG – Background
SMS - Sample Series
(Multi-Dimensional)
OpenPolScope data directory structure
Image data is expected to be organized according to the following directory tree:
<LCPolScopeData> --------- (user chosen top directory)
|
<UserName1> --------- (contains directories of a single user/project)
|
<SessionDate1>--- (contains image and metadata files of a day’s session)
|
<SessionDate2>
<UserName2> --------- (contains directories of another user/project)
|
<SessionDate1>--- (contains image and metadata files of a day’s session)
|
<SessionDate2>
Pol-Analyzer User Manual, Birefringence Imaging
4|P a g e
Installation
For using the Pol-Analyzer plugin, the user needs to be familiar with ImageJ. The plugin is
installed into the plugins folder and appears in the ImageJ Plugins menu, providing
functions to view and analyze PolScope data that have been previously acquired. Image
data need to be formatted as Micro-Manager stacks (not ImageJ stacks). Therefore, in its
current release, Pol-Analyzer requires the co-installation of Micro-Manager.
The Pol-Analyzer plugin can be accessed
from the ImageJ Plugins menu.
The Orientation-LinesV3 plugin can be
used to set parameters in a single query
panel and will operate on an open and
active PolScope stack (Micro-Manager
and ImageJ stack format).
The PolScope Legacy entry contains
plugins that operate only on traditional
ImageJ PolScope stacks (ImageJ stacks)
Pol-Analyzer Window
The Pol-Analyzer window contains
action buttons, a progress bar, and
several tabs that let the user set data
locations, measurement parameters,
options, etc. The following sections
give an overview of the window
components.
Pol-Analyzer User Manual, Birefringence Imaging
5|P a g e
Overview of Functionality and Tabs
The top line shows the folder names of the
current User/Project and Session.
The Process button initiates the recalculation
of the image data as specified by the settings
in the tab panels
The progress bar gives an estimate of the
completion of an active process.
Status messages are printed below the bar.
Data tab
In the Data tab panel, the root folder Data
Location can be selected, where MicroManager data were saved. The lists of
existing User and Session folders are then
loaded into their corresponding pull down
menus.
Note: The PolScope-Analyzer only works on
existing data. Use the Pol-Acquisition plugin
to acquire new PolScope images
Session Description: This description is
imported when the Session was created and
can be updated during Processing.
Saving
Overwrite Original Processed Images: Enable
this option to overwrite previously
computed images. Default is enabled.
Show Overwrite Confirmation message:
When enabled, prompts for a confirmation before previously computed data are
overwritten. Default is enabled.
Note: If overwrite is enabled, only processed images are overwritten. Raw images are
never modified or overwritten.
Note: Newly computed data can only be saved by overwriting previous results at the time
of generating the new results. If Overwriting Original Processed Images is not checked, the
newly computed data, displayed in the stack, can only be saved to disk as a new, complete
data stack, because Save commands in Micro-Manager don’t allow overwriting previous
data.
Pol-Analyzer User Manual, Birefringence Imaging
Parameters tab
6|P a g e
This tab lets the user select the image
window that holds the sample data
(Processed Data) to be processed and the
associated background data, if available.
Pull-down menus let the user choose
between available datasets. Depending on
the check box settings in the Options
panel, the entries in the sample pull down
menu vary. The Open button lets the user
open sample data from the disk.
The tab also shows measurement
parameters at the time of acquisition or
last
processing.
The
information
displayed here is stored in the metadata
file and parsed when the dataset is
loaded.
These parameters should not require any modifications. However, if background correction
was not applied during acquisition or other parameters were not correct, the values can be
edited and once reprocessed are saved to the image metadata.
Image-Path Mirror: Used for an Inverted microscope or if there is a mirror in the optical
path. Setting the mirror parameter inappropriately leads to incorrectly computed
orientation values. Retardance values are not affected by the mirror setting.
Wavelength: Sets the wavelength that will be used when setting the retardance values.
Default is 546 nm.
Swing: Sets the nominal retardance bias (as a fraction of the wavelength) for the elliptical
settings of the liquid crystals.
Black Level: The blacklevel is the average pixel value that is measured when the camera is
not illuminated. The black level primarily depends on the camera offset setting.
Pol-Analyzer User Manual, Birefringence Imaging
Birefringence tab
7|P a g e
The main processor selected in
the Processing panel (here
Birefringence) will be displayed
as an additional tab. Its panel
will contain options only
applicable when this processor
is selected.
Retardance Ceiling: Sets the
value of the retardance ceiling
that is used for storing the
retardance values in its image
channel (usually first image). By
way of explanation, all image
data are stored as 8 bit or 16 bit pixel values, including the computed or virtual channels.
For display and storage, computed retardance values are converted to 8- or 16-bit integer
values, linearly mapping the retardance between 0 and the ceiling value into 0 and 255 (8bit) or 0 and 4095 (16-bit). 4095 was chosen to make the converted retardance values
similar to the intensity values acquired by a 12-bit camera. Retardance values that are
computed to be higher than the ceiling value are stored as 255 or 4095.
Orientation Reference: Sets the orientation reference that is used for processing the slow
axis orientation image. (See Pol-Acquisition manual, sections “Calibration of calculated
retardance and orientation values” and “Mapping of calculated retardance and orientation
values into 8-bit and 16-bit images”)
Use 4-Frame Processing...: Option to use only 4 frames for processing, dropping the last
raw image channel.
Convert Non Micro-Manager PolStack to Mmgr Dataset : This option allows converting
PolStack acquired using Psj or any software to be converted as a Micro-Manager PolStack.
Default values might be used to populate metadata field and once converted the new
dataset should be re-processed with correct parameters (eg. Background, retardance
ceiling, swing, etc.)
Pol-Analyzer User Manual, Birefringence Imaging
Processing tab
8|P a g e
The Processing tab is divided into 3
main segments.
PreProcessing: This applies some
modifications to the raw image data
before they are sent to the main
processor. An example is Ratioing in
which the pixel values of the sample
images are multiplied by a correction
factor calculated based on the
background
images.
Multiple
Preprocessors can be selected.
Note: The raw image data that are
stored in the raw image channels are
never altered during any processing
steps, including preprocessing and
postprocessing.
Processing Mode: This is the main processor, which controls the processing algorithms. It
defines the number of raw images expected; the number of computed images, which are
also called virtual channels; the computation algorithm for the virtual channel images;
along with other parameters. Only one Processing Mode can be selected. A Processing Mode
has its own options tab (eg. Birefringence).
PostProcessing: This applies some post-processing correction to the images. It can also be
used to generate additional images. Multiple Postprocessors can be selected.
Note: All the OpenPolScope processors that are currently installed will be displayed in this
tab.
Note: Pre/PostProcessor may or may not have additional options that are indicated by a
button.
Note: If a PolScope data set is opened and the associated Processing Mode plugin is not
installed, the data-set will open as a regular Micro-Manager data-set and not a PolScope
data-set.
Pol-Analyzer User Manual, Birefringence Imaging
Options tab
9|P a g e
In the Options tab one can set
preferences for the Pol-Analyzer.
Processing:
Process stacks: If checked, processing
occurs for all computed channels of a
data-set (stack); if not checked,
processing occurs only for the
currently selected time-point and/or
z-position. Default is enabled.
Run Processing from Slider: When
enabled will execute processing
whenever a value is changed from the
slider (eg. Retardance ceiling slider).
Default is disabled.
Dont Process...: This option allows
walking the data-set through time, slice, position without processing. The currently
selected channel is always displayed.
Parallelize Processing: Enables processing using multiple cpu cores that are available. This
option provides full utilization of processing power when processing a Multi-dimentional
stack. This should not be enabled when acquiring images and Processing at the same time.
Default is enabled.
Program:
Show only Open Windows...: Modifies the behavior of the 'Open...' button under Parameters
to List view instead of File dialog opener. Default is enabled.
Batch Processing Mode: Selecting this option provides a BatchMode panel for batch
processing multi datasets. The Process button is transformed for 'Batch Process' and its
corresponding panel is added next to Options panel.
Note: During Batch Processing mode 'Open windows' will be ignored and the datasets
required for processing can be selected from the panel's table-view. The currently selected
Pol-Analyzer User Manual, Birefringence Imaging
10 | P a g e
Processing Mode is the default method used. If a Session consists of different type
(different modes) of acquired data, those other datasets will be skipped when processing.
BatchMode tab
Batch Processing only allows certain parameters that are Batch Processable. Once selected by enabling their checkbox, those values and/or selections will be applied to all the datasets that have
been selected for Processing.
Pol-Analyzer User Manual, Birefringence Imaging
11 | P a g e
Help
Report tool
The Report tool can be accessed via the Menu bar to send bug reports or suggestions.
Pol-Analyzer User Manual, Birefringence Imaging
ChangeLog
12 | P a g e
Pol-Analyzer User Manual, Birefringence Imaging
About
13 | P a g e
Pol-Analyzer User Manual, Birefringence Imaging
14 | P a g e
Copyright, license, warranty/disclaimer
Copyright © 2009 - 2013, Marine Biological Laboratory
NOTICE: Some of the algorithms herein are protected by US patent #5521705, #7202950
and other patents applied for or pending.
LICENSE (Berkeley Software Distribution License): Redistribution and use in source and
binary forms, with or without modification, are permitted provided that the following
conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list
of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
3. Neither the name of the Marine Biological Laboratory nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The views and conclusions contained in the software and documentation are those of the
authors and should not be interpreted as representing official policies, either expressed or
implied, of any organization.
From the Laboratory of
Rudolf Oldenbourg ([email protected])
Cellular Dynamics Program
Marine Biological Lab,
Woods Hole, MA
USA
© 2013