Merge branch 'img-metadata'

This branch introduces a new component, imglib2-meta, to manage extra
metadata about N-dimensional images. In particular, it provides a class
hierarchy for attaching per-dimension metadata as extensions of the Axis
interface. The AnnotatedSpace interface provides a EuclideanSpace
extension that manages the Axis list.

This change breaks backwards compatibility. The existing
net.imglib2.meta package and net.imglib2.img.ImgPlus class have been
migrated from imglib2 core to the new imglib2-meta component. See below
for instructions on how to update existing code.

The old AxisType interface is now only one part of an Axis, specifically
a TypedAxis. The CalibratedAxis interface extends TupedAxis and
includes a unit (as a simple string) and a calibration (as a plain
double for now).

We will eventually need to enhance the Views utility methods to respect
AnnotatedSpace-based objects. This will ensure that Views
transformations keep Axis objects attached to their proper dimensions in
an extensible way when things are restructured by the transformation.

In the future, we will probably introduce a unit library capable of
interpreting and manipulating the unit strings, so you can do things
like coregister two images with different units.

Once we have smarter units, we can add CalibratedViews utility methods
that provide additional units-sensitive functionality on top of vanilla
Views. We can also enhance the CombinedRealInterval class (which unions
multiple N-dimensional intervals) to use CalibratedViews.

Lastly, we may also want to consider changing the calibration from a
plain double to a proper typed ImgLib2 NumericType of some sort; but
let's do it only if we have a need for it.

Updating downstream code should be fairly straightforward:

1) 'import net.imglib2.img.ImgPlus' -> 'import net.imglib2.meta.ImgPlus'

   The ImgPlus really belonged in the meta package from the start.

2) Add the imglib2-meta dependency to your project's Maven POM:

   <dependency>
     <groupId>${imglib2.groupId}</groupId>
     <artifactId>imglib2-meta</artifactId>
     <version>${imglib2.version}</version>
   </dependency>

3) 'CalibratedSpace' -> 'OldCalibratedSpace'
   'DefaultCalibratedSpace' -> 'DefaultOldCalibratedSpace'
   'CopyCalibratedSpace' -> 'CopyOldCalibratedSpace'

   Or you can update your code to use the new CalibratedSpace API.

4) 'imgPlus.getAxisIndex' -> 'imgPlus.dimensionIndex'

5) 'imgPlus.calibration(axis)' -> 'imgPlus.axis(axis).calibration()'

Conflicts:
	ij/src/main/java/net/imglib2/img/display/imagej/ImageJFunctions.java
	io/pom.xml
	ops/src/main/java/net/imglib2/ops/operation/metadata/unary/CopyCalibratedSpace.java

algorithms/core/pom.xml

@@ -23,7 +23,7 @@
 		<dependency>
 			<groupId>junit</groupId>
 			<artifactId>junit</artifactId>
-			<version>4.8.1</version>
+			<version>${junit.version}</version>
 			<scope>test</scope>
 		</dependency>
 	</dependencies>

algorithms/gpl/pom.xml

@@ -32,6 +32,11 @@
 			<artifactId>imglib2-algorithms</artifactId>
 			<version>${project.version}</version>
 		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>imglib2-meta</artifactId>
+			<version>${project.version}</version>
+		</dependency>
 
 		<dependency>
 			<!-- TODO: define a real POM for mpicbg project -->
@@ -55,7 +60,7 @@
 		<dependency>
 			<groupId>junit</groupId>
 			<artifactId>junit</artifactId>
-			<version>4.8.1</version>
+			<version>${junit.version}</version>
 			<scope>test</scope>
 		</dependency>
 	</dependencies>

algorithms/gpl/src/main/java/net/imglib2/algorithm/region/localneighborhood/Utils.java

@@ -27,7 +27,8 @@
 package net.imglib2.algorithm.region.localneighborhood;
 
 import net.imglib2.meta.Axes;
-import net.imglib2.meta.Metadata;
+import net.imglib2.meta.CalibratedAxis;
+import net.imglib2.meta.CalibratedSpace;
 import net.imglib2.util.Util;
 
 /**
@@ -38,19 +39,22 @@ public class Utils {
 
 
 	/**
-	 * Return the xyz calibration stored in an {@link Metadata} in a 3-elements
-	 * double array. Calibration is ordered as X, Y, Z. If one axis is not found,
-	 * then the calibration for this axis takes the value of 1.
+	 * Return the xyz calibration stored in a {@link CalibratedSpace} in a
+	 * 3-elements double array. Calibration is ordered as X, Y, Z. If one axis is
+	 * not found, then the calibration for this axis takes the value of 1.
 	 */
-	public static final double[] getSpatialCalibration(final Metadata img) {
+	public static final double[] getSpatialCalibration(
+		final CalibratedSpace<?> space)
+	{
 		final double[] calibration = Util.getArrayFromValue(1d, 3);
-		for (int d = 0; d < img.numDimensions(); d++) {
-			if (img.axis(d).equals(Axes.X)) {
-				calibration[0] = img.calibration(d);
-			} else if (img.axis(d).equals(Axes.Y)) {
-				calibration[1] = img.calibration(d);
-			} else if (img.axis(d).equals(Axes.Z)) {
-				calibration[2] = img.calibration(d);
+		for (int d = 0; d < space.numDimensions(); d++) {
+			final CalibratedAxis axis = space.axis(d);
+			if (axis.type() == Axes.X) {
+				calibration[0] = axis.calibration();
+			} else if (axis.type() == Axes.Y) {
+				calibration[1] = axis.calibration();
+			} else if (axis.type() == Axes.Z) {
+				calibration[2] = axis.calibration();
 			}
 		}
 		return calibration;

algorithms/legacy/pom.xml

@@ -56,7 +56,7 @@
 		<dependency>
 			<groupId>junit</groupId>
 			<artifactId>junit</artifactId>
-			<version>4.8.1</version>
+			<version>${junit.version}</version>
 			<scope>test</scope>
 		</dependency>
 

core/pom.xml

@@ -17,7 +17,7 @@
 		<dependency>
 			<groupId>junit</groupId>
 			<artifactId>junit</artifactId>
-			<version>4.8.1</version>
+			<version>${junit.version}</version>
 			<scope>test</scope>
 		</dependency>
 	</dependencies>

core/src/main/java/net/imglib2/AbstractAnnotatedSpace.java

@@ -0,0 +1,98 @@
+/*
+ * #%L
+ * ImgLib2: a general-purpose, multidimensional image processing library.
+ * %%
+ * Copyright (C) 2009 - 2013 Stephan Preibisch, Tobias Pietzsch, Barry DeZonia,
+ * Stephan Saalfeld, Albert Cardona, Curtis Rueden, Christian Dietz, Jean-Yves
+ * Tinevez, Johannes Schindelin, Lee Kamentsky, Larry Lindsey, Grant Harris,
+ * Mark Hiner, Aivar Grislis, Martin Horn, Nick Perry, Michael Zinsmaier,
+ * Steffen Jaensch, Jan Funke, Mark Longair, and Dimiter Prodanov.
+ * %%
+ * 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.
+ * 
+ * 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.
+ * #L%
+ */
+
+package net.imglib2;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Abstract base class for {@link AnnotatedSpace} implementations.
+ * 
+ * @author Curtis Rueden
+ */
+public abstract class AbstractAnnotatedSpace<A extends Axis> implements
+	AnnotatedSpace<A>
+{
+
+	private final List<A> axisList;
+
+	public AbstractAnnotatedSpace(final int numDims) {
+		axisList = new ArrayList<A>(numDims);
+		// We have no way of knowing the axes to populate, so we fill with nulls.
+		for (int d = 0; d < numDims; d++) {
+			axisList.add(null);
+		}
+	}
+
+	public AbstractAnnotatedSpace(final A... axes) {
+		axisList = Arrays.asList(axes);
+	}
+
+	public AbstractAnnotatedSpace(final List<A> axes) {
+		axisList = new ArrayList<A>(axes.size());
+		axisList.addAll(axes);
+	}
+
+	// -- AnnotatedSpace methods --
+
+	@Override
+	public A axis(final int d) {
+		return axisList.get(d);
+	}
+
+	@Override
+	public void axes(final A[] axes) {
+		for (int d = 0; d < axes.length; d++) {
+			axes[d] = axis(d);
+		}
+	}
+
+	@Override
+	public void setAxis(final A axis, final int d) {
+		axisList.set(d, axis);
+	}
+
+	// -- EuclideanSpace methods --
+
+	@Override
+	public int numDimensions() {
+		return axisList.size();
+	}
+
+}

core/src/main/java/net/imglib2/AnnotatedSpace.java

@@ -0,0 +1,64 @@
+/*
+ * #%L
+ * ImgLib2: a general-purpose, multidimensional image processing library.
+ * %%
+ * Copyright (C) 2009 - 2013 Stephan Preibisch, Tobias Pietzsch, Barry DeZonia,
+ * Stephan Saalfeld, Albert Cardona, Curtis Rueden, Christian Dietz, Jean-Yves
+ * Tinevez, Johannes Schindelin, Lee Kamentsky, Larry Lindsey, Grant Harris,
+ * Mark Hiner, Aivar Grislis, Martin Horn, Nick Perry, Michael Zinsmaier,
+ * Steffen Jaensch, Jan Funke, Mark Longair, and Dimiter Prodanov.
+ * %%
+ * 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.
+ * 
+ * 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.
+ * #L%
+ */
+
+package net.imglib2;
+
+/**
+ * A Euclidean space with associated metadata about each dimension of the space.
+ * The nature of the metadata is left intentionally open-ended; at the topmost
+ * level, the {@link Axis} interface provides no additional information about a
+ * dimensional axis, but it can be extended to do so.
+ * <p>
+ * One potential use of the {@link Axis} objects is to store calibration and
+ * unit information (see the {@code imglib2-meta} project), but any desired
+ * information about the space's dimensions could conceivably be attached.
+ * </p>
+ * 
+ * @author Curtis Rueden
+ */
+public interface AnnotatedSpace<A extends Axis> extends EuclideanSpace {
+
+	/** Gets the axis associated with the given dimension of the space. */
+	A axis(int d);
+
+	/** Copies the space's axes into the given array. */
+	void axes(A[] axes);
+
+	/** Sets the dimensional axis associated with the given dimension. */
+	void setAxis(A axis, int d);
+
+}

core/src/main/java/net/imglib2/Axis.java

@@ -0,0 +1,56 @@
+/*
+ * #%L
+ * ImgLib2: a general-purpose, multidimensional image processing library.
+ * %%
+ * Copyright (C) 2009 - 2013 Stephan Preibisch, Tobias Pietzsch, Barry DeZonia,
+ * Stephan Saalfeld, Albert Cardona, Curtis Rueden, Christian Dietz, Jean-Yves
+ * Tinevez, Johannes Schindelin, Lee Kamentsky, Larry Lindsey, Grant Harris,
+ * Mark Hiner, Aivar Grislis, Martin Horn, Nick Perry, Michael Zinsmaier,
+ * Steffen Jaensch, Jan Funke, Mark Longair, and Dimiter Prodanov.
+ * %%
+ * 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.
+ * 
+ * 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.
+ * #L%
+ */
+
+package net.imglib2;
+
+/**
+ * A dimensional axis of an {@link AnnotatedSpace}.
+ * <p>
+ * This interface does not define any explicit API, but serves as an extension
+ * point for annotated {@link EuclideanSpace}s: subtypes of {@code Axis} can be
+ * defined to include concepts such as axis names, labels and calibrations, and
+ * then assigned to the axes of a {@link AnnotatedSpace}.
+ * </p>
+ * <p>
+ * See the {@code imglib2-meta} project for an example.
+ * </p>
+ * 
+ * @author Curtis Rueden
+ */
+public interface Axis {
+	// NB: Marker interface.
+}

core/src/main/java/net/imglib2/EuclideanSpace.java

@@ -38,10 +38,10 @@
 package net.imglib2;
 
 /**
- *
+ * {R<sup><em>n</em></sup>}: an N-dimensional Euclidean space.
+ * 
  * @author Stephan Preibisch
  * @author Stephan Saalfeld
- * @author Stephan Saalfeld <saalfeld@mpi-cbg.de>
  */
 public interface EuclideanSpace
 {

core/src/main/java/net/imglib2/FinalInterval.java

@@ -47,7 +47,7 @@
 public final class FinalInterval extends AbstractInterval
 {
 	/**
-	 * Creates a {@link AbstractInterval} from another {@link Interval}
+	 * Creates an Interval from another {@link Interval}
 	 *
 	 * @param interval - another {@link Interval}
 	 */

core/src/main/java/net/imglib2/RandomAccessible.java

@@ -50,7 +50,6 @@
  * 
  * @author Stephan Saalfeld
  * @author Tobias Pietzsch
- * @author Stephan Saalfeld <saalfeld@mpi-cbg.de>
  */
 public interface RandomAccessible< T > extends EuclideanSpace
 {

core/src/main/java/net/imglib2/RealRandomAccessible.java

@@ -43,9 +43,12 @@
  * <p>A function over real space that can create a random access
  * {@link Sampler}.</p>
  * 
- *
+ * <p>If your algorithm takes a RealRandomAccessible, this
+ * usually means that you expect that the domain is infinite.
+ * (In contrast to this, {@link RealRandomAccessibleRealInterval}s have a
+ * finite domain.)</p>
+ * 
  * @author Stephan Saalfeld
- * @author Stephan Saalfeld <saalfeld@mpi-cbg.de>
  */
 public interface RealRandomAccessible< T > extends EuclideanSpace
 {

examples/pom.xml

@@ -41,6 +41,11 @@
 			<artifactId>imglib2-io</artifactId>
 			<version>${project.version}</version>
 		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>imglib2-meta</artifactId>
+			<version>${project.version}</version>
+		</dependency>
 		<dependency>
 			<groupId>${project.groupId}</groupId>
 			<artifactId>imglib2-realtransform</artifactId>