Class DBox


  • public class DBox
    extends java.lang.Object
    Version:
    4.8
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static SimpleArrayList<SimpleArrayList<DBox>> freeBoxes
      static store of available boxes, accessible by dimension.
      int[] length
      It specifies for each dimension the length of dbox in that dimension.
      int[] origin
      It specifies point in n-dimensional space where the dbox originates from.
    • Constructor Summary

      Constructors 
      Constructor Description
      DBox​(int dimension)
      constructs a new Box.
      DBox​(int[] origin, int[] length)
      constructs a new Box.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int area()
      It computes the area in 2D case or volume in 3D case.
      static DBox boundingBox​(java.util.Collection<DBox> boxes)
      computes the bounding box of the given collection of boxes
      java.lang.String checkInvariants()
      It checks whether the DBox is consistent.
      boolean containsPoint​(int[] pointCoordinates)
      It checks if this DBox contains the point as specified by an array of coordinates.
      DBox copyInto​(DBox box)
      It copies this DBox into given DBox.
      static void dispatchBox​(DBox unusedBox)
      It allows the system to reuse the given box by placing it into the pool of allocated boxes.
      boolean equals​(java.lang.Object obj)  
      static DBox getAllocatedInstance​(int dimension)
      It returns an instance of DBox of the corresponding dimension, using a previously allocated one if possible
      int hashCode()  
      DBox intersectWith​(int[] offset, DBox other, int[] otherOffset)
      It intersects this DBox with a view of the given DBox that was shifted according to the given offset.
      DBox intersectWith​(DBox other)
      It intersects this DBox with the given DBox.
      DBox intersectWith​(DBox other, int[] otherOffset)
      It intersects this DBox with the given DBox, but the other DBox is shifted by the specified offset.
      static DBox newBox​(int dimension)
      It returns an usable box, reusing a box from the pool if possible.
      static java.lang.String poolStatus()
      It provides a string representation of the DBoxes which are present in the DBox pool.
      java.util.Collection<DBox> subtract​(DBox hole, java.util.Collection<DBox> difference)
      computes the difference between this box and the given box.
      java.util.Collection<DBox> subtractAll​(java.util.Collection<DBox> others, java.util.Collection<DBox> result)
      It computes the result of a subtraction from this box of all the boxes given.
      static java.util.Collection<DBox> subtractAll​(java.util.Collection<DBox> source, java.util.Collection<DBox> holes, java.util.Collection<DBox> result)
      It computes the result of a subtraction from the given collection of boxes of all the boxes given in the subtracting collection.
      static void supportDimension​(int dimension)
      It makes sure that there is a slot of the given dimension in the slot.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • freeBoxes

        public static final SimpleArrayList<SimpleArrayList<DBox>> freeBoxes
        static store of available boxes, accessible by dimension. This makes it possible to reuse previously used boxes that are not used anymore. The user should use dispatchBox() to get rid of a box that is not needed anymore, and newBox(dimension) to get a new one.
      • origin

        public final int[] origin
        It specifies point in n-dimensional space where the dbox originates from.
      • length

        public final int[] length
        It specifies for each dimension the length of dbox in that dimension.
    • Constructor Detail

      • DBox

        public DBox​(int[] origin,
                    int[] length)
        constructs a new Box. The parameter arrays are not copied.
        Parameters:
        origin - it specifies the origin of the DBox in the n-dimensional space.
        length - it specifies the length of the Dbox in the n-dimensional space.
      • DBox

        public DBox​(int dimension)
        constructs a new Box. The parameter arrays are not copied.
        Parameters:
        dimension - it specifies the dimension of the createed DBox.
    • Method Detail

      • supportDimension

        public static final void supportDimension​(int dimension)
        It makes sure that there is a slot of the given dimension in the slot.

        It has to be called at least once before using newBox() and dispatchBox().

        Parameters:
        dimension - the number of dimensions
      • checkInvariants

        public java.lang.String checkInvariants()
        It checks whether the DBox is consistent.
        Returns:
        It returns the string description of the problem, or null if no problem with data structure consistency encountered.
      • dispatchBox

        public static final void dispatchBox​(DBox unusedBox)
        It allows the system to reuse the given box by placing it into the pool of allocated boxes. After calling this function, the caller must not keep any reference to the box, as the box may be arbitrary changed by any future owner.
        Parameters:
        unusedBox - the not used DBox which is being recycled.
      • newBox

        public static final DBox newBox​(int dimension)
        It returns an usable box, reusing a box from the pool if possible. A DBox that is not used anymore should be put back into the pool using dispatchBox.
        Parameters:
        dimension - it specifies number of dimensions of a requested box
        Returns:
        It returns DBox with the specified dimension. Later on, when box is no longer needed it should be dispatched back.
      • getAllocatedInstance

        public static final DBox getAllocatedInstance​(int dimension)
        It returns an instance of DBox of the corresponding dimension, using a previously allocated one if possible
        Parameters:
        dimension - the number of dimensions
        Returns:
        it returns a preallocated DBox of a given dimensions.
      • poolStatus

        public static java.lang.String poolStatus()
        It provides a string representation of the DBoxes which are present in the DBox pool.
        Returns:
        string representation of the pool of DBoxes.
      • containsPoint

        public boolean containsPoint​(int[] pointCoordinates)
        It checks if this DBox contains the point as specified by an array of coordinates.
        Parameters:
        pointCoordinates - it specifies the point coordinates.
        Returns:
        true if the point is inside DBox.
      • intersectWith

        public DBox intersectWith​(DBox other)
        It intersects this DBox with the given DBox.

        For efficiency reasons, the DBox returned is the static instance; if it needs to be stored, a copy has to be made using clone().

        Parameters:
        other - the DBox to intersect this one with
        Returns:
        null if the intersection is empty, or a reference to a static DBox corresponding to the intersection. The result must be cloned if its scope is not local.
      • intersectWith

        public DBox intersectWith​(DBox other,
                                  int[] otherOffset)
        It intersects this DBox with the given DBox, but the other DBox is shifted by the specified offset.

        For efficiency reasons, the DBox returned is the static instance; if it needs to be stored, a copy has to be made using clone().

        Parameters:
        other - DBox with which the intersection is computed.
        otherOffset - the offset
        Returns:
        null if the intersection is empty, or a reference to a static DBox corresponding to the intersection. The result must be cloned if its scope is not local.
      • intersectWith

        public DBox intersectWith​(int[] offset,
                                  DBox other,
                                  int[] otherOffset)
        It intersects this DBox with a view of the given DBox that was shifted according to the given offset. If the intersection is empty, returns null.

        For efficiency reasons, the DBox returned is the static instance; if it needs to be stored, a copy has to be made using clone().

        Parameters:
        offset - the offset to apply to this box before intersecting
        other - the DBox to intersect this one with
        otherOffset - the offset to apply to the other DBox before intersecting
        Returns:
        null if the intersection is empty, or a reference to a static DBox corresponding to the intersection. Clone if its scope is not local.
      • subtract

        public java.util.Collection<DBox> subtract​(DBox hole,
                                                   java.util.Collection<DBox> difference)
        computes the difference between this box and the given box. The difference is returned under the form of a collection of boxes.

        NOTE: the collection of DBoxes returned is not minimal (in some cases, some boxes can be merged)

        if needed, implement a version that can take a lexical order as argument, to allow brute force search or learning of the best decomposition

        Parameters:
        hole - the box to subtract this box with
        difference - the collection of boxes corresponding to the remaining area
        Returns:
        the computed difference, which is the difference paramter after the call (this is for ease of use only)
      • boundingBox

        public static DBox boundingBox​(java.util.Collection<DBox> boxes)
        computes the bounding box of the given collection of boxes
        Parameters:
        boxes - collection of boxes
        Returns:
        a temporary DBox that represents the bounding box of the given boxes. clone it if you need to reuse it.
      • subtractAll

        public static java.util.Collection<DBox> subtractAll​(java.util.Collection<DBox> source,
                                                             java.util.Collection<DBox> holes,
                                                             java.util.Collection<DBox> result)
        It computes the result of a subtraction from the given collection of boxes of all the boxes given in the subtracting collection. The collection used to store the result is given to avoid allocating a new set of boxes each time the function is called. However, for ease of use, it is also returned (after the call, the result argument is equal to the returned value).
        Parameters:
        source - the collection of boxes to subtract from
        holes - the boxes to subtract from the source boxes
        result - the collection to store the resulting boxes into
        Returns:
        the result argument, for ease of use
      • subtractAll

        public java.util.Collection<DBox> subtractAll​(java.util.Collection<DBox> others,
                                                      java.util.Collection<DBox> result)
        It computes the result of a subtraction from this box of all the boxes given. The collection used to store the result is given to avoid allocating a new set of boxes each time the function is called. However, for ease of use, it is also returned (after the call, the result argument is equal to the returned value)
        Parameters:
        others - the boxes to subtract from this box
        result - the collection to store the resulting boxes into
        Returns:
        the result argument, for ease of use
      • area

        public int area()
        It computes the area in 2D case or volume in 3D case.
        Returns:
        the area/volume of the DBox.
      • copyInto

        public final DBox copyInto​(DBox box)
        It copies this DBox into given DBox.
        Parameters:
        box - the DBox to copy this DBox into
        Returns:
        for convenience reasons, returns the copied DBox (same as the argument)
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object