org.bonej.wrapperPlugins.AnisotropyWrapper.java Source code

Java tutorial

Introduction

Here is the source code for org.bonej.wrapperPlugins.AnisotropyWrapper.java

Source

/*
BSD 2-Clause License
Copyright (c) 2018, Michael Doube, Richard Domander, Alessandro Felder
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.
* 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 HOLDER 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.
*/

package org.bonej.wrapperPlugins;

import static java.util.stream.Collectors.toList;
import static java.util.stream.Stream.generate;
import static org.bonej.utilities.AxisUtils.isSpatialCalibrationsIsotropic;
import static org.bonej.wrapperPlugins.CommonMessages.NOT_3D_IMAGE;
import static org.bonej.wrapperPlugins.CommonMessages.NOT_BINARY;
import static org.bonej.wrapperPlugins.CommonMessages.NO_IMAGE_OPEN;
import static org.scijava.ui.DialogPrompt.MessageType.WARNING_MESSAGE;
import static org.scijava.ui.DialogPrompt.OptionType.OK_CANCEL_OPTION;
import static org.scijava.ui.DialogPrompt.Result.OK_OPTION;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Optional;
import java.util.Random;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.function.Function;

import net.imagej.ImgPlus;
import net.imagej.ops.OpService;
import net.imagej.ops.special.function.BinaryFunctionOp;
import net.imagej.ops.special.function.Functions;
import net.imagej.ops.special.function.UnaryFunctionOp;
import net.imagej.ops.stats.regression.leastSquares.Quadric;
import net.imagej.units.UnitService;
import net.imglib2.RandomAccessibleInterval;
import net.imglib2.type.NativeType;
import net.imglib2.type.logic.BitType;
import net.imglib2.type.numeric.RealType;

import org.apache.commons.math3.random.RandomVectorGenerator;
import org.apache.commons.math3.random.UnitSphereRandomVectorGenerator;
import org.bonej.ops.ellipsoid.Ellipsoid;
import org.bonej.ops.ellipsoid.QuadricToEllipsoid;
import org.bonej.ops.mil.MILPlane;
import org.bonej.utilities.AxisUtils;
import org.bonej.utilities.ElementUtil;
import org.bonej.utilities.SharedTable;
import org.bonej.wrapperPlugins.wrapperUtils.Common;
import org.bonej.wrapperPlugins.wrapperUtils.HyperstackUtils;
import org.bonej.wrapperPlugins.wrapperUtils.HyperstackUtils.Subspace;
import org.bonej.wrapperPlugins.wrapperUtils.UsageReporter;
import org.joml.Matrix4d;
import org.joml.Matrix4dc;
import org.joml.Quaterniond;
import org.joml.Quaterniondc;
import org.joml.Vector3d;
import org.scijava.ItemIO;
import org.scijava.ItemVisibility;
import org.scijava.app.StatusService;
import org.scijava.command.Command;
import org.scijava.command.CommandService;
import org.scijava.command.ContextCommand;
import org.scijava.log.LogService;
import org.scijava.plugin.Parameter;
import org.scijava.plugin.Plugin;
import org.scijava.plugin.PluginService;
import org.scijava.prefs.PrefService;
import org.scijava.table.DefaultColumn;
import org.scijava.table.Table;
import org.scijava.ui.DialogPrompt.Result;
import org.scijava.ui.UIService;
import org.scijava.widget.NumberWidget;

/**
 * A command that analyses the degree of anisotropy in an image.
 *
 * @author Richard Domander
 */
@Plugin(type = Command.class, menuPath = "Plugins>BoneJ>Anisotropy")
public class AnisotropyWrapper<T extends RealType<T> & NativeType<T>> extends ContextCommand {

    /**
     * Generates four normally distributed values between [0, 1] that describe a
     * unit quaternion. These can be used to create isotropically distributed
     * rotations.
     */
    private static final RandomVectorGenerator qGenerator = new UnitSphereRandomVectorGenerator(4);

    /**
     * Default directions is 2_000 since that's roughly the number of points in
     * Poisson distributed sampling that'd give points about 5 degrees apart).
     */
    private static final int DEFAULT_DIRECTIONS = 2_000;
    // The default number of lines was found to be sensible after experimenting
    // with data at hand. Other data may need a different number.
    private static final int DEFAULT_LINES = 100;
    private static final double DEFAULT_INCREMENT = 1.0;
    private static BinaryFunctionOp<RandomAccessibleInterval<BitType>, Quaterniondc, Vector3d> milOp;
    private static UnaryFunctionOp<Matrix4dc, Optional<Ellipsoid>> quadricToEllipsoidOp;
    private static UnaryFunctionOp<List<Vector3d>, Matrix4dc> solveQuadricOp;
    private final Function<Ellipsoid, Double> degreeOfAnisotropy = ellipsoid -> 1.0
            - ellipsoid.getA() / ellipsoid.getC();
    @SuppressWarnings("unused")
    @Parameter(validater = "validateImage")
    private ImgPlus<T> inputImage;
    @Parameter(label = "Directions", description = "The number of times sampling is performed from different directions", min = "9", style = NumberWidget.SPINNER_STYLE, required = false, callback = "applyMinimum")
    private Integer directions = DEFAULT_DIRECTIONS;
    @Parameter(label = "Lines per dimension", description = "How many sampling lines are projected in both 2D directions (this number squared)", min = "1", style = NumberWidget.SPINNER_STYLE, required = false, callback = "applyMinimum")
    private Integer lines = DEFAULT_LINES;
    @Parameter(label = "Sampling increment", min = "0.01", description = "Distance between sampling points (in voxels)", style = NumberWidget.SPINNER_STYLE, required = false, stepSize = "0.1", callback = "applyMinimum")
    private Double samplingIncrement = DEFAULT_INCREMENT;
    @Parameter(label = "Recommended minimums", description = "Apply minimum recommended values to directions, lines, and increment", persist = false, required = false, callback = "applyMinimum")
    private boolean recommendedMin;
    @Parameter(visibility = ItemVisibility.MESSAGE)
    private String instruction = "NB parameter values can affect results significantly";
    private boolean calibrationWarned;
    @Parameter(label = "Show radii", description = "Show the radii of the fitted ellipsoid in the results", required = false)
    private boolean printRadii;
    private static Long seed;

    /**
     * The anisotropy results in a {@link Table}.
     * <p>
     * Null if there are no results.
     * </p>
     */
    @Parameter(type = ItemIO.OUTPUT, label = "BoneJ results")
    private Table<DefaultColumn<Double>, Double> resultsTable;
    @Parameter
    private LogService logService;
    @Parameter
    private StatusService statusService;
    @Parameter
    private OpService opService;
    @Parameter
    private UIService uiService;
    @Parameter
    private UnitService unitService;
    @Parameter
    private PrefService prefService;
    @Parameter
    private PluginService pluginService;
    @Parameter
    private CommandService commandService;
    private static UsageReporter reporter;

    @Override
    public void run() {
        statusService.showStatus("Anisotropy: initialising");
        final ImgPlus<BitType> bitImgPlus = Common.toBitTypeImgPlus(opService, inputImage);
        final List<Subspace<BitType>> subspaces = HyperstackUtils.split3DSubspaces(bitImgPlus).collect(toList());
        matchOps(subspaces.get(0));
        final List<Ellipsoid> ellipsoids = new ArrayList<>();
        for (int i = 0; i < subspaces.size(); i++) {
            statusService.showStatus("Anisotropy: sampling subspace #" + (i + 1));
            final Subspace<BitType> subspace = subspaces.get(i);
            final Ellipsoid ellipsoid = milEllipsoid(subspace);
            if (ellipsoid == null) {
                return;
            }
            ellipsoids.add(ellipsoid);
        }
        addResults(subspaces, ellipsoids);
        if (SharedTable.hasData()) {
            resultsTable = SharedTable.getTable();
        }
        if (reporter == null) {
            reporter = UsageReporter.getInstance(prefService, pluginService, commandService);
        }
        reporter.reportEvent(getClass().getName());
    }

    // region -- Helper methods --
    static void setReporter(final UsageReporter reporter) {
        if (reporter == null) {
            throw new NullPointerException("Reporter cannot be null");
        }
        AnisotropyWrapper.reporter = reporter;
    }

    private void addResult(final Subspace<BitType> subspace, final double anisotropy, final Ellipsoid ellipsoid) {
        final String imageName = inputImage.getName();
        final String suffix = subspace.toString();
        final String label = suffix.isEmpty() ? imageName : imageName + " " + suffix;
        SharedTable.add(label, "Degree of anisotropy", anisotropy);
        if (printRadii) {
            SharedTable.add(label, "Radius a", ellipsoid.getA());
            SharedTable.add(label, "Radius b", ellipsoid.getB());
            SharedTable.add(label, "Radius c", ellipsoid.getC());
        }
    }

    private void addResults(final List<Subspace<BitType>> subspaces, final List<Ellipsoid> ellipsoids) {
        statusService.showStatus("Anisotropy: showing results");
        for (int i = 0; i < subspaces.size(); i++) {
            final Subspace<BitType> subspace = subspaces.get(i);
            final Ellipsoid ellipsoid = ellipsoids.get(i);
            final double anisotropy = degreeOfAnisotropy.apply(ellipsoid);
            addResult(subspace, anisotropy, ellipsoid);
        }
    }

    @SuppressWarnings("unused")
    private void applyMinimum() {
        if (recommendedMin) {
            lines = DEFAULT_LINES;
            directions = DEFAULT_DIRECTIONS;
            samplingIncrement = DEFAULT_INCREMENT;
        }
    }

    private Optional<Ellipsoid> fitEllipsoid(final List<Vector3d> pointCloud) {
        statusService.showStatus("Anisotropy: solving quadric equation");
        final Matrix4dc quadric = solveQuadricOp.calculate(pointCloud);
        statusService.showStatus("Anisotropy: fitting ellipsoid");
        return quadricToEllipsoidOp.calculate(quadric);
    }

    @SuppressWarnings("unchecked")
    private void matchOps(final Subspace<BitType> subspace) {
        milOp = Functions.binary(opService, MILPlane.class, Vector3d.class, subspace.interval, new Quaterniond(),
                lines, samplingIncrement);
        final List<Vector3d> tmpPoints = generate(Vector3d::new).limit(Quadric.MIN_DATA).collect(toList());
        solveQuadricOp = Functions.unary(opService, Quadric.class, Matrix4dc.class, tmpPoints);
        final Matrix4dc matchingMock = new Matrix4d();
        quadricToEllipsoidOp = (UnaryFunctionOp) Functions.unary(opService, QuadricToEllipsoid.class,
                Optional.class, matchingMock);
    }

    private Ellipsoid milEllipsoid(final Subspace<BitType> subspace) {
        final List<Vector3d> pointCloud;
        try {
            pointCloud = runDirectionsInParallel(subspace.interval);
            if (pointCloud.size() < Quadric.MIN_DATA) {
                cancel("Anisotropy could not be calculated - too few points");
                return null;
            }
            final Optional<Ellipsoid> ellipsoid = fitEllipsoid(pointCloud);
            if (!ellipsoid.isPresent()) {
                cancel("Anisotropy could not be calculated - ellipsoid fitting failed");
                return null;
            }
            return ellipsoid.get();
        } catch (final ExecutionException | InterruptedException e) {
            logService.trace(e.getMessage());
            cancel("The plug-in was interrupted");
        }
        return null;
    }

    /**
     * Creates a random isotropically distributed quaternion.
     *
     * @return a (rotation) quaternion which can be used as a parameter for the
     *         op.
     */
    private static synchronized Quaterniondc randomQuaternion() {
        final double[] v = qGenerator.nextVector();
        return new Quaterniond(v[0], v[1], v[2], v[3]);
    }

    private List<Vector3d> runDirectionsInParallel(final RandomAccessibleInterval<BitType> interval)
            throws ExecutionException, InterruptedException {
        final int cores = Runtime.getRuntime().availableProcessors();
        // The parallellization of the the MILPlane algorithm is a memory bound
        // problem, which is why speed gains start to drop after 5 cores. With much
        // larger 'nThreads' it slows down due to overhead. Of course '5' here is a
        // bit of a magic number, which might not hold true for all environments,
        // but we need some kind of upper bound
        final int nThreads = Math.max(5, cores);
        final ExecutorService executor = Executors.newFixedThreadPool(nThreads);
        final Callable<Vector3d> milTask = () -> milOp.calculate(interval, randomQuaternion());
        final List<Future<Vector3d>> futures = generate(() -> milTask).limit(directions).map(executor::submit)
                .collect(toList());
        final List<Vector3d> pointCloud = Collections.synchronizedList(new ArrayList<>(directions));
        final int futuresSize = futures.size();
        final AtomicInteger progress = new AtomicInteger();
        for (final Future<Vector3d> future : futures) {
            statusService.showProgress(progress.getAndIncrement(), futuresSize);
            pointCloud.add(future.get());
        }
        shutdownAndAwaitTermination(executor);
        return pointCloud;
    }

    // Shuts down an ExecutorService as per recommended by Oracle
    private void shutdownAndAwaitTermination(final ExecutorService executor) {
        executor.shutdown(); // Disable new tasks from being submitted
        try {
            // Wait a while for existing tasks to terminate
            if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {
                executor.shutdownNow(); // Cancel currently executing tasks
                // Wait a while for tasks to respond to being cancelled
                if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {
                    logService.trace("Pool did not terminate");
                }
            }
        } catch (final InterruptedException ie) {
            // (Re-)Cancel if current thread also interrupted
            executor.shutdownNow();
            // Preserve interrupt status
            Thread.currentThread().interrupt();
            logService.trace(ie);
        }
    }

    @SuppressWarnings("unused")
    private void validateImage() {
        if (inputImage == null) {
            cancel(NO_IMAGE_OPEN);
            return;
        }
        if (AxisUtils.countSpatialDimensions(inputImage) != 3) {
            cancel(NOT_3D_IMAGE);
            return;
        }
        if (!ElementUtil.isBinary(inputImage)) {
            cancel(NOT_BINARY);
            return;
        }
        if (!isSpatialCalibrationsIsotropic(inputImage, 0.01, unitService) && !calibrationWarned) {
            final Result result = uiService.showDialog(
                    "The voxels in the image are anisotropic, which may affect results. Continue anyway?",
                    WARNING_MESSAGE, OK_CANCEL_OPTION);
            // Avoid showing warning more than once (validator gets called before and
            // after dialog pops up..?)
            calibrationWarned = true;
            if (result != OK_OPTION) {
                cancel(null);
            }
        }
    }
    // endregion

    // region -- Utility methods --
    /**
     * Sets the seed used in the random generation of MIL sampling lines.
     * <p>
     * The method's here only to enable reproducible unit test.
     * </p>
     * 
     * @param seed a seed number.
     * @see Random#setSeed
     */
    static void setSeed(final long seed) {
        AnisotropyWrapper.seed = seed;
    }
    // endregion
}