Browse Source

Use the Maven Site plugin for the documentation.

Replace the DocBook manual by a site handled by the Maven
Site plugin, which also includes the Javadocs.
master
parent
commit
a8b2676625
13 changed files with 266 additions and 549 deletions
  1. +0
    -1
      .gitignore
  2. +0
    -547
      doc/manual.xml
  3. +21
    -1
      pom.xml
  4. +34
    -0
      src/site/apt/extended-panel.apt
  5. +72
    -0
      src/site/apt/index.apt
  6. +126
    -0
      src/site/apt/unified-merge.apt
  7. +0
    -0
      src/site/resources/images/merge-output-all-panels.png
  8. +0
    -0
      src/site/resources/images/merge-output-single-merge.png
  9. +0
    -0
      src/site/resources/images/merge-output-vertical.png
  10. +0
    -0
      src/site/resources/images/merge-settings-1.png
  11. +0
    -0
      src/site/resources/images/panel-output-1.png
  12. +0
    -0
      src/site/resources/images/panel-settings-1.png
  13. +13
    -0
      src/site/site.xml

+ 0
- 1
.gitignore View File

@ -1,4 +1,3 @@
/javadoc/
/target/
/.classpath
/.project


+ 0
- 547
doc/manual.xml View File

@ -1,547 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<article xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en">
<info>
<title>Incenp.org ImageJ Plugins</title>
<author>
<personname>
<firstname>Damien</firstname>
<surname>Goutte-Gattat</surname>
</personname>
<email>dgouttegattat@incenp.org</email>
</author>
<copyright>
<year>2019</year>
<holder>Damien Goutte-Gattat</holder>
</copyright>
</info>
<para><application>Incenp.org ImageJ Plugins</application> are a set of
plugins for the <link xl:href="https://imagej.net/">ImageJ</link> image
analysis software.</para>
<para>Currently, the set contains two plugins: <emphasis>Unified
Merge</emphasis>, to create merged images from a hyperstack, and
<emphasis>Extended Panel</emphasis>, to create a panel from selected
frames in a hyperstack.</para>
<note>
<para>Those plugins are <emphasis>not</emphasis> intended to build
“publication-quality” figures with all the flexibility that one would
expect from a figure preparation tool. Rather, they are intended to
provide a quick and easy way to generate “good enough” images.</para>
<para>As such, many aspects of the generated images are hardcoded in the
plugins’ code and cannot be changed by the user without directly
modifying said code.</para>
<para>For users looking for a full-featured figure preparation tool, I
would personally recommend <link
xl:href="http://figure.openmicroscopy.org/">OMERO.figure</link>, an
application for the <link
xl:href="http://www.openmicroscopy.org/omero/">OMERO server</link> and
its OMERO.web client.</para>
</note>
<para>The plugins are distributed under the terms of the GNU General Public
License, version 3 or higher.</para>
<section>
<title>Setup</title>
<section>
<title>From a binary distribution</title>
<para>Binary distributions, in the form of JAR files, are available on
the <link
xl:href="https://git.incenp.org/damien/imagej-plugins/releases">release
page</link> of the project.</para>
<para>Simply download the latest JAR file on that page (named
<filename>incenp_plugins-<replaceable>X.Y.Z</replaceable>.jar</filename>,
where <replaceable>X.Y.Z</replaceable> is the latest version) and save
it anywhere under the <filename class="directory">plugins/</filename>
directory of your ImageJ installation.</para>
<para>The plugins will be available upon the next restart of ImageJ
under the
<menuchoice><guimenu>Plugins</guimenu><guisubmenu>Incenp.org</guisubmenu></menuchoice>
menu. You may also check the plugins were installed correctly by
opening the plugins’ “about” dialog under
<menuchoice><guimenu>Help</guimenu><guisubmenu>About
Plugins</guisubmenu><guimenuitem>Incenp.org
Plugins...</guimenuitem></menuchoice>.</para>
</section>
<section>
<title>From source</title>
<para>You may download the source code either from a tarball archive on
the <link
xl:href="https://git.incenp.org/damien/imagej-plugins/releases">release
page</link>, or directly from the Git repository:</para>
<screen>
<prompt>$ </prompt><command>git clone https://git.incenp.org/damien/imagej-plugins.git</command>
</screen>
<para>The project uses <link
xl:href="https://maven.apache.org/">Maven</link> as its build
system, so you need to have Maven installed with the
<command>mvn</command> command available from the shell. Then, simply
run the following command from the source directory:</para>
<screen>
<prompt>$ </prompt><command>mvn package</command>
</screen>
<para>This will generate a JAR archive named
<filename>incenp_plugins-<replaceable>X.Y.Z</replaceable>.jar</filename>
in the <filename class="directory">target</filename> subdirectory.
Install that file in your ImageJ’s <filename
class="directory">plugins</filename> directory as described in the
previous section.</para>
</section>
</section>
<section>
<title>The Unified_Merge plugin</title>
<para>This plugin allows to create an image which may contain one or
several individual channels in grayscale alongside a colored merge of
several channels.</para>
<figure xml:id="fig.unified_merge.output.1">
<title>Sample output from the Unified_Merge plugin</title>
<mediaobject>
<imageobject>
<imagedata fileref="imgs/merge-output-all-panels.png" align="center"
width="12cm"/>
</imageobject>
</mediaobject>
</figure>
<para>To illustrate the purpose of this plugin, let’s consider a sample
output in <xref linkend="fig.unified_merge.output.1"
xrefstyle="select:label" />. The hyperstack used as the source image
was made of 3 different channels (<literal>DiC</literal>,
<literal>mCherry::H2A.Z</literal>, and <literal>GFP::Polo</literal>).
From that source, the plugin generated an image composed of 4 panels
side by side: the 3 leftmost panels depict the individual channels, in
grayscale; the rightmost panel depicts a composite colored image of all
3 channels merged together.</para>
<figure xml:id="fig.unified_merge.settings">
<title>Settings dialog for the Unified Merge plugin</title>
<mediaobject>
<imageobject>
<imagedata fileref="imgs/merge-settings-1.png" align="center"
width="8cm"/>
</imageobject>
</mediaobject>
</figure>
<para>When the plugin is called, you’re presented with a settings dialog
like the one depicted in <xref linkend="fig.unified_merge.settings"
xrefstyle="select:label" />. The settings are organized in several
sections.</para>
<section>
<title>General settings</title>
<para>This section contains the following settings:</para>
<variablelist>
<varlistentry>
<term><option>Orientation</option></term>
<listitem>
<para>This defines whether the panels will be placed next to each
other, with the merged panel on the right
(<literal>Horizontal</literal>), or one on top of another, with
the merged panel at the bottom
(<literal>Vertical</literal>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Separator width</option></term>
<listitem>
<para>If this option is enabled, the panels will be separated by a
white line whose width (in pixels) can also be specified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Font size</option></term>
<listitem>
<para>This is the size of the font used to display the labels. The
value can range from 8 to 24.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Copy original overlay only once</option></term>
<listitem>
<para>If the original hyperstack contain an overlay and this
option is enabled, the overlay will only be carried over to the
first panel (leftmost panel or top panel, depending on the
orientation setting) of the final image. If this option is not
enabled, the overlay will be duplicated as needed to be carried
over to all panels.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Frame settings</title>
<para>Settings in this section are only meaningful for hyperstacks
containing several time frames (t-frames).</para>
<variablelist>
<varlistentry>
<term><option>First frame</option></term>
<term><option>Last frame</option></term>
<listitem>
<para>Those settings allow to create an image containing only a
subset of the t-frames from the original hyperstack.
<option>First frame</option> is the one-based index of the first
t-frame to include in the resulting image; <option>Last
frame</option> is the one-based index of the last t-frame to
include. The default behavior is to include all t-frames (i.e.
<option>First frame</option> defaults to 1 and <option>Last
frame</option> defaults to the number of t-frames.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Show labels on all frames</option></term>
<term><option>Show labels in this frame</option></term>
<listitem>
<para>If the <option>Show labels in this frame</option> option is
selected, channel labels will only be put on the indicated
t-frame; otherwise all t-frames will carry the labels.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Show time labels</option></term>
<listitem>
<para>If this option is enabled, each t-frame will carry a time
indicator on the top left corner of the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Interval</option></term>
<listitem>
<para>If enabled, this option allows to specify the time elapsed
(in seconds) between each t-frame; otherwise the plugin will
attempt to find that information in the metadata of the original
hyperstack.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Offset first frame</option></term>
<listitem>
<para>If this option is enabled and the <option>First
frame</option> is set to anything else than its default value
of 1, time indicators will be shifted so that the first actual
t-frame to be included in the resulting image will have a time
of 0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Use 00:00 format</option></term>
<listitem>
<para>If enabled, time indicators will be displayed with a
semi-colon to separate minutes from seconds. Otherwise the
default format is to display <literal>h</literal>,
<literal>m</literal> and <literal>s</literal> units.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Channel settings</title>
<para>The settings dialog will contain one channel settings section for
each channel in the original hyperstack.</para>
<variablelist>
<varlistentry>
<term><option>Name</option></term>
<listitem>
<para>This is the name which will be used to label the
channel.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Color</option></term>
<listitem>
<para>This is the color to use to colorize that channel in the
merged image. The channel label will also be displayed in the
indicated color.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Show individual image</option></term>
<listitem>
<para>If this option is enabled, the channel will be displayed on
a panel of its own, in the leftmost (or top, depending on the
<option>Orientation</option> setting) part of the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Show merged image</option></term>
<listitem>
<para>If this option is enabled, the channel will appear on the
merged panel, in the rightmost (or bottom, depending on the
<option>Orientation</option> setting) part of the image.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Examples</title>
<para><xref linkend="fig.unified_merge.output.1"
xrefstyle="select:label" /> above was an example of an image with
all channels displayed both individually and on the merged panel
(<option>Show individual image</option> and <option>Show merged
image</option> options enabled for all 3 channels).</para>
<figure xml:id="fig.unified_merge.output.2">
<title>Example of a single merge</title>
<mediaobject>
<imageobject>
<imagedata fileref="imgs/merge-output-single-merge.png" align="center"
width="4cm"/>
</imageobject>
</mediaobject>
</figure>
<para><xref linkend="fig.unified_merge.output.2"
xrefstyle="select:label" /> is an example of a simple merge, with
all channels only displayed as part of the merged image. This image
was generated by enabling the <option>Show merged image</option>
option and disabling the <option>Show individual image</option> option
for all 3 channels.</para>
<figure xml:id="fig.unified_merge.output.3">
<title>Example of a more elaborated merge</title>
<mediaobject>
<imageobject>
<imagedata fileref="imgs/merge-output-vertical.png" align="center"
width="4cm"/>
</imageobject>
</mediaobject>
</figure>
<para>Finally, <xref linkend="fig.unified_merge.output.3"
xrefstyle="select:label" /> is an example of a more complex merge,
where only the <literal>GFP::Polo</literal> is shown on a panel of its
own, while the merged panel contains all three channels. This image
was generated by enabling the <option>Show merged image</option>
option on all three channels, but enabling the <option>Show individual
channel</option> option only on the <literal>GFP::Polo</literal>
channel. Note also that the <option>Orientation</option> option was
set to <literal>Vertical</literal>.</para>
</section>
</section>
<section>
<title>The Extended_Panel plugin</title>
<para>This plugin allows to create an image containing a selection of
t-frames (or z-slices) from a given hyperstack, disposed in an
array.</para>
<figure xml:id="fig.extended_panel.output.1">
<title>Sample output for the Extended_Panel plugin</title>
<mediaobject>
<imageobject>
<imagedata fileref="imgs/panel-output-1.png" align="center"
width="12cm"/>
</imageobject>
</mediaobject>
</figure>
<para><xref linkend="fig.extended_panel.output.1" xrefstyle="select:label"
/> illustrates the purpose of this plugin. The source image in that
example was a “simple merge” generated by the Unified_Merge plugin as in
<xref linkend="fig.unified_merge.output.2" xrefstyle="select:label" />
above. Six t-frames from that image were selected and disposed in two
rows and three columns.</para>
<figure xml:id="fig.extended_panel.settings">
<title>Settings dialog for the Extended_Panel plugin</title>
<mediaobject>
<imageobject>
<imagedata fileref="imgs/panel-settings-1.png" align="center"
width="8cm"/>
</imageobject>
</mediaobject>
</figure>
<para>When the plugin is called, you’re presented with a settings dialog
like the one depicted in <xref linkend="fig.extended_panel.settings"
xrefstyle="select:label" />.</para>
<variablelist>
<varlistentry>
<term><option>Columns</option></term>
<term><option>Rows</option></term>
<listitem>
<para>Those options define the number of columns and rows to display
in the final image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Selected frames</option></term>
<listitem>
<para>This is the list of t-frames to include in the final image.
Each frame to include is to be specified by its one-based frame
index. If there is less frames than the number of panels in the
final image (that is, less than the product of
<option>Columns</option> and <option>Rows</option>), the last
panels will be left blank.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>Separator width</option></term>
<listitem>
<para>If this option is enabled, the panels will be separated by a
white line whose width (in pixels) can also be specified.</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>If the source image contains only one t-frame but several z-slices,
the plugin will work z-slices instead of t-frames.</para>
</note>
</section>
</article>

+ 21
- 1
pom.xml View File

@ -3,7 +3,7 @@
<parent>
<groupId>org.incenp</groupId>
<artifactId>incenp-base</artifactId>
<version>1.0.0</version>
<version>1.1.0</version>
</parent>
<groupId>org.incenp.imagej</groupId>
@ -82,7 +82,27 @@
<artifactId>maven-release-plugin</artifactId>
<version>2.5.3</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.8.2</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>3.0.0</version>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.1.1</version>
</plugin>
</plugins>
</reporting>
</project>

+ 34
- 0
src/site/apt/extended-panel.apt View File

@ -0,0 +1,34 @@
The Extended_Panel plugin
This plugin allows to create an image containing a selection of
t-frames (or z-slices) from a given hyperstack, disposed in an array.
[images/panel-output-1.png] Sample output for the Extended_Panel plugin
The figure above illustrates the purpose of this plugin. The source
image in that example was a “simple merge” generated by the
{{{./unified-merge.html}Unified Merge plugin}}. Six t-frames from that
image were selected and disposed in two rows and three columns.
When the plugin is called, you´re presented with a settings dialog lik
the one depicted in the figure below.
[images/panel-settings-1.png] Settings dialog for the Extended_Panel plugin
The settings are as follows:
[Colums / Rows] Those options define the number of columns and rows
to display in the final image.
[Selected frames] This is the list of t-frames to include in the
final image. Each frame to include is to be specified by its 1-based
frame index. If there is less frames than the number of panels in
the image (that is, less than the product of <Columns> and <Rows>),
the last panels will be left blank.
[Separator width] If this option is enabled, the panels will be
separated by a white line whose width (in pixels) can also be
specified.
Note that if the source image contains only one t-frame but several
z-slices, the plugin will work with z-slices instead of t-frames.

+ 72
- 0
src/site/apt/index.apt View File

@ -0,0 +1,72 @@
-------------------------
Incenp.org ImageJ Plugins
-------------------------
Damien Goutte-Gattat
--------------------
2020-01-12
----------
<Incenp.org ImageJ Plugins> are a set of plugins for the
{{{https://imagej.net}ImageJ}} image analysis software.
Currently, the set contains two plugins: <Unified Merge>, to create
merged images from a hyperstack, and <Extended Panel>, to create a
panel from selected frames in a hyperstack.
Those plugins are <not> intended to build “publication-quality”
figures with all the flexibility that one would expect from a figure
preparation tool. Rather, they are intended to provide a quick and
easy way to generate “good enough” images. As such, many aspects of
the generated images are hard-coded in the plugins’ code and cannot be
changed by the user without directly modifying said code.
For users looking for a full-featured figure preparation tool, I would
personally recommend {{{http://figure.openmicroscopy.org/}OMERO.figure}},
an application for the {{{http://www.openmicroscopy.org/}OMERO server}}
and its OMERO.web client.
The plugins are distributed under the terms of the GNU General Public
License, version 3 or higher.
Setup
* From a binary distribution
Binary distributions, in the form of JAR files, are available on the
{{{https://git.incenp.org/damien/imagej-plugins/releases}release page}}
of the project.
Simply download the latest JAR file on that page (named
<incenp-plugins-X.X.Y.jar>, where <X.Y.X> is the latest version) and
save it anywhere under the <plugins> directory of your ImageJ
installation.
The plugins will be available upon the next restart of ImageJ under
the <Plugins\>Incenp.org> menu. You may also check the plugins were
installed correctly by opening the plugins’ “about” dialog under
<Help\>About Plugins...\>Incenp.org Plugins...>.
* From source
You may download the source code either from a tarball archive on the
{{{https://git.incenp.org/damien/imagej-plugins/releases}release page}},
or directly from the Git repository:
+-----------------------------------------------------------
$ git clone https://git.incenp.org/damien/imagej-plugins.git
+-----------------------------------------------------------
The project uses {{{https://maven.apache.org/}Maven}} as its build
system, so you need to have Maven installed with the <mvn> command
available from the shell. Then, simply run the following command from
the source directory:
+------------
$ mvn package
+------------
This will generate a JAR archive named <incenp-plugins-X.Y.Z.jar> in
the <target> directory. Install that file in your ImageJ’s <plugins>
directory as described in the previous section.

+ 126
- 0
src/site/apt/unified-merge.apt View File

@ -0,0 +1,126 @@
The Unified_Merge Plugin
This plugin allows to create an image which may contain one or
several individual channels in grayscale alongside a colored
merge of several channels.
[images/merge-output-all-panels.png] Sample output from the Unified_Merge plugin
To illustrate the purpose of this plugin, let´s consider a sample
output in the figure above. The hyperstack used as the source image
was made of three different channels (DiC, mCherry::H2A.Z, and
GFP::Polo). From that source, the plugin generated an image composed
of four panels side by side: the three leftmost panels depict the
individual channels, in grayscale; the rightmost panel depicts a
composite colored image of all three channels merged together.
When the plugin is called, you´re presented with a settings dialog
lile the one depicted below. The settings are organized in several
sections.
[images/merge-settings-1.png] Settings dialog for the Unified_Merge plugin
* General settings
This section contains the following settings:
[Orientation] This defines whether the panels will be placed next to
each other, with the merged panel on the right (<Horizontal>), or
one on top of another, with the merged panel at the bottom
<Vertical>).
[Separator width] If this option is enabled, the panels will be
separated by a white line whose width (in pixels) can also be
specified.
[Font size] This is the size of the font used to display the labels.
The value can range from 8 to 24.
[Copy original overlay only once] If the original hyperstack
contains an overlay and this option is enabled, the overlay will
only be carried over to the first panel (leftmost panel or top
panel, depending on the orientation setting) of the final image. If
this option is not enabled, the overlay will be duplicated as needed
to be carried over to all panels.
* Frame settings
Settings in this section are only meaningful for hyperstacks
containing several time-frames (t-frames).
[First frame/Last frame] Those settings allow to create an image
containing only a subset of the t-frames from the original
hyperstack. <First frame> is the 1-based offset of the first t-frame
to include in the resulting image; <Last frame> is the 1-based index
of the last t-frame to include. The default behavior is to include
all t-frames (i.e. <First frame> defaults to 1 and <Last frame>
defaults to the number of t-frames).
[Show labels on all frames] If this option is selected, channel
labels will be visible on all t-frames.
[Show labels in this frame] If the previous option is not selected,
this setting indicates which t-frame will carry the channel labels.
[Show time labels] If this option is enabled, each t-frame will
carry a time indicator on the top left corner of the image.
[Interval] If enabled, this option allows to specify the time
elapsed (in seconds) between each t-frame; otherwise the plugin will
attempt to find that information in the metadata of the original
hyperstack.
[Offset first frame] If this option is enabled and the <First frame>
option is set to anything else than its default value of 1, time
indicators will be shifted so that the first actual t-frame to be
included in the resulting image will have a time of 0.
[Use 00:00 format] If enabled, time indicators will be displayed
with a semi-colon to separate minutes from seconds. Otherwise the
default format is to display <h>, <m>, and <s> units.
* Channel settings
The settings dialog will contain one channel settings section for each
channel in the original hyperstack.
[Name] This is the name which will be used to label the channel.
[Color]This is the color to use to colorize the channel in the
merged image. The channel label will also be displayed in the
indicated color.
[Show individual image] If this option is enabled, the channel will
be displayed on a panel of its own, in the leftmost (or top,
depending on the <Orientation> setting) part of the image.
[Show merged image] If this option is enabled, the channel will
appear on the merged panel, on the rightmost (or bottom, depending
on the <Orientation> setting) part of the image.
* Examples
The first figure on the top of this page was an example of an image
with all channels dusplayed both individually and on the merge panel
(<Show individual image> and <Show merged image> options enabled for
all three channels.
The image below is an example of a simple merge, with all channels
only displayed as part of the merged image. This image was generated
by enabling the <Show merged image> option and disabling the <Show
individual image> option for all three channels.
[images/merge-output-single-merge.png] Example of a simple merge
Finally, the image below is an example of a more complex merge, where
only the <GFP::Polo> channel is shown on a panel of its own, while the
merged panel contains all three channels. This image was generated by
enabling the <Show merged image> option on all three channels, but
enabling the <Show individual channel> option only on the GFP::Polo
channel. Note also that the <Orientation> option was set to “Vertical”.
[images/merge-output-vertical.png] Example of a more elaborated merge

doc/imgs/merge-output-all-panels.png → src/site/resources/images/merge-output-all-panels.png View File


doc/imgs/merge-output-single-merge.png → src/site/resources/images/merge-output-single-merge.png View File


doc/imgs/merge-output-vertical.png → src/site/resources/images/merge-output-vertical.png View File


doc/imgs/merge-settings-1.png → src/site/resources/images/merge-settings-1.png View File


doc/imgs/panel-output-1.png → src/site/resources/images/panel-output-1.png View File


doc/imgs/panel-settings-1.png → src/site/resources/images/panel-settings-1.png View File


+ 13
- 0
src/site/site.xml View File

@ -0,0 +1,13 @@
<?xml version="1.0"?>
<project xmlns="http://maven.apache.org/DECORATION/1.8.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION 1.8.0
http://maven.apache.org/xsd/decoration-1.8.0.xsd">
<body>
<menu name="Plugins">
<item name="Unified Merge" href="unified-merge.html" />
<item name="Extended Panel" href="extended-panel.html" />
</menu>
<menu ref="reports" />
</body>
</project>

Loading…
Cancel
Save