SpatialDistribution.java

package gdsc.smlm.model;

/*----------------------------------------------------------------------------- 
 * GDSC SMLM Software
 * 
 * Copyright (C) 2013 Alex Herbert
 * Genome Damage and Stability Centre
 * University of Sussex, UK
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *---------------------------------------------------------------------------*/

/**
 * Contains methods for sampling the spatial position of a molecule.
 * <p>
 * The centre of the distribution is [0,0,0]. Therefore the coordinates can be negative or positive.
 */
public interface SpatialDistribution
{
	/**
	 * Get the next position. Note the centre of the distribution is [0,0,0].
	 * <p>
	 * Note: May return null if no more positions are available.
	 * 
	 * @return The next position [x,y,z]
	 */
	double[] next();

	/**
	 * Check if the coordinates are within the distribution bounds
	 * 
	 * @param xyz
	 * @return True if the coordinates are within the distribution bounds
	 */
	boolean isWithin(double[] xyz);

	/**
	 * Check if the coordinates are within the distribution bounds in the XY
	 * dimensions. If the distribution is dependent on the Z-dimension (e.g. 3D
	 * objects) then this can return the same as the {@link #isWithin(double[])} method.
	 * 
	 * @param xyz
	 * @return True if the coordinates are within the distribution bounds in the
	 *         XY dimensions
	 */
	boolean isWithinXY(double[] xyz);

	/**
	 * Initialise the distribution with a set of coordinates. This can be used before calls to
	 * {@link #isWithin(double[])} or {@link #isWithinXY(double[])} if the implementation depends on knowing the original
	 * coordinate location.
	 * 
	 * @param xyz
	 */
	void initialise(double[] xyz);
}