Add int octtrees

This adds octtrees with int coordinates.

Affects #6

com.io7m.jspatial.api/src/main/java/com/io7m/jspatial/api/octtrees/OctTreeConfigurationIType.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright © 2017 <[email protected]> http://io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+package com.io7m.jspatial.api.octtrees;
+
+import com.io7m.jregions.core.unparameterized.volumes.VolumeI;
+import com.io7m.jspatial.api.JSpatialImmutableStyleType;
+import org.immutables.value.Value;
+
+/**
+ * The type of integer octtree configurations.
+ *
+ * @since 3.0.0
+ */
+
+@JSpatialImmutableStyleType
+@Value.Immutable
+public interface OctTreeConfigurationIType
+{
+  /**
+   * @return The maximum bounding volume of the tree
+   */
+
+  @Value.Parameter
+  VolumeI volume();
+
+  /**
+   * @return The minimum width of octants (must be {@code >= 2})
+   */
+
+  @Value.Parameter
+  @Value.Default
+  default int minimumOctantWidth()
+  {
+    return 2;
+  }
+
+  /**
+   * @return The minimum height of octants (must be {@code >= 2})
+   */
+
+  @Value.Parameter
+  @Value.Default
+  default int minimumOctantHeight()
+  {
+    return 2;
+  }
+
+  /**
+   * @return The minimum depth of octants (must be {@code >= 2})
+   */
+
+  @Value.Parameter
+  @Value.Default
+  default int minimumOctantDepth()
+  {
+    return 2;
+  }
+
+  /**
+   * @return {@code true} iff the implementation should attempt to trim empty
+   * leaf nodes when an item is removed
+   */
+
+  @Value.Parameter
+  @Value.Default
+  default boolean trimOnRemove()
+  {
+    return false;
+  }
+}

com.io7m.jspatial.api/src/main/java/com/io7m/jspatial/api/octtrees/OctTreeIType.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright © 2017 <[email protected]> http://io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+package com.io7m.jspatial.api.octtrees;
+
+import com.io7m.jregions.core.unparameterized.volumes.VolumeI;
+
+import java.util.function.BiFunction;
+
+/**
+ * The type of mutable octtrees with {@code int} coordinates.
+ *
+ * @param <A> The precise type of octtree members
+ *
+ * @since 3.0.0
+ */
+
+public interface OctTreeIType<A> extends OctTreeReadableIType<A>
+{
+  /**
+   * <p>Insert the object {@code item} into the octtree.</p>
+   *
+   * <p>The function returns {@code false} if the object could not be
+   * inserted for any reason (perhaps due to being too large).</p>
+   *
+   * <p>If the object is already in the tree, it is replaced. This can be
+   * used to update the bounds of an object within the tree.</p>
+   *
+   * @param item   The object to insert
+   * @param bounds The object's bounds
+   *
+   * @return {@code true} if the object was inserted
+   */
+
+  boolean insert(
+    final A item,
+    final VolumeI bounds);
+
+  /**
+   * <p>Remove the object {@code item} from the octtree.</p>
+   *
+   * <p>The function returns {@code false} if the object could not be
+   * removed for any reason (perhaps due to not being in the tree in the first
+   * place).</p>
+   *
+   * @param item The object to remove
+   *
+   * @return {@code true} if the object was removed
+   */
+
+  boolean remove(
+    A item);
+
+  /**
+   * Remove all objects from the tree.
+   */
+
+  void clear();
+
+  /**
+   * Trim all empty quadrants from the tree.
+   */
+
+  void trim();
+
+  /**
+   * Apply {@code f} to each element of the tree.
+   *
+   * @param f   A mapping function
+   * @param <B> The type of result elements
+   *
+   * @return A new tree
+   */
+
+  @Override
+  <B> OctTreeIType<B> map(BiFunction<A, VolumeI, B> f);
+}

com.io7m.jspatial.api/src/main/java/com/io7m/jspatial/api/octtrees/OctTreeOctantIType.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright © 2017 <[email protected]> http://io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+package com.io7m.jspatial.api.octtrees;
+
+import com.io7m.jregions.core.unparameterized.volumes.VolumeI;
+
+import java.util.Map;
+
+/**
+ * A octant as it appears within the context of an octtree.
+ *
+ * @param <T> The precise type of objects
+ *
+ * @since 3.0.0
+ */
+
+public interface OctTreeOctantIType<T>
+{
+  /**
+   * @return A read-only view of the objects directly contained within this
+   * octant
+   */
+
+  Map<T, VolumeI> objects();
+
+  /**
+   * @return The volume of the octant
+   */
+
+  VolumeI volume();
+}

com.io7m.jspatial.api/src/main/java/com/io7m/jspatial/api/octtrees/OctTreeOctantIterationIType.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright © 2017 <[email protected]> http://io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+package com.io7m.jspatial.api.octtrees;
+
+import com.io7m.jspatial.api.TreeVisitResult;
+
+/**
+ * The type of functions used to iterate over the octants of octtrees.
+ *
+ * @param <A> The type of tree objects
+ * @param <C> The type of contextual values
+ *
+ * @since 3.0.0
+ */
+
+@FunctionalInterface
+public interface OctTreeOctantIterationIType<A, C>
+{
+  /**
+   * Apply the function.
+   *
+   * @param context A context value
+   * @param octant  The current octant
+   * @param depth   The current octant depth
+   *
+   * @return A value indicating how or if the traversal should continue
+   */
+
+  TreeVisitResult apply(
+    C context,
+    OctTreeOctantIType<A> octant,
+    long depth);
+}

com.io7m.jspatial.api/src/main/java/com/io7m/jspatial/api/octtrees/OctTreeRaycastResultIType.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright © 2017 <[email protected]> http://io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+package com.io7m.jspatial.api.octtrees;
+
+import com.io7m.jregions.core.unparameterized.volumes.VolumeI;
+import com.io7m.jspatial.api.JSpatialImmutableStyleType;
+import org.immutables.value.Value;
+
+/**
+ * The type of octtree raycast results.
+ *
+ * @param <T> The precise type of objects
+ *
+ * @since 3.0.0
+ */
+
+@Value.Immutable
+@JSpatialImmutableStyleType
+public interface OctTreeRaycastResultIType<T>
+  extends Comparable<OctTreeRaycastResultIType<T>>
+{
+  @Override
+  default int compareTo(final OctTreeRaycastResultIType<T> o)
+  {
+    return Double.compare(this.distance(), o.distance());
+  }
+
+  /**
+   * @return The distance to the object
+   */
+
+  @Value.Parameter(order = 0)
+  double distance();
+
+  /**
+   * @return The object volume
+   */
+
+  @Value.Parameter(order = 1)
+  VolumeI volume();
+
+  /**
+   * @return The object
+   */
+
+  @Value.Parameter(order = 2)
+  T item();
+}