diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml
index 904712e..8e5ac19 100644
--- a/.github/workflows/gradle.yml
+++ b/.github/workflows/gradle.yml
@@ -1,9 +1,5 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-# This workflow will build a Java project with Gradle and cache/restore any dependencies to improve the workflow execution time
-# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-gradle
+# Builds both modules and runs their JUnit tests.
+# The Skript tests (skriptTest) are not run here: the skript-test Gradle plugin is only published to mavenLocal for now.
name: Java CI with Gradle
@@ -12,6 +8,7 @@ on:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
+ workflow_dispatch:
permissions:
contents: read
@@ -23,21 +20,40 @@ jobs:
steps:
- uses: actions/checkout@v6
- - name: Set up JDK 17
+ - name: Set up JDK 25
uses: actions/setup-java@v5
with:
- java-version: '17'
+ java-version: '25'
distribution: 'temurin'
- cache: gradle
+ - name: Set up Gradle
+ uses: gradle/actions/setup-gradle@v4
- name: Grant execute permission for gradlew
- run: chmod +x gradlew
- - name: Build with Gradle
- uses: gradle/gradle-build-action@67421db6bd0bf253fb4bd25b31ebb98943c375e1
+ run: chmod +x gradlew
+ # 'build' runs the JUnit tests of shapes-lib and skript-particle before packaging the plugin
+ - name: Build and test with Gradle
+ run: ./gradlew build
+ # Shows the results on the job's summary page and annotates failing tests. annotate_only skips creating a
+ # separate check run, which would need 'checks: write' (and is unavailable to PRs from forks).
+ - name: Publish test results
+ uses: mikepenz/action-junit-report@v5
+ if: always()
with:
- arguments: build
+ report_paths: '*/build/test-results/test/TEST-*.xml'
+ annotate_only: true
+ detailed_summary: true
+ include_passed: true
+ group_suite: true
+ - name: Upload test reports
+ uses: actions/upload-artifact@v6
+ if: failure()
+ with:
+ name: test-reports
+ path: |
+ */build/reports/tests/test/
+ */build/test-results/test/*.xml
- name: Upload Nightly Build
uses: actions/upload-artifact@v6
if: success()
with:
- name: skript-particle-nightly
- path: build/libs/*
+ name: skript-particle-nightly
+ path: skript-particle/build/libs/*.jar
diff --git a/.gitignore b/.gitignore
index 965fe30..3cd03c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,5 +7,8 @@
/src/test/skriptparticle/
CLAUDE.md
/.claude
-/shapes-lib/build
-/skript-particle/build
+/shapes-lib/build/
+/skript-particle/build/
+/skript-particle/.gradle/
+/net/minecraft/network
+/benchmark
diff --git a/README.md b/README.md
index 72a7bf0..ef95721 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
# skript-particle
Skript addon for creating complex particle effects with minimal hassle.
- **Requires Skript 2.14+, Java 21, Paper 1.21.1+**
+ **Requires Skript 2.16+, Java 21, Paper 1.21.1+**
Download at the [releases page.](https://github.com/sovdeeth/skript-particle/releases)
diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar
index 41d9927..61285a6 100644
Binary files a/gradle/wrapper/gradle-wrapper.jar and b/gradle/wrapper/gradle-wrapper.jar differ
diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
index a595206..325da1a 100644
--- a/gradle/wrapper/gradle-wrapper.properties
+++ b/gradle/wrapper/gradle-wrapper.properties
@@ -1,5 +1,7 @@
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.9.0-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
diff --git a/gradlew b/gradlew
index 1b6c787..adff685 100644
--- a/gradlew
+++ b/gradlew
@@ -1,7 +1,7 @@
#!/bin/sh
#
-# Copyright © 2015-2021 the original authors.
+# Copyright © 2015 the original authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -15,6 +15,8 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
+# SPDX-License-Identifier: Apache-2.0
+#
##############################################################################
#
@@ -55,7 +57,7 @@
# Darwin, MinGW, and NonStop.
#
# (3) This script is generated from the Groovy template
-# https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+# https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
# within the Gradle project.
#
# You can find Gradle at https://github.com/gradle/gradle/.
@@ -80,13 +82,11 @@ do
esac
done
-APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
-
-APP_NAME="Gradle"
+# This is normally unused
+# shellcheck disable=SC2034
APP_BASE_NAME=${0##*/}
-
-# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
# Use the maximum available, or set MAX_FD != -1 to use that value.
MAX_FD=maximum
@@ -114,7 +114,6 @@ case "$( uname )" in #(
NONSTOP* ) nonstop=true ;;
esac
-CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
# Determine the Java command to use to start the JVM.
@@ -133,22 +132,29 @@ location of your Java installation."
fi
else
JAVACMD=java
- which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+ if ! command -v java >/dev/null 2>&1
+ then
+ die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
Please set the JAVA_HOME variable in your environment to match the
location of your Java installation."
+ fi
fi
# Increase the maximum file descriptors if we can.
if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
case $MAX_FD in #(
max*)
+ # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+ # shellcheck disable=SC2039,SC3045
MAX_FD=$( ulimit -H -n ) ||
warn "Could not query maximum file descriptor limit"
esac
case $MAX_FD in #(
'' | soft) :;; #(
*)
+ # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+ # shellcheck disable=SC2039,SC3045
ulimit -n "$MAX_FD" ||
warn "Could not set maximum file descriptor limit to $MAX_FD"
esac
@@ -165,7 +171,6 @@ fi
# For Cygwin or MSYS, switch paths to Windows format before running java
if "$cygwin" || "$msys" ; then
APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
- CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
JAVACMD=$( cygpath --unix "$JAVACMD" )
@@ -193,18 +198,27 @@ if "$cygwin" || "$msys" ; then
done
fi
-# Collect all arguments for the java command;
-# * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
-# shell script including quotes and variable substitutions, so put them in
-# double quotes to make sure that they get re-expanded; and
-# * put everything else in single quotes, so that it's not re-expanded.
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+# * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+# and any embedded shellness will be escaped.
+# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+# treated as '${Hostname}' itself on the command line.
set -- \
"-Dorg.gradle.appname=$APP_BASE_NAME" \
- -classpath "$CLASSPATH" \
- org.gradle.wrapper.GradleWrapperMain \
+ -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
"$@"
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+ die "xargs is not available"
+fi
+
# Use "xargs" to parse quoted args.
#
# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
diff --git a/gradlew.bat b/gradlew.bat
index 27f5d3b..c4bdd3a 100644
--- a/gradlew.bat
+++ b/gradlew.bat
@@ -13,11 +13,13 @@
@rem See the License for the specific language governing permissions and
@rem limitations under the License.
@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
-@if "%DEBUG%" == "" @echo off
+@if "%DEBUG%"=="" @echo off
@rem ##########################################################################
@rem
-@rem Gradle startup script for Windows
+@rem Gradle startup script for Windows
@rem
@rem ##########################################################################
@@ -25,7 +27,8 @@
if "%OS%"=="Windows_NT" setlocal
set DIRNAME=%~dp0
-if "%DIRNAME%" == "" set DIRNAME=.
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
set APP_BASE_NAME=%~n0
set APP_HOME=%DIRNAME%
@@ -40,13 +43,13 @@ if defined JAVA_HOME goto findJavaFromJavaHome
set JAVA_EXE=java.exe
%JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto execute
+if %ERRORLEVEL% equ 0 goto execute
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
goto fail
@@ -56,32 +59,33 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe
if exist "%JAVA_EXE%" goto execute
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
goto fail
:execute
@rem Setup the command line
-set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
@rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %*
:end
@rem End local scope for the variables with windows NT shell
-if "%ERRORLEVEL%"=="0" goto mainEnd
+if %ERRORLEVEL% equ 0 goto mainEnd
:fail
rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
rem the _cmd.exe /c_ return code!
-if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
-exit /b 1
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
:mainEnd
if "%OS%"=="Windows_NT" endlocal
diff --git a/settings.gradle b/settings.gradle
index bd0f6f2..efbd40b 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -1,2 +1,12 @@
+pluginManagement {
+ repositories {
+ mavenLocal()
+ gradlePluginPortal()
+ maven {
+ url 'https://repo.papermc.io/repository/maven-public/'
+ }
+ }
+}
+
rootProject.name = 'skript-particle-root'
include 'shapes-lib', 'skript-particle'
diff --git a/shapes-lib/build.gradle b/shapes-lib/build.gradle
index b5aef52..5afd75b 100644
--- a/shapes-lib/build.gradle
+++ b/shapes-lib/build.gradle
@@ -10,8 +10,15 @@ repositories {
dependencies {
api "org.joml:joml:${jomlVersion}"
+ compileOnly 'org.jetbrains:annotations:24.0.1'
+ testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
+ testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+}
+
+tasks.named('test') {
+ useJUnitPlatform()
}
java {
- toolchain.languageVersion.set(JavaLanguageVersion.of(21))
+ toolchain.languageVersion.set(JavaLanguageVersion.of(25))
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/Easable.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/Easable.java
new file mode 100644
index 0000000..cde3f41
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/Easable.java
@@ -0,0 +1,18 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * Something that has an {@link EasingFunction}.
+ */
+public interface Easable {
+
+ /**
+ * @return the easing function used to distribute rotation along the axis
+ */
+ EasingFunction getEasing();
+
+ /**
+ * @param easing the easing function used to distribute rotation along the axis
+ */
+ void setEasing(EasingFunction easing);
+
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/EasingFunction.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/EasingFunction.java
new file mode 100644
index 0000000..ff4a985
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/EasingFunction.java
@@ -0,0 +1,165 @@
+package com.sovdee.shapes.modifiers;
+
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Maps a normalised value {@code t ∈ [0, 1]} to a (typically) {@code [0, 1]} output, shaping
+ * how interpolation progresses along a modifier's input axis.
+ *
+ * Built-in constants and factory methods cover the most common curves, like {@link #SINE_IN_OUT}.
+ *
+ * Custom implementations must provide a stable {@link #easingHash()} so that modifier cache
+ * invalidation works correctly.
+ */
+public interface EasingFunction {
+
+ /**
+ * Given an input between 0 and 1, applies the easing function and returns a mapped output
+ * @param t Input between 0 and 1.
+ * @return Output value mapped by the easing function.
+ */
+ double apply(double t);
+
+ /**
+ * @return Stable hash of this easing's configuration, used in modifier cache keys.
+ * Two easings that produce identical output for all inputs should return the same value.
+ */
+ int easingHash();
+
+ /**
+ * Controls which end of the interpolation range is eased.
+ *
+ * - {@link #IN} — slow start, fast end (ease into motion)
+ * - {@link #OUT} — fast start, slow end (ease out of motion)
+ * - {@link #IN_OUT} — slow start and slow end (symmetric ease)
+ *
+ */
+ enum Mode {
+ IN,
+ OUT,
+ IN_OUT
+ }
+
+ /**
+ * Power-curve easing: {@code t^n} (in), {@code 1-(1-t)^n} (out),
+ * symmetric combination (in-out).
+ * @param exponent 1 = linear, 2 = quadratic, 3 = cubic, etc.
+ * @param mode Whether to have the start, end, or both be smooth.
+ */
+ record PowerEasing(double exponent, Mode mode) implements EasingFunction {
+ /**
+ * Applies the power-curve easing to {@code t}.
+ *
+ * - IN: {@code t^exponent}
+ * - OUT: {@code 1 - (1-t)^exponent}
+ * - IN_OUT: piecewise symmetric combination of the above
+ *
+ *
+ * @param t normalised input in {@code [0, 1]}
+ * @return eased output value
+ */
+ @Override
+ public double apply(double t) {
+ return switch (mode) {
+ case IN -> Math.pow(t, exponent);
+ case OUT -> 1.0 - Math.pow(1.0 - t, exponent);
+ case IN_OUT -> {
+ if (t < 0.5)
+ yield Math.pow(2.0 * t, exponent) / 2.0;
+ yield 1.0 - Math.pow(-2.0 * t + 2.0, exponent) / 2.0;
+ }
+ };
+ }
+
+ /**
+ * @return a hash combining the exponent and mode ordinal,
+ * unique among all standard {@code PowerEasing} configurations
+ */
+ @Override
+ public int easingHash() {
+ return 31 * Double.hashCode(exponent) + mode.ordinal();
+ }
+ }
+
+ /**
+ * Sine-based easing.
+ * @param mode Whether to have the start, end, or both be smooth.
+ */
+ record SineEasing(Mode mode) implements EasingFunction {
+ /**
+ * Applies the sine-based easing to {@code t}.
+ *
+ * - IN: {@code 1 - cos(t * π/2)}
+ * - OUT: {@code sin(t * π/2)}
+ * - IN_OUT: {@code -(cos(π*t) - 1) / 2}
+ *
+ *
+ * @param t normalised input in {@code [0, 1]}
+ * @return eased output value
+ */
+ @Override
+ public double apply(double t) {
+ return switch (mode) {
+ case IN -> 1.0 - Math.cos(t * Math.PI / 2.0);
+ case OUT -> Math.sin(t * Math.PI / 2.0);
+ case IN_OUT -> -(Math.cos(Math.PI * t) - 1.0) / 2.0;
+ };
+ }
+
+ @Override
+ public int easingHash() {
+ return 1000 + mode.ordinal();
+ }
+ }
+
+ // -------------------------------------------------------------------------
+ // Named constants
+ // -------------------------------------------------------------------------
+
+ EasingFunction LINEAR = new PowerEasing(1.0, Mode.IN);
+
+ EasingFunction QUAD_IN = new PowerEasing(2.0, Mode.IN);
+ EasingFunction QUAD_OUT = new PowerEasing(2.0, Mode.OUT);
+ EasingFunction QUAD_IN_OUT = new PowerEasing(2.0, Mode.IN_OUT);
+
+ EasingFunction CUBIC_IN = new PowerEasing(3.0, Mode.IN);
+ EasingFunction CUBIC_OUT = new PowerEasing(3.0, Mode.OUT);
+ EasingFunction CUBIC_IN_OUT = new PowerEasing(3.0, Mode.IN_OUT);
+
+ EasingFunction SINE_IN = new SineEasing(Mode.IN);
+ EasingFunction SINE_OUT = new SineEasing(Mode.OUT);
+ EasingFunction SINE_IN_OUT = new SineEasing(Mode.IN_OUT);
+
+ // -------------------------------------------------------------------------
+ // Factory methods
+ // -------------------------------------------------------------------------
+
+ /**
+ * @param exponent Degree to use for the easing function
+ * @return A power-based easing function with a gradual start and abrupt end
+ */
+ @Contract("_ -> new")
+ static @NotNull EasingFunction powerIn(double exponent) {
+ return new PowerEasing(exponent, Mode.IN);
+ }
+
+ /**
+ * @param exponent Degree to use for the easing function
+ * @return A power-based easing function with an abrupt start and gradual end
+ */
+ @Contract("_ -> new")
+ static @NotNull EasingFunction powerOut(double exponent) {
+ return new PowerEasing(exponent, Mode.OUT);
+ }
+
+ /**
+ * @param exponent Degree to use for the easing function
+ * @return A power-based easing function with a gradual start and end
+ */
+ @Contract("_ -> new")
+ static @NotNull EasingFunction powerInOut(double exponent) {
+ return new PowerEasing(exponent, Mode.IN_OUT);
+ }
+
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/HasInput.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/HasInput.java
new file mode 100644
index 0000000..4d158d1
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/HasInput.java
@@ -0,0 +1,17 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * A modifier that is driven by a {@link NormalizedInput}.
+ */
+public interface HasInput {
+
+ /**
+ * @return the input that drives this modifier
+ */
+ NormalizedInput getInput();
+
+ /**
+ * @param input the input to drive this modifier with
+ */
+ void setInput(NormalizedInput input);
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/NormalizedInput.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/NormalizedInput.java
new file mode 100644
index 0000000..80ad5ba
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/NormalizedInput.java
@@ -0,0 +1,23 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * A normalized input source for driving per-point modifier computations.
+ * Returns a value in [0, 1] derived from the point's current context.
+ */
+public interface NormalizedInput {
+
+ /**
+ * Returns a value in [0, 1] derived from the point's current context.
+ *
+ * @param point the current point context
+ * @return a value in [0, 1]
+ */
+ double sample(PointContext point);
+
+ /**
+ * Stable hash of this input's identity, for use in {@code modifierHash()}.
+ *
+ * @return a stable integer hash
+ */
+ int inputHash();
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/PointContext.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/PointContext.java
new file mode 100644
index 0000000..c1bac4e
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/PointContext.java
@@ -0,0 +1,82 @@
+package com.sovdee.shapes.modifiers;
+
+import com.sovdee.shapes.shapes.Shape;
+
+/**
+ * Geometry-only context for a single point during modifier and render passes.
+ * A single instance is allocated per draw call and reused across all points.
+ *
+ * Clients that need render-specific properties (color, motion, visibility) should
+ * extend this class and override {@link #reset()} to clear their additional fields.
+ */
+public class PointContext {
+
+ /**
+ * Shape reference.
+ */
+ public Shape shape;
+
+ /**
+ * Local-space position (writable by geometry modifiers).
+ */
+ public double x, y, z;
+
+ /**
+ * 0-based index of this point in the draw order.
+ */
+ public int index;
+
+ /**
+ * Total number of points being drawn this pass.
+ */
+ public int totalPoints;
+
+ /**
+ * Pre-computed bounds for normalization helpers. Set once per pass before the modify loop.
+ */
+ public ShapeBounds bounds;
+
+ // ---- Normalization convenience (delegate to bounds) ----
+
+ /**
+ * @return Normalised X position within shape bounds [0, 1].
+ */
+ public double normalizedX() { return bounds.normalizeX(x); }
+
+ /**
+ * @return Normalised Y position within shape bounds [0, 1].
+ */
+ public double normalizedY() { return bounds.normalizeY(y); }
+
+ /**
+ * @return Normalised Z position within shape bounds [0, 1].
+ */
+ public double normalizedZ() { return bounds.normalizeZ(z); }
+
+ /**
+ * @return Normalised XZ radius [0, 1] relative to max XZ extent.
+ */
+ public double normalizedRadius() { return bounds.normalizeRadial(x, z); }
+
+ /**
+ * @return Normalised 3D distance from the origin [0, 1], relative to the furthest point.
+ */
+ public double normalizedSpherical() {
+ return bounds.normalizeSpherical(x, y, z);
+ }
+
+ /**
+ * @return XZ angle mapped to [0, 1] (0 = +X axis, wraps around).
+ */
+ public double angle() {
+ double a = Math.atan2(z, x);
+ if (a < 0) a += 2 * Math.PI;
+ return a / (2 * Math.PI);
+ }
+
+ /**
+ * Resets mutable (non-geometry) fields between points.
+ * Override in subclasses to clear render-specific properties (color, motion, etc.).
+ */
+ public void reset() {}
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/PointModifier.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/PointModifier.java
new file mode 100644
index 0000000..0bdecf1
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/PointModifier.java
@@ -0,0 +1,78 @@
+package com.sovdee.shapes.modifiers;
+
+import com.sovdee.shapes.sampling.DefaultPointSampler;
+
+/**
+ * Transforms individual points. Geometry modifiers (taper, twist, wave) transform position
+ * in local space before orientation/scale and are cached with shape state.
+ *
+ * Modifiers that can run prior to rendering (geometry-only modifiers) should extends {@link PreRenderPointModifier}
+ */
+public interface PointModifier extends Cloneable {
+
+ /**
+ * Called once per pass before the {@link #modify} loop.
+ * Pre-compute expensive state here (e.g., LUTs, inverse ranges).
+ *
+ * @param bounds the bounding box of the points for this pass
+ */
+ default void prepare(ShapeBounds bounds) {}
+
+ /**
+ * Called per point. Avoid allocations in this method.
+ * Modify the provided context to modify the point/render.
+ *
+ * @param point mutable per-point context, reused. Do not hold references.
+ */
+ void modify(Context point);
+
+ /**
+ * Returns a hash code representing this modifier's current configuration.
+ * Used for cache invalidation in {@link DefaultPointSampler}.
+ */
+ int modifierHash();
+
+ /**
+ * Returns a deep copy of this modifier. The clone must be fully independent:
+ * changes to the clone's configuration must not affect the original.
+ *
+ * @return a new modifier instance with the same configuration
+ */
+ PointModifier clone();
+
+ /**
+ * The minimum context type this modifier requires.
+ * Defaults to {@link PointContext} (compatible with any renderer).
+ * Render modifiers should override this to declare their specific required type,
+ * enabling validation in {@link DefaultPointSampler#render}.
+ */
+ default Class contextType() {
+ return PointContext.class;
+ }
+
+ /**
+ * Marker base class for geometry-only (pre-render) modifiers.
+ * These run during point sampling and are cached with the shape state.
+ * They always operate on plain {@link PointContext}.
+ */
+ abstract class PreRenderPointModifier implements PointModifier {
+
+ /**
+ * Returns a shallow clone of this geometry modifier.
+ * Sufficient for modifiers whose fields are all primitives or immutable objects.
+ *
+ * @return a new {@code PointModifier} instance with the same configuration
+ * @throws RuntimeException wrapping {@link CloneNotSupportedException} if cloning fails
+ */
+ @Override
+ @SuppressWarnings("unchecked")
+ public PointModifier clone() {
+ try {
+ return (PointModifier) super.clone();
+ } catch (CloneNotSupportedException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/RotationPlane.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/RotationPlane.java
new file mode 100644
index 0000000..811bdcf
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/RotationPlane.java
@@ -0,0 +1,21 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * The plane in which a {@link TwistModifier} rotates points.
+ */
+public enum RotationPlane {
+ /**
+ * rotates around the Y axis, acts on X and Z
+ */
+ XZ,
+
+ /**
+ * rotates around the Z axis, acts on X and Y
+ */
+ XY,
+
+ /**
+ * rotates around the X axis, acts on Y and Z
+ */
+ YZ
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ScaleAxes.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ScaleAxes.java
new file mode 100644
index 0000000..9639810
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ScaleAxes.java
@@ -0,0 +1,54 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * Specifies which coordinate axes are scaled by a {@link ScalingModifier}.
+ */
+public enum ScaleAxes {
+ /**
+ * Scales the X axis only.
+ */
+ X (true, false, false),
+
+ /**
+ * Scales the Y axis only.
+ */
+ Y (false, true, false),
+
+ /**
+ * Scales the Z axis only.
+ */
+ Z (false, false, true),
+
+ /**
+ * Scales the X and Y axes.
+ */
+ XY (true, true, false),
+
+ /**
+ * Scales the X and Z axes.
+ */
+ XZ (true, false, true),
+
+ /**
+ * Scales the Y and Z axes.
+ */
+ YZ (false, true, true),
+
+ /**
+ * Scales all three axes.
+ */
+ XYZ (true, true, true);
+
+ /** Whether the X axis is scaled. */
+ public final boolean x;
+ /** Whether the Y axis is scaled. */
+ public final boolean y;
+ /** Whether the Z axis is scaled. */
+ public final boolean z;
+
+ ScaleAxes(boolean x, boolean y, boolean z) {
+ this.x = x;
+ this.y = y;
+ this.z = z;
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ScalingModifier.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ScalingModifier.java
new file mode 100644
index 0000000..c31d8c4
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ScalingModifier.java
@@ -0,0 +1,148 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * Scales any combination of axes by a value that linearly interpolates from
+ * {@code startScale} to {@code endScale} based on a {@link NormalizedInput}.
+ *
+ * Examples:
+ *
+ * - Taper a cylinder along Y: {@code new ScalingModifier(1, 0, StandardInput.Y, ScaleAxes.XZ)}
+ * - Taper inward from radial center: {@code new ScalingModifier(1, 0, StandardInput.RADIUS, ScaleAxes.XYZ)}
+ * - Scale by draw order: {@code new ScalingModifier(0, 1, StandardInput.T, ScaleAxes.XYZ)}
+ *
+ */
+public class ScalingModifier extends PointModifier.PreRenderPointModifier implements HasInput, Easable {
+
+ private double startScale;
+ private double endScale;
+ private NormalizedInput input;
+ private ScaleAxes axes;
+ private EasingFunction easing = EasingFunction.LINEAR;
+
+ /**
+ * Creates a {@code ScalingModifier} that scales the XZ plane driven by the Y axis.
+ *
+ * @param startScale scale factor at input minimum
+ * @param endScale scale factor at input maximum
+ */
+ public ScalingModifier(double startScale, double endScale) {
+ this(startScale, endScale, StandardInput.Y, ScaleAxes.XZ);
+ }
+
+ /**
+ * Creates a {@code ScalingModifier} with a specified input and set of scaled axes.
+ *
+ * @param startScale scale factor at input minimum
+ * @param endScale scale factor at input maximum
+ * @param input the normalized input that drives the scale factor
+ * @param axes which axes to scale
+ */
+ public ScalingModifier(double startScale, double endScale, NormalizedInput input, ScaleAxes axes) {
+ this.startScale = startScale;
+ this.endScale = endScale;
+ this.input = input;
+ this.axes = axes;
+ }
+
+ /**
+ * Scales the configured axes by {@code startScale + easing(t) * (endScale - startScale)},
+ * where {@code t} is sampled from the input.
+ *
+ * @param point the mutable point context to transform
+ */
+ @Override
+ public void modify(PointContext point) {
+ double t = easing.apply(input.sample(point));
+ double scale = startScale + t * (endScale - startScale);
+ if (axes.x) point.x *= scale;
+ if (axes.y) point.y *= scale;
+ if (axes.z) point.z *= scale;
+ }
+
+ /**
+ * {@inheritDoc}
+ * Includes {@code startScale}, {@code endScale}, {@code input}, {@code axes},
+ * and the easing hash.
+ */
+ @Override
+ public int modifierHash() {
+ int result = Double.hashCode(startScale);
+ result = 31 * result + Double.hashCode(endScale);
+ result = 31 * result + input.inputHash();
+ result = 31 * result + axes.ordinal();
+ result = 31 * result + easing.easingHash();
+ return result;
+ }
+
+ /**
+ * @return the scale factor at input minimum
+ */
+ public double getStartScale() {
+ return startScale;
+ }
+
+ /**
+ * @param startScale the scale factor at input minimum
+ */
+ public void setStartScale(double startScale) {
+ this.startScale = startScale;
+ }
+
+ /**
+ * @return the scale factor at input maximum
+ */
+ public double getEndScale() {
+ return endScale;
+ }
+
+ /**
+ * @param endScale the scale factor at input maximum
+ */
+ public void setEndScale(double endScale) {
+ this.endScale = endScale;
+ }
+
+ /**
+ * @return which axes are scaled
+ */
+ public ScaleAxes getAxes() {
+ return axes;
+ }
+
+ /**
+ * @param axes which axes to scale
+ */
+ public void setAxes(ScaleAxes axes) {
+ this.axes = axes;
+ }
+
+ @Override
+ public NormalizedInput getInput() {
+ return input;
+ }
+
+ @Override
+ public void setInput(NormalizedInput input) {
+ this.input = input;
+ }
+
+ @Override
+ public EasingFunction getEasing() {
+ return easing;
+ }
+
+ @Override
+ public void setEasing(EasingFunction easing) {
+ this.easing = easing;
+ }
+
+ /**
+ * Returns a deep copy of this modifier with independent state.
+ *
+ * @return a new {@code ScalingModifier} with the same configuration
+ */
+ @Override
+ public ScalingModifier clone() {
+ return (ScalingModifier) super.clone();
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ShapeBounds.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ShapeBounds.java
new file mode 100644
index 0000000..fa51579
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/ShapeBounds.java
@@ -0,0 +1,211 @@
+package com.sovdee.shapes.modifiers;
+
+import org.joml.Vector3d;
+
+import java.util.List;
+
+/**
+ * Axis-aligned bounding box computed from a set of points.
+ * Provides normalization helpers for use in modifiers and shaders.
+ */
+public final class ShapeBounds {
+
+ private final double minX, minY, minZ;
+ private final double maxX, maxY, maxZ;
+ private final double rangeX, rangeY, rangeZ;
+ private final double maxRadius;
+ private final double maxDistance;
+
+ // Pre-computed inverse ranges for fast normalization (no division in hot loop)
+ private final double invRangeX, invRangeY, invRangeZ, invMaxRadius;
+
+ private ShapeBounds(double minX, double minY, double minZ,
+ double maxX, double maxY, double maxZ,
+ double maxRadius, double maxDistance) {
+ this.minX = minX; this.minY = minY; this.minZ = minZ;
+ this.maxX = maxX; this.maxY = maxY; this.maxZ = maxZ;
+ this.rangeX = maxX - minX;
+ this.rangeY = maxY - minY;
+ this.rangeZ = maxZ - minZ;
+ this.maxRadius = maxRadius;
+ this.maxDistance = maxDistance;
+ this.invRangeX = rangeX > 1e-6 ? 1.0 / rangeX : 0.0;
+ this.invRangeY = rangeY > 1e-6 ? 1.0 / rangeY : 0.0;
+ this.invRangeZ = rangeZ > 1e-6 ? 1.0 / rangeZ : 0.0;
+ this.invMaxRadius = maxRadius > 1e-6 ? 1.0 / maxRadius : 0.0;
+ }
+
+ /**
+ * Computes the bounding box from the given list of points.
+ * Returns a degenerate (all-zero) bounds if the list is empty.
+ */
+ public static ShapeBounds compute(List points) {
+ if (points.isEmpty()) {
+ return new ShapeBounds(0, 0, 0, 0, 0, 0, 0, 0);
+ }
+ double minX = Double.MAX_VALUE, minY = Double.MAX_VALUE, minZ = Double.MAX_VALUE;
+ double maxX = -Double.MAX_VALUE, maxY = -Double.MAX_VALUE, maxZ = -Double.MAX_VALUE;
+ double maxRadius = 0;
+ double maxDistanceSquared = 0;
+ for (Vector3d p : points) {
+ if (p.x < minX) minX = p.x;
+ if (p.y < minY) minY = p.y;
+ if (p.z < minZ) minZ = p.z;
+ if (p.x > maxX) maxX = p.x;
+ if (p.y > maxY) maxY = p.y;
+ if (p.z > maxZ) maxZ = p.z;
+ double r = Math.sqrt(p.x * p.x + p.z * p.z);
+ if (r > maxRadius) maxRadius = r;
+ double distanceSquared = p.x * p.x + p.y * p.y + p.z * p.z;
+ if (distanceSquared > maxDistanceSquared) maxDistanceSquared = distanceSquared;
+ }
+ return new ShapeBounds(minX, minY, minZ, maxX, maxY, maxZ, maxRadius, Math.sqrt(maxDistanceSquared));
+ }
+
+ /**
+ * Normalizes x to [0, 1] within the shape's X extent.
+ */
+ public double normalizeX(double x) {
+ return (x - minX) * invRangeX;
+ }
+
+ /**
+ * Normalizes y to [0, 1] within the shape's Y extent.
+ */
+ public double normalizeY(double y) {
+ return (y - minY) * invRangeY;
+ }
+
+ /**
+ * Normalizes z to [0, 1] within the shape's Z extent.
+ */
+ public double normalizeZ(double z) {
+ return (z - minZ) * invRangeZ;
+ }
+
+ /**
+ * Normalizes the XZ radius to [0, 1] relative to the shape's max XZ radius.
+ */
+ public double normalizeRadial(double x, double z) {
+ return Math.sqrt(x * x + z * z) * invMaxRadius;
+ }
+
+ /**
+ * Returns the max XZ distance from origin across all points.
+ */
+ public double maxRadiusXZ() {
+ return maxRadius;
+ }
+
+ /**
+ * @return the largest distance of any point from the origin, in all three dimensions
+ */
+ public double maxDistance() {
+ return maxDistance;
+ }
+
+ /**
+ * Normalizes a point's distance from the origin to {@code [0, 1]}, where 1 is the furthest point.
+ *
+ * @return the normalized distance, or {@code 0} if every point is at the origin
+ */
+ public double normalizeSpherical(double x, double y, double z) {
+ return maxDistance > 1e-6 ? Math.sqrt(x * x + y * y + z * z) / maxDistance : 0.0;
+ }
+
+ /**
+ * @return the extent of the bounding box along the Y axis ({@code maxY - minY})
+ */
+ public double height() {
+ return rangeY;
+ }
+ /**
+ * @return the extent of the bounding box along the X axis ({@code maxX - minX})
+ */
+ public double width() {
+ return rangeX;
+ }
+ /**
+ * @return the extent of the bounding box along the Z axis ({@code maxZ - minZ})
+ */
+ public double length() {
+ return rangeZ;
+ }
+
+ /**
+ * @return the minimum X coordinate across all points
+ */
+ public double minX() {
+ return minX;
+ }
+ /**
+ * @return the minimum Y coordinate across all points
+ */
+ public double minY() {
+ return minY;
+ }
+ /**
+ * @return the minimum Z coordinate across all points
+ */
+ public double minZ() {
+ return minZ;
+ }
+ /**
+ * @return the maximum X coordinate across all points
+ */
+ public double maxX() {
+ return maxX;
+ }
+ /**
+ * @return the maximum Y coordinate across all points
+ */
+ public double maxY() {
+ return maxY;
+ }
+ /**
+ * @return the maximum Z coordinate across all points
+ */
+ public double maxZ() {
+ return maxZ;
+ }
+
+ /**
+ * Pre-computed reciprocal of the X extent, used for fast normalisation without division.
+ * Returns {@code 0} if the X extent is degenerate (less than {@code 1e-12}).
+ *
+ * @return {@code 1 / rangeX}, or {@code 0} if the range is effectively zero
+ */
+ public double invRangeX() {
+ return invRangeX;
+ }
+
+ /**
+ * Pre-computed reciprocal of the Y extent, used for fast normalisation without division.
+ * Returns {@code 0} if the Y extent is degenerate (less than {@code 1e-12}).
+ *
+ * @return {@code 1 / rangeY}, or {@code 0} if the range is effectively zero
+ */
+ public double invRangeY() {
+ return invRangeY;
+ }
+
+ /**
+ * Pre-computed reciprocal of the Z extent, used for fast normalisation without division.
+ * Returns {@code 0} if the Z extent is degenerate (less than {@code 1e-12}).
+ *
+ * @return {@code 1 / rangeZ}, or {@code 0} if the range is effectively zero
+ */
+ public double invRangeZ() {
+ return invRangeZ;
+ }
+
+ /**
+ * Pre-computed reciprocal of the maximum XZ radius, used for fast radial normalisation.
+ * Returns {@code 0} if the maximum radius is degenerate (less than {@code 1e-12}).
+ *
+ * @return {@code 1 / maxRadius}, or {@code 0} if the radius is effectively zero
+ */
+ public double invMaxRadius() {
+ return invMaxRadius;
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/SpatialAxis.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/SpatialAxis.java
new file mode 100644
index 0000000..b5f72bc
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/SpatialAxis.java
@@ -0,0 +1,22 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * A spatial coordinate axis.
+ * Used to specify the output displacement axis of a {@link WaveModifier}.
+ */
+public enum SpatialAxis {
+ /**
+ * The X axis.
+ */
+ X,
+
+ /**
+ * The Y axis.
+ */
+ Y,
+
+ /**
+ * The Z axis.
+ */
+ Z
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/StandardInput.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/StandardInput.java
new file mode 100644
index 0000000..f53bf6e
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/StandardInput.java
@@ -0,0 +1,71 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * Standard normalized inputs for driving geometry modifiers.
+ * Each constant samples a specific aspect of the point's context,
+ * returning a value in [0, 1].
+ */
+public enum StandardInput implements NormalizedInput {
+ /**
+ * Normalized position within the X extent of the shape's bounds.
+ */
+ X {
+ @Override
+ public double sample(PointContext point) { return point.normalizedX(); }
+ },
+
+ /**
+ * Normalized position within the Y extent of the shape's bounds.
+ */
+ Y {
+ @Override
+ public double sample(PointContext point) { return point.normalizedY(); }
+ },
+
+ /**
+ * Normalized position within the Z extent of the shape's bounds.
+ */
+ Z {
+ @Override
+ public double sample(PointContext point) { return point.normalizedZ(); }
+ },
+
+ /**
+ * Normalized draw order: {@code index / totalPoints}.
+ */
+ T {
+ @Override
+ public double sample(PointContext point) {
+ return point.totalPoints > 0 ? (double) point.index / point.totalPoints : 0.0;
+ }
+ },
+
+ /**
+ * XZ distance from the origin, normalized to the maximum XZ radius.
+ */
+ RADIUS {
+ @Override
+ public double sample(PointContext point) { return point.normalizedRadius(); }
+ },
+
+ /**
+ * 3D distance from the origin, normalized to the maximum XZ radius.
+ */
+ SPHERICAL {
+ @Override
+ public double sample(PointContext point) { return point.normalizedSpherical(); }
+ },
+
+ /**
+ * XZ angle mapped to [0, 1] over a full revolution (0 = +X axis).
+ */
+ ANGLE {
+ @Override
+ public double sample(PointContext point) { return point.angle(); }
+ };
+
+ @Override
+ public int inputHash() {
+ return ordinal();
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/TwistModifier.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/TwistModifier.java
new file mode 100644
index 0000000..df3d75e
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/TwistModifier.java
@@ -0,0 +1,147 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * Rotates each point in the specified {@link RotationPlane} by an angle proportional to
+ * the value of a {@link NormalizedInput}. A {@code totalAngle} of 2π produces one full twist.
+ *
+ * Examples:
+ *
+ * - Classic Y-axis twist: {@code new TwistModifier(2*PI, StandardInput.Y, RotationPlane.XZ)}
+ * - Radial tornado: {@code new TwistModifier(2*PI, StandardInput.RADIUS, RotationPlane.XZ)}
+ * - Draw-order twist: {@code new TwistModifier(PI, StandardInput.T, RotationPlane.XZ)}
+ *
+ */
+public class TwistModifier extends PointModifier.PreRenderPointModifier implements HasInput, Easable {
+
+ private double totalAngle;
+ private NormalizedInput input;
+ private RotationPlane plane;
+ private EasingFunction easing = EasingFunction.LINEAR;
+
+ /**
+ * Creates a {@code TwistModifier} in the XZ plane driven by the Y axis.
+ *
+ * @param totalAngle total rotation in radians; {@code 2π} produces one full revolution
+ */
+ public TwistModifier(double totalAngle) {
+ this(totalAngle, StandardInput.Y, RotationPlane.XZ);
+ }
+
+ /**
+ * Creates a {@code TwistModifier} with a specified input and rotation plane.
+ *
+ * @param totalAngle total rotation in radians; {@code 2π} produces one full revolution
+ * @param input the normalized input that drives the rotation angle
+ * @param plane the plane in which points are rotated
+ */
+ public TwistModifier(double totalAngle, NormalizedInput input, RotationPlane plane) {
+ this.totalAngle = totalAngle;
+ this.input = input;
+ this.plane = plane;
+ }
+
+ /**
+ * Rotates the point in the configured plane by {@code easing(t) * totalAngle} radians,
+ * where {@code t} is sampled from the input.
+ *
+ * @param point the mutable point context to transform
+ */
+ @Override
+ public void modify(PointContext point) {
+ double t = easing.apply(input.sample(point));
+ double angle = totalAngle * t;
+ double cos = Math.cos(angle);
+ double sin = Math.sin(angle);
+ switch (plane) {
+ case YZ -> {
+ double newY = point.y * cos - point.z * sin;
+ double newZ = point.y * sin + point.z * cos;
+ point.y = newY;
+ point.z = newZ;
+ }
+ case XY -> {
+ double newX = point.x * cos - point.y * sin;
+ double newY = point.x * sin + point.y * cos;
+ point.x = newX;
+ point.y = newY;
+ }
+ default -> { // XZ
+ double newX = point.x * cos - point.z * sin;
+ double newZ = point.x * sin + point.z * cos;
+ point.x = newX;
+ point.z = newZ;
+ }
+ }
+ }
+
+ /**
+ * {@inheritDoc}
+ * Includes {@code totalAngle}, {@code input}, {@code plane}, and the easing hash.
+ */
+ @Override
+ public int modifierHash() {
+ int result = Double.hashCode(totalAngle);
+ result = 31 * result + input.inputHash();
+ result = 31 * result + plane.ordinal();
+ result = 31 * result + easing.easingHash();
+ return result;
+ }
+
+ /**
+ * @return the total rotation angle in radians
+ */
+ public double getTotalAngle() {
+ return totalAngle;
+ }
+
+ /**
+ * @param totalAngle the total rotation angle in radians
+ */
+ public void setTotalAngle(double totalAngle) {
+ this.totalAngle = totalAngle;
+ }
+
+ /**
+ * @return the rotation plane
+ */
+ public RotationPlane getPlane() {
+ return plane;
+ }
+
+ /**
+ * @param plane the rotation plane
+ */
+ public void setPlane(RotationPlane plane) {
+ this.plane = plane;
+ }
+
+ @Override
+ public NormalizedInput getInput() {
+ return input;
+ }
+
+ @Override
+ public void setInput(NormalizedInput input) {
+ this.input = input;
+ }
+
+ @Override
+ public EasingFunction getEasing() {
+ return easing;
+ }
+
+ @Override
+ public void setEasing(EasingFunction easing) {
+ this.easing = easing;
+ }
+
+ /**
+ * Returns a deep copy of this modifier with independent state.
+ *
+ * @return a new {@code TwistModifier} with the same configuration
+ */
+ @Override
+ public TwistModifier clone() {
+ return (TwistModifier) super.clone();
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/WaveModifier.java b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/WaveModifier.java
new file mode 100644
index 0000000..d9be7ce
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/modifiers/WaveModifier.java
@@ -0,0 +1,163 @@
+package com.sovdee.shapes.modifiers;
+
+/**
+ * Displaces points by {@code amplitude * sin(2π * frequency * input + phase)},
+ * where input and output are independently configurable.
+ *
+ * {@code frequency} is expressed in cycles over the full [0, 1] input range,
+ * so {@code frequency=1} always means exactly one full sine cycle regardless of
+ * shape size or which input is used.
+ *
+ * Output axis: the coordinate component to displace (X, Y, or Z).
+ * Input: any {@link NormalizedInput} — X, Y, Z, T, RADIUS, SPHERICAL, or ANGLE.
+ */
+public class WaveModifier extends PointModifier.PreRenderPointModifier {
+
+ private double amplitude;
+ private double frequency;
+ private double phase;
+ private NormalizedInput input;
+ private SpatialAxis outputAxis;
+
+ /**
+ * Creates a fully configured wave modifier.
+ *
+ * @param amplitude peak displacement distance (positive or negative)
+ * @param frequency cycles over the full [0, 1] input range; {@code 1} = one full cycle
+ * @param phase phase offset in radians
+ * @param input the normalized input used as the sine function's argument
+ * @param outputAxis the spatial coordinate component to displace
+ */
+ public WaveModifier(double amplitude, double frequency, double phase,
+ NormalizedInput input, SpatialAxis outputAxis) {
+ this.amplitude = amplitude;
+ this.frequency = frequency;
+ this.phase = phase;
+ this.input = input;
+ this.outputAxis = outputAxis;
+ }
+
+ /**
+ * Creates a wave displacing {@code outputAxis} driven by normalized draw order (T),
+ * with a phase of {@code 0}.
+ *
+ * @param amplitude peak displacement distance
+ * @param frequency cycles over the full [0, 1] T range
+ * @param outputAxis the spatial coordinate component to displace
+ */
+ public WaveModifier(double amplitude, double frequency, SpatialAxis outputAxis) {
+ this(amplitude, frequency, 0.0, StandardInput.T, outputAxis);
+ }
+
+ /**
+ * Displaces the point along {@code outputAxis} by
+ * {@code amplitude * sin(2π * frequency * input + phase)},
+ * where {@code input} is sampled from the configured {@link NormalizedInput}.
+ *
+ * @param point the mutable point context to transform
+ */
+ @Override
+ public void modify(PointContext point) {
+ double displacement = amplitude * Math.sin(2 * Math.PI * frequency * input.sample(point) + phase);
+ switch (outputAxis) {
+ case X -> point.x += displacement;
+ case Y -> point.y += displacement;
+ case Z -> point.z += displacement;
+ }
+ }
+
+ /**
+ * {@inheritDoc}
+ * Includes {@code amplitude}, {@code frequency}, {@code phase}, {@code input},
+ * and {@code outputAxis}.
+ */
+ @Override
+ public int modifierHash() {
+ int result = Double.hashCode(amplitude);
+ result = 31 * result + Double.hashCode(frequency);
+ result = 31 * result + Double.hashCode(phase);
+ result = 31 * result + input.inputHash();
+ result = 31 * result + outputAxis.ordinal();
+ return result;
+ }
+
+ /**
+ * @return the peak displacement distance
+ */
+ public double getAmplitude() {
+ return amplitude;
+ }
+
+ /**
+ * @param amplitude the peak displacement distance
+ */
+ public void setAmplitude(double amplitude) {
+ this.amplitude = amplitude;
+ }
+
+ /**
+ * @return the number of cycles over the full [0, 1] input range
+ */
+ public double getFrequency() {
+ return frequency;
+ }
+
+ /**
+ * @param frequency the number of cycles over the full [0, 1] input range
+ */
+ public void setFrequency(double frequency) {
+ this.frequency = frequency;
+ }
+
+ /**
+ * @return the phase offset in radians
+ */
+ public double getPhase() {
+ return phase;
+ }
+
+ /**
+ * @param phase the phase offset in radians
+ */
+ public void setPhase(double phase) {
+ this.phase = phase;
+ }
+
+ /**
+ * @return the normalized input driving the wave
+ */
+ public NormalizedInput getInput() {
+ return input;
+ }
+
+ /**
+ * @param input the normalized input to drive the wave with
+ */
+ public void setInput(NormalizedInput input) {
+ this.input = input;
+ }
+
+ /**
+ * @return the spatial coordinate component that is displaced
+ */
+ public SpatialAxis getOutputAxis() {
+ return outputAxis;
+ }
+
+ /**
+ * @param outputAxis the spatial coordinate component to displace
+ */
+ public void setOutputAxis(SpatialAxis outputAxis) {
+ this.outputAxis = outputAxis;
+ }
+
+ /**
+ * Returns a deep copy of this modifier with independent state.
+ *
+ * @return a new {@code WaveModifier} with the same configuration
+ */
+ @Override
+ public WaveModifier clone() {
+ return (WaveModifier) super.clone();
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DefaultPointSampler.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DefaultPointSampler.java
index cd76bac..0be8ad5 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DefaultPointSampler.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DefaultPointSampler.java
@@ -1,123 +1,682 @@
package com.sovdee.shapes.sampling;
+import com.sovdee.shapes.modifiers.PointContext;
+import com.sovdee.shapes.modifiers.PointModifier;
+import com.sovdee.shapes.modifiers.PointModifier.PreRenderPointModifier;
+import com.sovdee.shapes.modifiers.ShapeBounds;
import com.sovdee.shapes.shapes.Shape;
import org.joml.Quaterniond;
import org.joml.Vector3d;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
import java.util.Comparator;
-import java.util.LinkedHashSet;
-import java.util.Set;
-import java.util.TreeSet;
+import java.util.List;
import java.util.UUID;
/**
- * Default implementation of {@link PointSampler} with hash-based caching.
+ * Default implementation of {@link PointSampler}.
+ *
+ * The last sampled points are cached as an immutable snapshot, which is shared with clones of this sampler
+ * until either side's configuration or shape changes.
*/
public class DefaultPointSampler implements PointSampler {
+ /** The point spacing used when no density has been set explicitly. */
+ public static final double DEFAULT_DENSITY = 0.25;
+
+ /** The point limit of a shape at its default density, until a limit is set. */
+ public static final int DEFAULT_MAX_POINTS = 10_000;
+ /**
+ * The most points any sampling may produce, explicit density or not, and the point limit of a shape with an
+ * explicit density until a limit is set. A density that would exceed it is coarsened just enough to fit,
+ * so a single oversized shape can't exhaust the server's memory.
+ */
+ public static final int HARD_MAX_POINTS = 100_000;
+ /** How many times a sampling may be retried at a coarser density to get under the cap. */
+ private static final int MAX_CAP_ATTEMPTS = 48;
+ /** How many samplings {@link #setParticleCount(Shape, int)} may use to home in on its target. */
+ private static final int MAX_COUNT_REFINEMENTS = 10;
+
private SamplingStyle style = SamplingStyle.OUTLINE;
- private double density = 0.25;
+ private double density = DEFAULT_DENSITY;
+ private int maxPoints = DEFAULT_MAX_POINTS;
+ // until a limit is set, the limit depends on whether the density is explicit
+ private boolean maxPointsExplicit = false;
+ private boolean densityExplicit = false;
private Comparator ordering;
- private final UUID uuid;
+ private volatile UUID uuid;
private DrawContext drawContext;
+ private List> modifiers = new ArrayList<>();
- // Cache
- private Set cachedPoints = new LinkedHashSet<>();
- private CacheState lastState;
- private boolean needsUpdate = false;
+ // Cache: an immutable snapshot, swapped atomically and shared with clones.
+ private volatile Cache cache;
+ /**
+ * Creates a new {@code DefaultPointSampler} with default settings:
+ * {@link SamplingStyle#OUTLINE}, density {@code 0.25}, max points {@code 10 000},
+ * no ordering, no modifiers, and an empty point cache.
+ * The sampler's {@link UUID} is generated when it is first requested.
+ */
public DefaultPointSampler() {
- this.uuid = UUID.randomUUID();
- this.lastState = new CacheState(style, 0, 1.0, 0, density, 0);
}
+
+ /**
+ * Returns sampled points for the given shape using the shape's own orientation.
+ * Results are cached and only recomputed when the shape or sampler state changes.
+ *
+ * @param shape the shape to sample
+ * @return an ordered list of transformed world-space points
+ */
@Override
- public Set getPoints(Shape shape) {
+ public List getPoints(Shape shape) {
return getPoints(shape, shape.getOrientation());
}
+ /**
+ * Returns sampled points for the given shape using the supplied orientation quaternion.
+ * The cache is invalidated when the style, orientation, scale, offset, density,
+ * shape version, or geometry-modifier configuration changes.
+ * Points are transformed (orientation → scale → offset) before being returned.
+ *
+ * @param shape the shape to sample
+ * @param orientation the orientation to apply to the sampled points
+ * @return an ordered list of transformed world-space points
+ */
@Override
- public Set getPoints(Shape shape, Quaterniond orientation) {
- CacheState state = new CacheState(style, orientation.hashCode(),
- shape.getScale(), shape.getOffset().hashCode(), density, shape.getVersion());
- if (shape.isDynamic() || needsUpdate || !state.equals(lastState) || cachedPoints.isEmpty()) {
- Set points = (ordering != null) ? new TreeSet<>(ordering) : new LinkedHashSet<>();
+ public synchronized List getPoints(Shape shape, Quaterniond orientation) {
+ // let the shape pick up any changes to its external inputs before checking the cache
+ shape.refresh();
+
+ int cap = getMaxPoints();
+ CacheState state = new CacheState(style, new Quaterniond(orientation), shape.getScale(), shape.getOffset(),
+ density, densityExplicit, cap, shape.getVersion(), computeModifierHash());
+ Cache cache = this.cache;
+ if (cache != null && cache.state.equals(state))
+ return cache.points;
+
+ // an explicit density is used exactly unless it exceeds the limit; otherwise the density is fitted to the limit
+ Sample sample = densityExplicit
+ ? sampleExplicit(shape, cap)
+ : sampleWithinCap(shape, cap);
+ List points = sample.points;
+
+ applyGeometryModifiers(shape, points);
+
+ // Sorted in local space, so the order turns with the shape. List#sort is stable, so points the ordering
+ // considers equal are all kept in their generated order.
+ if (ordering != null) {
+ points.sort(ordering);
+ }
+
+ double scale = shape.getScale();
+ Vector3d offset = shape.getOffset();
+ for (Vector3d point : points) {
+ orientation.transform(point);
+ point.mul(scale);
+ point.add(offset);
+ }
+
+ List result = Collections.unmodifiableList(points);
+ this.cache = new Cache(state, result, sample.density);
+ return result;
+ }
+
+ /**
+ * Generates the untransformed points of a shape at the given density.
+ *
+ * @param limit the most points that may be generated before a {@link PointLimitExceededException} is thrown
+ */
+ private static List generate(Shape shape, SamplingStyle style, double density, int limit) {
+ List points = new BoundedList(limit);
+ shape.beforeSampling(density);
+ switch (style) {
+ case OUTLINE -> shape.generateOutline(points, density);
+ case SURFACE -> shape.generateSurface(points, density);
+ case FILL -> shape.generateFilled(points, density);
+ }
+ shape.afterSampling(points);
+ return points;
+ }
- shape.beforeSampling(density);
- switch (style) {
- case OUTLINE -> shape.generateOutline(points, density);
- case SURFACE -> shape.generateSurface(points, density);
- case FILL -> shape.generateFilled(points, density);
+ /**
+ * Samples a shape at its explicit density, which is used exactly unless it would produce more than
+ * {@code cap} points. Only then is it coarsened, just enough to fit.
+ */
+ private Sample sampleExplicit(Shape shape, int cap) {
+ try {
+ return new Sample(generate(shape, style, density, cap), density);
+ } catch (PointLimitExceededException e) {
+ return sampleWithinCap(shape, cap);
+ }
+ }
+
+ /**
+ * Samples a shape at the current density, coarsening the density as needed so that no more than
+ * {@code cap} points are produced.
+ */
+ private Sample sampleWithinCap(Shape shape, int cap) {
+ double working = density;
+ // the shape's own estimate is only a starting point: it is never trusted to be finer than the base density.
+ double estimate = shape.computeDensity(style, cap);
+ if (Double.isFinite(estimate) && estimate > working)
+ working = estimate;
+
+ // generating far more points than the cap is wasted work, so stop early and coarsen instead
+ int limit = (int) Math.min((long) cap * 2 + 64, Integer.MAX_VALUE);
+ double dimensions = switch (style) {
+ case OUTLINE -> 1;
+ case SURFACE -> 2;
+ case FILL -> 3;
+ };
+ List points = null;
+ for (int attempt = 0; attempt < MAX_CAP_ATTEMPTS; attempt++) {
+ try {
+ points = generate(shape, style, working, limit);
+ } catch (PointLimitExceededException e) {
+ points = null;
+ working *= 2;
+ continue;
}
- shape.afterSampling(points);
+ if (points.size() <= cap)
+ return new Sample(points, working);
+ // slightly overshoot so shapes that respond as expected land under the cap in one step
+ working *= Math.pow((double) points.size() / cap, 1 / dimensions) * 1.02;
+ }
+ // The shape did not respond to density. Keep what fits rather than exceeding the cap.
+ if (points == null)
+ points = new ArrayList<>();
+ else if (points.size() > cap)
+ points = new ArrayList<>(points.subList(0, cap));
+ return new Sample(points, working);
+ }
- for (Vector3d point : points) {
- orientation.transform(point);
- point.mul(shape.getScale());
- point.add(shape.getOffset());
+ /**
+ * Applies the geometry modifiers in order. Each modifier sees the bounds of the points as the previous
+ * modifiers left them.
+ */
+ @SuppressWarnings("unchecked")
+ private void applyGeometryModifiers(Shape shape, List points) {
+ PointContext ctx = null;
+ for (PointModifier modifier : modifiers) {
+ if (!(modifier instanceof PreRenderPointModifier))
+ continue;
+ PointModifier mod = (PointModifier) modifier;
+ if (ctx == null) {
+ ctx = new PointContext();
+ ctx.shape = shape;
+ ctx.totalPoints = points.size();
+ }
+ ShapeBounds bounds = ShapeBounds.compute(points);
+ ctx.bounds = bounds;
+ mod.prepare(bounds);
+ for (int i = 0; i < points.size(); i++) {
+ Vector3d p = points.get(i);
+ ctx.x = p.x; ctx.y = p.y; ctx.z = p.z;
+ ctx.index = i;
+ mod.modify(ctx);
+ p.x = ctx.x; p.y = ctx.y; p.z = ctx.z;
}
- cachedPoints = points;
- lastState = state;
- needsUpdate = false;
}
- return cachedPoints;
}
+ /**
+ * Returns the density the shape is actually sampled at. This differs from {@link #getDensity()} when the
+ * density had to be coarsened to stay within {@link #getMaxPoints()}.
+ */
+ @Override
+ public synchronized double getEffectiveDensity(Shape shape) {
+ getPoints(shape);
+ Cache cache = this.cache;
+ return cache != null ? cache.density : density;
+ }
+
+ /**
+ * Sets an explicit density so that the shape samples to approximately the given number of points.
+ * Starts from the shape's {@link Shape#computeDensity(SamplingStyle, int) estimate} and corrects it by
+ * measuring how the point count actually responds, so shapes without an exact formula still land close.
+ */
+ @Override
+ public synchronized void setParticleCount(Shape shape, int count) {
+ int target = Math.clamp(count, 1, HARD_MAX_POINTS);
+ shape.refresh();
+
+ // Start no finer than the density currently in use: the first sample then costs no more than drawing the
+ // shape as it is, and every later step towards more points is bounded.
+ double current = getEffectiveDensity(shape);
+ double estimate = shape.computeDensity(style, target);
+ if (Double.isFinite(estimate) && estimate > current)
+ current = estimate;
+
+ int limit = (int) Math.min((long) target * 8 + 1024, Integer.MAX_VALUE);
+ double dimensions = switch (style) {
+ case OUTLINE -> 1;
+ case SURFACE -> 2;
+ case FILL -> 3;
+ };
+ long tolerance = Math.max(1, target / 50);
+ double bestDensity = current;
+ long bestError = Long.MAX_VALUE;
+ double previousDensity = Double.NaN;
+ int previousCount = -1;
+
+ for (int i = 0; i < MAX_COUNT_REFINEMENTS; i++) {
+ int actual;
+ try {
+ actual = generate(shape, style, current, limit).size();
+ } catch (PointLimitExceededException e) {
+ // far too many points: back off and try again
+ previousCount = -1;
+ current *= 2;
+ continue;
+ }
+ long error = Math.abs((long) actual - target);
+ if (error < bestError) {
+ bestError = error;
+ bestDensity = current;
+ }
+ if (error <= tolerance)
+ break;
+
+ // measure how the count scales with density (count ~ density^-dimensions)
+ if (previousCount > 0 && actual > 0 && actual != previousCount && current != previousDensity) {
+ double measured = Math.log((double) previousCount / actual) / Math.log(current / previousDensity);
+ if (Double.isFinite(measured))
+ dimensions = Math.clamp(measured, 1, 3);
+ }
+ previousDensity = current;
+ previousCount = actual;
+
+ double next = current * Math.pow(Math.max(actual, 1) / (double) target, 1 / dimensions);
+ if (actual < target) {
+ // when adding points, never step further than is safe for a 3-dimensional response
+ double safest = current * Math.pow(Math.max(actual, 1) / (target * 4.0), 1 / 3.0);
+ next = Math.max(next, safest);
+ }
+ next = Math.max(next, Shape.EPSILON);
+ if (next == current)
+ break;
+ current = next;
+ }
+ setDensity(bestDensity);
+ }
+
+ /**
+ * Drives the render loop for a shape. Gets cached points, prepares render modifiers,
+ * then calls the renderer for each point.
+ *
+ * @param shape the shape to render
+ * @param orientation the orientation to use for point sampling
+ * @param renderer the client-provided renderer
+ */
+ @Override
+ public void render(Shape shape, Quaterniond orientation, ShapeRenderer renderer) {
+ List points = getPoints(shape, orientation);
+ preparePass(shape, points, renderer.getContext()).renderBatch(points, renderer);
+ }
+
+ /**
+ * Returns the bounds of the given points. When they are this sampler's cached points, the bounds are
+ * computed once and reused for as long as the cache is valid.
+ */
+ @Override
+ public ShapeBounds boundsOf(List points) {
+ Cache cache = this.cache;
+ if (cache != null && cache.points == points)
+ return cache.bounds();
+ return ShapeBounds.compute(points);
+ }
+
+ @Override
+ public RenderPass preparePass(Shape shape, List points, Context context) {
+ // Collect render modifiers (everything that is not a pre-render/geometry modifier)
+ List> renderMods = new ArrayList<>();
+ Class ctxClass = context.getClass();
+ for (PointModifier mod : modifiers) {
+ if (mod instanceof PreRenderPointModifier) continue;
+ if (!mod.contextType().isAssignableFrom(ctxClass)) {
+ throw new IllegalStateException(
+ "Render modifier " + mod.getClass().getSimpleName() +
+ " requires context type " + mod.contextType().getSimpleName() +
+ " but renderer provides " + ctxClass.getSimpleName()
+ );
+ }
+ //noinspection unchecked
+ renderMods.add((PointModifier) mod);
+ }
+
+ // Prepare render modifiers against the full point set
+ ShapeBounds bounds = boundsOf(points);
+ context.bounds = bounds;
+ context.totalPoints = points.size();
+ context.shape = shape;
+ for (PointModifier mod : renderMods) {
+ mod.prepare(bounds);
+ }
+ return new RenderPass<>(context, renderMods);
+ }
+
+ /**
+ * Forces the point cache to be regenerated on the next call to
+ * {@link #getPoints(Shape)} or {@link #getPoints(Shape, Quaterniond)}.
+ * Useful when an external change affects the shape that is not tracked by the cache key.
+ */
public void markDirty() {
- needsUpdate = true;
+ cache = null;
}
+ /**
+ * @return the current sampling style (outline, surface, or fill)
+ */
@Override
- public SamplingStyle getStyle() { return style; }
+ public SamplingStyle getStyle() {
+ return style;
+ }
+ /**
+ * Sets the sampling style and invalidates the point cache.
+ *
+ * @param style the new sampling style
+ */
@Override
public void setStyle(SamplingStyle style) {
this.style = style;
- this.needsUpdate = true;
}
+ /**
+ * Returns the current point spacing density.
+ * This is the base spacing between points. When it has not been set explicitly via {@link #setDensity},
+ * sampling may use a coarser density to stay within {@link #getMaxPoints()};
+ * see {@link #getEffectiveDensity(Shape)}.
+ *
+ * @return the current density value
+ */
@Override
- public double getDensity() { return density; }
+ public double getDensity() {
+ return density;
+ }
+ /**
+ * Sets the point spacing density explicitly, overriding any max-points-based auto-density.
+ * Clamps the value to at least {@code Shape.EPSILON}. Invalidates the point cache.
+ * Sampling still never produces more than {@link #HARD_MAX_POINTS} points; a density that would is coarsened
+ * to fit (see {@link #getEffectiveDensity(Shape)}).
+ *
+ * @param density the desired point spacing; smaller values produce more points
+ */
@Override
public void setDensity(double density) {
this.density = Math.max(density, Shape.EPSILON);
- this.needsUpdate = true;
+ this.densityExplicit = true;
+ }
+
+ /**
+ * Returns the point limit in effect: the limit that was set, or, until one is set,
+ * {@link #DEFAULT_MAX_POINTS} at the default density and {@link #HARD_MAX_POINTS} at an explicit density.
+ */
+ @Override
+ public int getMaxPoints() {
+ if (maxPointsExplicit)
+ return maxPoints;
+ return densityExplicit ? HARD_MAX_POINTS : DEFAULT_MAX_POINTS;
}
+ /**
+ * Sets the point limit, clamped to between {@code 1} and {@link #HARD_MAX_POINTS}. It applies whether or not
+ * the density is explicit, and the density itself is left unchanged.
+ *
+ * @param maxPoints the maximum particle count
+ */
@Override
- public Comparator getOrdering() { return ordering; }
+ public void setMaxPoints(int maxPoints) {
+ this.maxPoints = Math.clamp(maxPoints, 1, HARD_MAX_POINTS);
+ this.maxPointsExplicit = true;
+ }
+
+ @Override
+ public void resetMaxPoints() {
+ this.maxPoints = DEFAULT_MAX_POINTS;
+ this.maxPointsExplicit = false;
+ }
+ /**
+ * Returns to the default density, limited by {@link #getMaxPoints()}.
+ */
+ @Override
+ public void resetDensity() {
+ this.density = DEFAULT_DENSITY;
+ this.densityExplicit = false;
+ }
+
+ /**
+ * Returns whether density was set explicitly via {@link #setDensity}.
+ * When {@code false}, the density is coarsened as needed to stay within {@link #getMaxPoints()}.
+ *
+ * @return {@code true} if density was set explicitly
+ */
+ @Override
+ public boolean isDensityExplicit() {
+ return densityExplicit;
+ }
+
+ /**
+ * @return the comparator used to sort sampled points, or {@code null} for insertion order
+ */
+ @Override
+ public Comparator getOrdering() {
+ return ordering;
+ }
+
+ /**
+ * Sets the comparator used to sort sampled points after generation.
+ * Pass {@code null} to disable sorting. Invalidates the point cache.
+ *
+ * @param ordering a comparator over {@link org.joml.Vector3d}, or {@code null}
+ */
@Override
public void setOrdering(Comparator ordering) {
this.ordering = ordering;
- this.needsUpdate = true;
+ this.cache = null;
}
+ /**
+ * Returns the unique identifier for this sampler instance.
+ * The UUID is generated on first request and never changes afterwards.
+ *
+ * @return the immutable UUID of this sampler
+ */
@Override
- public UUID getUUID() { return uuid; }
+ public UUID getUUID() {
+ UUID id = uuid;
+ if (id == null) {
+ synchronized (this) {
+ id = uuid;
+ if (id == null)
+ uuid = id = UUID.randomUUID();
+ }
+ }
+ return id;
+ }
+ /**
+ * @return the client-provided {@link DrawContext}, or {@code null} if none is set
+ */
@Override
- public DrawContext getDrawContext() { return drawContext; }
+ public DrawContext getDrawContext() {
+ return drawContext;
+ }
+ /**
+ * Sets the client-provided rendering context.
+ *
+ * @param context the {@link DrawContext} to associate with this sampler
+ */
@Override
public void setDrawContext(DrawContext context) { this.drawContext = context; }
+ /**
+ * Returns the live modifier list. Callers should prefer {@link #addModifier},
+ * {@link #removeModifier}, and {@link #clearModifiers} to ensure cache invalidation.
+ *
+ * @return the mutable list of registered modifiers
+ */
+ @Override
+ public List> getModifiers() {
+ return modifiers;
+ }
+
+ /**
+ * Appends a modifier to the end of the modifier list.
+ * Geometry modifiers ({@link PointModifier.PreRenderPointModifier}) additionally
+ * invalidate the point cache.
+ *
+ * @param modifier the modifier to add
+ */
+ @Override
+ public void addModifier(PointModifier modifier) {
+ modifiers.add(modifier);
+ if (modifier instanceof PreRenderPointModifier) cache = null;
+ }
+
+ /**
+ * Removes a modifier from the list if present.
+ * If the removed modifier is a geometry modifier, the point cache is invalidated.
+ *
+ * @param modifier the modifier to remove
+ */
@Override
- public DefaultPointSampler clone() {
+ public void removeModifier(PointModifier modifier) {
+ if (modifiers.remove(modifier)) {
+ if (modifier instanceof PreRenderPointModifier) cache = null;
+ }
+ }
+
+ /**
+ * Removes all modifiers. If any geometry modifier was registered,
+ * the point cache is invalidated.
+ */
+ @Override
+ public void clearModifiers() {
+ if (!modifiers.isEmpty()) {
+ // If any geometry modifier was present, invalidate cache
+ boolean hadGeo = modifiers.stream().anyMatch(m -> m instanceof PreRenderPointModifier);
+ modifiers.clear();
+ if (hadGeo) cache = null;
+ }
+ }
+
+ private int computeModifierHash() {
+ int hash = 1;
+ for (PointModifier mod : modifiers) {
+ if (mod instanceof PreRenderPointModifier) hash = 31 * hash + mod.modifierHash();
+ }
+ return hash;
+ }
+
+ /**
+ * Returns a deep copy of this sampler. The clone has an empty point cache
+ * (forcing a fresh sample on first use) but otherwise copies all configuration,
+ * including a deep-copied modifier list and a copied {@link DrawContext}.
+ * The UUID is not shared: the clone gets its own when it is first requested.
+ *
+ * @return a new {@code DefaultPointSampler} with the same configuration
+ */
+ @Override
+ public synchronized DefaultPointSampler clone() {
try {
DefaultPointSampler copy = (DefaultPointSampler) super.clone();
- // Don't share the cache
- copy.cachedPoints = new LinkedHashSet<>();
- copy.needsUpdate = true;
+ // The copy is its own sampler, but keeps the cached points: they are immutable, and stay valid for
+ // as long as the copy's configuration and shape match the ones they were sampled with.
+ copy.uuid = null;
+ // maxPoints and densityExplicit are primitives — copied by super.clone()
if (drawContext != null)
copy.drawContext = drawContext.copy();
+ // Deep-copy modifiers
+ copy.modifiers = new ArrayList<>(modifiers.size());
+ for (PointModifier mod : modifiers) {
+ copy.modifiers.add(mod.clone());
+ }
return copy;
} catch (CloneNotSupportedException e) {
throw new AssertionError(e);
}
}
- private record CacheState(SamplingStyle style, int orientationHash, double scale,
- int offsetHash, double density, long shapeVersion) {}
+ private record CacheState(SamplingStyle style, Quaterniond orientation, double scale, Vector3d offset,
+ double density, boolean densityExplicit, int maxPoints, long shapeVersion,
+ int modifierHash) {}
+
+ /**
+ * @param density the density the points were actually sampled at
+ */
+ private static final class Cache {
+ final CacheState state;
+ final List points;
+ final double density;
+ // computed on first use; the points never change, so neither do their bounds
+ private volatile ShapeBounds bounds;
+
+ Cache(CacheState state, List points, double density) {
+ this.state = state;
+ this.points = points;
+ this.density = density;
+ }
+
+ ShapeBounds bounds() {
+ ShapeBounds b = bounds;
+ if (b == null)
+ bounds = b = ShapeBounds.compute(points);
+ return b;
+ }
+ }
+
+ private record Sample(List points, double density) {}
+
+ /**
+ * A list that refuses to grow beyond a set size, so that a bad density fails fast instead of exhausting memory.
+ */
+ private static final class BoundedList extends ArrayList {
+
+ private final int limit;
+
+ BoundedList(int limit) {
+ this.limit = limit;
+ }
+
+ @Override
+ public boolean add(Vector3d vector) {
+ if (size() >= limit)
+ throw new PointLimitExceededException(limit);
+ return super.add(vector);
+ }
+
+ @Override
+ public void add(int index, Vector3d vector) {
+ if (size() >= limit)
+ throw new PointLimitExceededException(limit);
+ super.add(index, vector);
+ }
+
+ @Override
+ public boolean addAll(Collection vectors) {
+ if ((long) size() + vectors.size() > limit)
+ throw new PointLimitExceededException(limit);
+ return super.addAll(vectors);
+ }
+
+ @Override
+ public boolean addAll(int index, Collection vectors) {
+ if ((long) size() + vectors.size() > limit)
+ throw new PointLimitExceededException(limit);
+ return super.addAll(index, vectors);
+ }
+
+ @Override
+ public void ensureCapacity(int minCapacity) {
+ // shapes pre-size from rough estimates, which can be wildly off; never reserve beyond the limit
+ super.ensureCapacity(Math.min(minCapacity, limit));
+ }
+ }
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DrawContext.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DrawContext.java
index 19427f0..e20cda8 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DrawContext.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/DrawContext.java
@@ -4,5 +4,12 @@
* Client-provided rendering metadata. Implementations are opaque to the library.
*/
public interface DrawContext {
+ /**
+ * Returns an independent copy of this context.
+ * Used by {@link DefaultPointSampler#clone()} to ensure the cloned sampler
+ * does not share rendering state with the original.
+ *
+ * @return a new {@code DrawContext} with the same configuration
+ */
DrawContext copy();
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointLimitExceededException.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointLimitExceededException.java
new file mode 100644
index 0000000..9dbe9fc
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointLimitExceededException.java
@@ -0,0 +1,21 @@
+package com.sovdee.shapes.sampling;
+
+/**
+ * Thrown when sampling a shape would produce more points than allowed.
+ */
+public class PointLimitExceededException extends RuntimeException {
+
+ private final int limit;
+
+ public PointLimitExceededException(int limit) {
+ super("Sampling this shape would produce more than " + limit + " points.");
+ this.limit = limit;
+ }
+
+ /**
+ * @return the number of points that was exceeded
+ */
+ public int getLimit() {
+ return limit;
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointOrder.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointOrder.java
new file mode 100644
index 0000000..a3ddee9
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointOrder.java
@@ -0,0 +1,61 @@
+package com.sovdee.shapes.sampling;
+
+import com.sovdee.shapes.modifiers.StandardInput;
+import org.joml.Vector3d;
+
+import java.util.Comparator;
+
+/**
+ * Common point orderings for {@link PointSampler#setOrdering(Comparator)}. Points are compared in the shape's
+ * local space, so these follow the shape as it rotates.
+ */
+public final class PointOrder {
+
+ private PointOrder() {}
+
+ /** From lowest to highest {@code x + y + z}: one corner of the shape to the opposite one. */
+ public static final Comparator DIAGONAL = Comparator.comparingDouble(v -> v.x + v.y + v.z);
+
+ /**
+ * A shuffled order that is the same every time a shape is sampled, so animations don't flicker between
+ * different orders. Points at the same position stay in their generated order.
+ */
+ public static final Comparator RANDOM = Comparator.comparingLong(PointOrder::scramble);
+
+ /**
+ * Orders points from where the given input is lowest to where it is highest. Matches the definitions the
+ * modifiers use: x/y/z along their axis, radius as the distance from the y axis, spherical as the distance
+ * from the center, and angle counterclockwise around the y axis starting at +x.
+ *
+ * @throws IllegalArgumentException for {@link StandardInput#T}, which is the draw order itself
+ */
+ public static Comparator along(StandardInput input) {
+ return switch (input) {
+ case X -> Comparator.comparingDouble(v -> v.x);
+ case Y -> Comparator.comparingDouble(v -> v.y);
+ case Z -> Comparator.comparingDouble(v -> v.z);
+ case RADIUS -> Comparator.comparingDouble(v -> v.x * v.x + v.z * v.z);
+ case SPHERICAL -> Comparator.comparingDouble(Vector3d::lengthSquared);
+ case ANGLE -> Comparator.comparingDouble(PointOrder::angle);
+ case T -> throw new IllegalArgumentException("points cannot be ordered by their own draw order");
+ };
+ }
+
+ private static double angle(Vector3d v) {
+ // same as PointContext#angle, before normalising
+ double a = Math.atan2(v.z, v.x);
+ return a < 0 ? a + 2 * Math.PI : a;
+ }
+
+ private static long scramble(Vector3d v) {
+ long h = Double.doubleToLongBits(v.x);
+ h = h * 0x9E3779B97F4A7C15L + Double.doubleToLongBits(v.y);
+ h = h * 0x9E3779B97F4A7C15L + Double.doubleToLongBits(v.z);
+ // splitmix64 finaliser
+ h ^= h >>> 30;
+ h *= 0xBF58476D1CE4E5B9L;
+ h ^= h >>> 27;
+ h *= 0x94D049BB133111EBL;
+ return h ^ (h >>> 31);
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointSampler.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointSampler.java
index 1d7221c..2416bdd 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointSampler.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/PointSampler.java
@@ -1,11 +1,14 @@
package com.sovdee.shapes.sampling;
+import com.sovdee.shapes.modifiers.PointContext;
+import com.sovdee.shapes.modifiers.PointModifier;
+import com.sovdee.shapes.modifiers.ShapeBounds;
import com.sovdee.shapes.shapes.Shape;
import org.joml.Quaterniond;
import org.joml.Vector3d;
import java.util.Comparator;
-import java.util.Set;
+import java.util.List;
import java.util.UUID;
/**
@@ -14,36 +17,206 @@
*/
public interface PointSampler extends Cloneable {
+ /**
+ * @return the current {@link SamplingStyle} (outline, surface, or fill)
+ */
SamplingStyle getStyle();
+
+ /**
+ * Sets the style used when sampling the shape's geometry.
+ *
+ * @param style the new sampling style
+ */
void setStyle(SamplingStyle style);
+ /**
+ * Returns the explicit point spacing density, if one has been set.
+ * When density is not explicit, implementations may coarsen it to stay within {@link #getMaxPoints()}.
+ *
+ * @return the current density value
+ */
double getDensity();
+
+ /**
+ * Sets an explicit point spacing density.
+ * Smaller values produce more points; calling this switches the sampler to explicit-density mode.
+ *
+ * @param density the desired point spacing
+ */
void setDensity(double density);
+ /**
+ * Returns the most points a sampling may currently produce. A shape whose density would produce more is
+ * sampled at a coarser density, just fine enough to stay within this limit.
+ *
+ * @return the point limit in effect
+ */
+ int getMaxPoints();
+
+ /**
+ * Sets the point limit. It applies whether or not the density is explicit, and does not change the density.
+ *
+ * @param maxPoints the maximum particle count
+ */
+ void setMaxPoints(int maxPoints);
+
+ /**
+ * Returns to the implementation's default point limit, which may depend on whether the density is explicit.
+ */
+ void resetMaxPoints();
+
+ /**
+ * Returns whether density was set explicitly via {@link #setDensity}.
+ * When {@code false}, the density is coarsened as needed to stay within {@link #getMaxPoints()}.
+ *
+ * @return {@code true} if density is explicit
+ */
+ boolean isDensityExplicit();
+
+ /**
+ * @return the comparator used to sort sampled points, or {@code null} for insertion order
+ */
Comparator getOrdering();
+
+ /**
+ * Sets the comparator used to sort sampled points after generation. Points are sorted in the shape's local
+ * space (after geometry modifiers, before orientation, scale and offset), so the order rotates with the shape.
+ * See {@link PointOrder} for common orderings.
+ *
+ * @param ordering a comparator over {@link Vector3d}, or {@code null} to disable sorting
+ */
void setOrdering(Comparator ordering);
+ /**
+ * Returns the unique identifier assigned to this sampler at construction time.
+ *
+ * @return the immutable UUID of this sampler
+ */
UUID getUUID();
+ /**
+ * @return the client-provided {@link DrawContext}, or {@code null} if none is set
+ */
DrawContext getDrawContext();
+
+ /**
+ * Associates a client-provided rendering context with this sampler.
+ *
+ * @param context the {@link DrawContext} to use during rendering
+ */
void setDrawContext(DrawContext context);
+ /**
+ * Returns to the implementation's default density, limited by {@link #getMaxPoints()}.
+ */
+ void resetDensity();
+
+ /**
+ * Returns the density the given shape is actually sampled at, which may be coarser than
+ * {@link #getDensity()} when the density is not explicit.
+ */
+ default double getEffectiveDensity(Shape shape) {
+ return getDensity();
+ }
+
+ /**
+ * @return the number of points the given shape currently samples to
+ */
+ default int getPointCount(Shape shape) {
+ return getPoints(shape).size();
+ }
+
/**
* Samples points from the given shape using the shape's own orientation.
+ * The returned list is unmodifiable and may be cached and shared: callers must not modify its vectors.
*/
- Set getPoints(Shape shape);
+ List getPoints(Shape shape);
/**
* Samples points from the given shape using the given orientation.
+ * The returned list is unmodifiable and may be cached and shared: callers must not modify its vectors.
*/
- Set getPoints(Shape shape, Quaterniond orientation);
+ List getPoints(Shape shape, Quaterniond orientation);
/**
* Computes and sets the density to achieve approximately the given particle count.
*/
default void setParticleCount(Shape shape, int count) {
- setDensity(shape.computeDensity(getStyle(), count));
+ double density = shape.computeDensity(getStyle(), Math.max(count, 1));
+ // an estimate of zero or less would mean an unbounded number of points
+ if (Double.isFinite(density) && density > Shape.EPSILON)
+ setDensity(density);
}
+ // ---- Modifier management ----
+
+ /**
+ * Returns the list of registered {@link PointModifier}s.
+ * Geometry modifiers are applied during point sampling; render modifiers are applied per frame.
+ *
+ * @return the mutable modifier list
+ */
+ List> getModifiers();
+
+ /**
+ * Appends a modifier to the modifier list.
+ * Geometry modifiers may additionally invalidate the point cache.
+ *
+ * @param modifier the modifier to add
+ */
+ void addModifier(PointModifier modifier);
+
+ /**
+ * Removes a modifier from the list if present.
+ * Geometry modifiers may additionally invalidate the point cache.
+ *
+ * @param modifier the modifier to remove
+ */
+ void removeModifier(PointModifier modifier);
+
+ /**
+ * Removes all modifiers from the list.
+ * Geometry modifiers may additionally invalidate the point cache.
+ */
+ void clearModifiers();
+
+ /**
+ * Drives the full render loop: gets cached points, runs render modifiers, calls renderer.
+ *
+ * @param shape the shape to render
+ * @param orientation the orientation for point sampling
+ * @param renderer client-provided renderer
+ */
+ void render(Shape shape, Quaterniond orientation, ShapeRenderer renderer);
+
+ /**
+ * Returns the bounds of a point list, typically one returned by {@link #getPoints}.
+ * Implementations may cache the bounds of their own cached points; the default computes them.
+ *
+ * @param points the points to bound
+ * @return the bounds of the points
+ */
+ default ShapeBounds boundsOf(List points) {
+ return ShapeBounds.compute(points);
+ }
+
+ /**
+ * Collects and prepares this sampler's render modifiers against the given (already sampled)
+ * point set, returning a {@link RenderPass} that can render the points in one or more
+ * sequential batches with a continuous point index. Used by clients that spread rendering
+ * over multiple ticks (e.g. animated draws); {@link #render} is the single-batch shortcut.
+ *
+ * @param shape the shape being rendered
+ * @param points the full, ordered point set for this pass
+ * @param context the renderer's context; its bounds/totalPoints/shape fields are populated
+ */
+ RenderPass preparePass(Shape shape, List points, Context context);
+
+ /**
+ * Returns a deep copy of this sampler with the same configuration.
+ * The clone must be fully independent from the original.
+ *
+ * @return a new sampler instance
+ */
PointSampler clone();
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/RenderPass.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/RenderPass.java
new file mode 100644
index 0000000..b9de5f8
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/RenderPass.java
@@ -0,0 +1,54 @@
+package com.sovdee.shapes.sampling;
+
+import com.sovdee.shapes.modifiers.PointContext;
+import com.sovdee.shapes.modifiers.PointModifier;
+import org.joml.Vector3d;
+
+import java.util.List;
+
+/**
+ * A prepared render pass over a shape's points. Created by
+ * {@link PointSampler#preparePass(com.sovdee.shapes.shapes.Shape, List, PointContext)} after
+ * render modifiers have been collected, validated, and prepared against the full point set.
+ *
+ * Points may then be rendered in one or more sequential batches via {@link #renderBatch};
+ * the pass keeps a running point index so that {@link PointContext#index} (and anything
+ * derived from it, such as normalized draw order) stays continuous across batches.
+ * A pass is single-use and not thread-safe; batches must be rendered in order.
+ */
+public final class RenderPass {
+
+ private final Context context;
+ private final List> renderModifiers;
+ private int nextIndex = 0;
+
+ RenderPass(Context context, List> renderModifiers) {
+ this.context = context;
+ this.renderModifiers = renderModifiers;
+ }
+
+ /**
+ * Runs the render loop over one batch of points: for each point the context is reset,
+ * populated, passed through every render modifier, and handed to the renderer.
+ * {@link ShapeRenderer#begin} and {@link ShapeRenderer#end} are called around the batch.
+ *
+ * @param batch the points to render, in draw order
+ * @param renderer the renderer to send points to; must be the renderer whose context
+ * this pass was prepared with
+ */
+ public void renderBatch(List batch, ShapeRenderer renderer) {
+ renderer.begin(batch.size());
+ for (Vector3d p : batch) {
+ context.reset();
+ context.x = p.x;
+ context.y = p.y;
+ context.z = p.z;
+ context.index = nextIndex++;
+ for (PointModifier mod : renderModifiers) {
+ mod.modify(context);
+ }
+ renderer.renderPoint(context);
+ }
+ renderer.end();
+ }
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/SamplingStyle.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/SamplingStyle.java
index d65ef9b..ba198d4 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/SamplingStyle.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/SamplingStyle.java
@@ -8,6 +8,11 @@ public enum SamplingStyle {
SURFACE,
FILL;
+ /**
+ * Returns a lowercase string representation of this style, e.g. {@code "outline"}.
+ *
+ * @return the lowercase enum name
+ */
@Override
public String toString() {
return name().toLowerCase();
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/sampling/ShapeRenderer.java b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/ShapeRenderer.java
new file mode 100644
index 0000000..aa0b9cf
--- /dev/null
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/sampling/ShapeRenderer.java
@@ -0,0 +1,38 @@
+package com.sovdee.shapes.sampling;
+
+import com.sovdee.shapes.modifiers.PointContext;
+
+/**
+ * Client-implemented interface for rendering shape points.
+ * The library drives the render loop; the client handles the actual output (e.g. NMS packets).
+ *
+ * Implementations may cast the {@link PointContext} to their own subclass (e.g. {@code RenderContext})
+ * to read render-specific properties written by render modifiers.
+ */
+public interface ShapeRenderer {
+
+ /**
+ * Called once before the point loop. Use to allocate buffers, pre-compute shared state, etc.
+ *
+ * @param totalPoints the number of points that will be rendered
+ */
+ void begin(int totalPoints);
+
+ /**
+ * Called for each point after all render modifiers have been applied.
+ * Should be allocation-free.
+ *
+ * @param point the mutable per-point context; cast to your subclass to access render properties
+ */
+ void renderPoint(Context point);
+
+ /**
+ * @return Returns the context this renderer uses.
+ */
+ Context getContext();
+
+ /**
+ * Called after all points have been rendered. Flush buffers, send remaining packets, etc.
+ */
+ void end();
+}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/AbstractShape.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/AbstractShape.java
index 1ba1478..cc4af3a 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/AbstractShape.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/AbstractShape.java
@@ -6,8 +6,7 @@
import org.joml.Quaterniond;
import org.joml.Vector3d;
-import java.util.LinkedHashSet;
-import java.util.Set;
+import java.util.List;
/**
* Base implementation of {@link Shape} providing spatial transform, versioning,
@@ -17,11 +16,16 @@ public abstract class AbstractShape implements Shape {
private final Quaterniond orientation;
private double scale;
- private Vector3d offset;
+ private final Vector3d offset;
private boolean dynamic = false;
private long version = 0;
private PointSampler pointSampler;
+ /**
+ * Initialises a new shape with an identity orientation, scale {@code 1.0}, zero offset,
+ * and a fresh {@link DefaultPointSampler}. Subclasses must call {@code super()} before
+ * setting dimension-specific fields.
+ */
public AbstractShape() {
this.orientation = new Quaterniond();
this.scale = 1;
@@ -31,46 +35,80 @@ public AbstractShape() {
// --- Spatial transform ---
+ /**
+ * {@inheritDoc}
+ * Returns a defensive copy so callers cannot mutate the internal quaternion.
+ */
@Override
public Quaterniond getOrientation() {
return new Quaterniond(orientation);
}
+ /**
+ * {@inheritDoc}
+ * The value is copied into the internal quaternion; the argument is not retained.
+ */
@Override
public void setOrientation(Quaterniond orientation) {
this.orientation.set(orientation);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public double getScale() { return scale; }
+ /**
+ * {@inheritDoc}
+ */
@Override
public void setScale(double scale) {
this.scale = scale;
}
+ /**
+ * {@inheritDoc}
+ * Returns a defensive copy so callers cannot mutate the internal offset.
+ */
@Override
public Vector3d getOffset() {
return new Vector3d(offset);
}
+ /**
+ * {@inheritDoc}
+ * The provided vector is stored directly (not copied); callers should not mutate it afterward.
+ */
@Override
public void setOffset(Vector3d offset) {
- this.offset = offset;
+ this.offset.set(offset);
}
// --- Oriented axes ---
+ /**
+ * {@inheritDoc}
+ * Computed by rotating {@code (1, 0, 0)} with the internal orientation quaternion.
+ */
@Override
public Vector3d getRelativeXAxis() {
return orientation.transform(new Vector3d(1, 0, 0));
}
+ /**
+ * {@inheritDoc}
+ * Computed by rotating {@code (0, 1, 0)} with the internal orientation quaternion.
+ */
@Override
public Vector3d getRelativeYAxis() {
return orientation.transform(new Vector3d(0, 1, 0));
}
+ /**
+ * {@inheritDoc}
+ * Computed by rotating {@code (0, 0, 1)} with the internal orientation quaternion.
+ */
@Override
public Vector3d getRelativeZAxis() {
return orientation.transform(new Vector3d(0, 0, 1));
@@ -78,6 +116,10 @@ public Vector3d getRelativeZAxis() {
// --- Change detection ---
+ /**
+ * {@inheritDoc}
+ * The counter starts at {@code 0} and is incremented each time {@link #invalidate()} is called.
+ */
@Override
public long getVersion() { return version; }
@@ -91,24 +133,55 @@ protected void invalidate() {
// --- Dynamic support ---
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean isDynamic() { return dynamic; }
+ /**
+ * {@inheritDoc}
+ */
@Override
public void setDynamic(boolean dynamic) { this.dynamic = dynamic; }
// --- Point generation defaults ---
+ /**
+ * Default surface implementation that delegates to {@link #generateOutline(List, double)}.
+ * Subclasses with a meaningful surface representation (e.g. {@link Circle}, {@link Sphere})
+ * should override this method.
+ *
+ * @param points the list to append generated points to; must not be null
+ * @param density the desired spacing between points
+ */
@Override
- public void generateSurface(Set points, double density) {
+ public void generateSurface(List points, double density) {
generateOutline(points, density);
}
+ /**
+ * Default filled implementation that delegates to {@link #generateSurface(List, double)}.
+ * Subclasses that can meaningfully fill their volume (e.g. {@link Circle}, {@link Sphere})
+ * should override this method.
+ *
+ * @param points the list to append generated points to; must not be null
+ * @param density the desired spacing between points
+ */
@Override
- public void generateFilled(Set points, double density) {
+ public void generateFilled(List points, double density) {
generateSurface(points, density);
}
+ /**
+ * Generic fallback implementation that always returns a density of {@code 0.25}.
+ * Subclasses should override this with a formula appropriate to their geometry so that
+ * {@link PointSampler#setParticleCount(Shape, int)} produces accurate results.
+ *
+ * @param style the {@link SamplingStyle} being used (OUTLINE, SURFACE, or FILL)
+ * @param targetPointCount the desired number of points
+ * @return {@code 0.25} as a safe, conservative default
+ */
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
// Generic fallback — subclasses should override for accuracy
@@ -117,34 +190,129 @@ public double computeDensity(SamplingStyle style, int targetPointCount) {
// --- Geometry query ---
+ /**
+ * {@inheritDoc}
+ */
@Override
- public abstract boolean contains(Vector3d point);
+ public boolean contains(Vector3d point) {
+ return contains(point, EPSILON);
+ }
+
+ /**
+ * Returns {@code true} if the given point lies within the volume of this shape, grown by {@code tolerance}.
+ * For shapes with no volume of their own (curves and flat shapes), the tolerance is how thick they are
+ * treated as being.
+ *
+ * @param point the point to test, in the same space as the sampled points
+ * @param tolerance how far outside the exact shape still counts as contained, in the shape's local units
+ * @return {@code true} if the point is contained by this shape
+ */
+ public boolean contains(Vector3d point, double tolerance) {
+ if (scale == 0)
+ return false;
+ refresh();
+ // undo the transform the sampler applies: orientation, then scale, then offset
+ Vector3d local = new Vector3d(point).sub(offset).div(scale);
+ orientation.transformInverse(local);
+ return containsLocal(local, Math.max(tolerance, 0));
+ }
+
+ /**
+ * Tests a point in this shape's local space, before orientation, scale and offset are applied.
+ * Concrete subclasses implement the containment test appropriate to their geometry.
+ *
+ * @param point the point to test, in local coordinates. Implementations may modify it.
+ * @param tolerance a non-negative distance outside the exact shape that still counts as contained
+ * @return {@code true} if the point is contained by this shape
+ */
+ protected abstract boolean containsLocal(Vector3d point, double tolerance);
// --- PointSampler ---
+ /**
+ * {@inheritDoc}
+ */
@Override
public PointSampler getPointSampler() { return pointSampler; }
+ /**
+ * {@inheritDoc}
+ */
@Override
public void setPointSampler(PointSampler sampler) { this.pointSampler = sampler; }
// --- Vertical fill helper ---
- protected static void fillVertically(Set points, double height, double density) {
- Set base = new LinkedHashSet<>(points);
- double heightStep = height / Math.round(height / density);
- for (double y = 0; y < height; y += heightStep) {
- for (Vector3d v : base) {
- points.add(new Vector3d(v.x, y, v.z));
+ /**
+ * Duplicates an existing slice of {@code points} at successive Y offsets to fill a vertical
+ * column of the given {@code height}. The Y step is derived from {@code density} so that
+ * layer spacing is as uniform as possible.
+ *
+ * The method reads all points in the range {@code [startIndex, points.size())} at the time
+ * of the call and appends copies of them in evenly spaced layers, up to and including {@code height}.
+ *
+ * @param points the list of points to extend; the existing slice is treated as the base layer
+ * @param startIndex the index of the first point in the base layer
+ * @param height the total vertical extent to fill; must be positive
+ * @param density the desired spacing between vertical layers
+ */
+ protected static void fillVertically(List points, int startIndex, double height, double density) {
+ fillVertically(points, startIndex, height, density, true);
+ }
+
+ /**
+ * Duplicates an existing slice of {@code points} in evenly spaced layers along the y-axis.
+ * The existing slice is the base layer and is not duplicated.
+ *
+ * @param points the list of points to extend
+ * @param startIndex the index of the first point in the base layer
+ * @param height the total vertical extent to fill; must be positive
+ * @param density the desired spacing between vertical layers
+ * @param includeTop whether to add a layer at exactly {@code height}. Pass {@code false} when the top
+ * is generated separately, to avoid duplicate points.
+ */
+ protected static void fillVertically(List points, int startIndex, double height, double density, boolean includeTop) {
+ int end = points.size();
+ int layers = segments(height, density);
+ int last = includeTop ? layers : layers - 1;
+ for (int layer = 1; layer <= last; layer++) {
+ double y = height * layer / layers;
+ for (int i = startIndex; i < end; i++) {
+ Vector3d v = points.get(i);
+ points.add(new Vector3d(v.x, v.y + y, v.z));
}
}
}
+ /**
+ * Returns how many segments of roughly {@code density} length fit into {@code length}.
+ * Always at least 1, so that dividing a length by the result is safe.
+ */
+ protected static int segments(double length, double density) {
+ double count = Math.round(Math.abs(length) / density);
+ if (!(count >= 1)) // also covers NaN
+ return 1;
+ return (int) Math.min(count, Integer.MAX_VALUE - 1);
+ }
+
// --- Replication ---
+ /**
+ * {@inheritDoc}
+ * Concrete subclasses must create a new instance with the same dimension-specific state and
+ * then call {@link #copyTo(Shape)} to propagate the base transform fields.
+ */
@Override
public abstract Shape clone();
+ /**
+ * {@inheritDoc}
+ * Copies orientation, scale, offset, dynamic flag, and a clone of the point sampler into
+ * {@code shape}. Dimension-specific fields are not touched.
+ *
+ * @param shape the target shape; must not be null
+ * @return {@code shape}, for chaining convenience
+ */
@Override
public Shape copyTo(Shape shape) {
shape.setOrientation(new Quaterniond(this.orientation));
@@ -152,14 +320,11 @@ public Shape copyTo(Shape shape) {
shape.setOffset(new Vector3d(this.offset));
shape.setDynamic(this.dynamic);
- // Clone sampler config
- PointSampler srcSampler = this.pointSampler;
- PointSampler destSampler = shape.getPointSampler();
- destSampler.setStyle(srcSampler.getStyle());
- destSampler.setDensity(srcSampler.getDensity());
- destSampler.setOrdering(srcSampler.getOrdering());
- if (srcSampler.getDrawContext() != null)
- destSampler.setDrawContext(srcSampler.getDrawContext().copy());
+ shape.setPointSampler(this.pointSampler.clone());
+ // The copy has the same geometry, so give it the same version: the cloned sampler's cached points
+ // then stay valid until either shape actually changes.
+ if (shape instanceof AbstractShape abstractShape)
+ abstractShape.version = this.version;
return shape;
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Arc.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Arc.java
index a4a8d7e..1a612e5 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Arc.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Arc.java
@@ -1,50 +1,128 @@
package com.sovdee.shapes.shapes;
+import com.sovdee.shapes.sampling.SamplingStyle;
import org.joml.Vector3d;
-import java.util.Set;
+import java.util.List;
+/**
+ * An arc is a partial {@link Circle}: a sector of a circle swept from angle {@code 0} to
+ * {@code cutoffAngle} radians around the Y axis. When a non-zero height is provided it becomes
+ * a partial cylinder (a cylindrical wedge).
+ *
+ * The cutoff angle is clamped to {@code [0, 2π]}. A cutoff of {@code 2π} produces a full
+ * circle or cylinder, identical in geometry to the parent {@link Circle}. Angles are measured
+ * in the XZ plane starting from the positive X axis.
+ *
+ * Surface generation delegates to {@link #generateFilled} so that sector fills are consistent
+ * across all three {@link com.sovdee.shapes.sampling.SamplingStyle} modes.
+ */
public class Arc extends Circle implements CutoffShape {
+ /**
+ * Creates a flat (zero-height) arc with the given radius and angular span.
+ *
+ * @param radius the radius of the arc; clamped to at least {@link Shape#EPSILON}
+ * @param cutoffAngle the angular span of the arc in radians; clamped to {@code [0, 2π]}
+ */
public Arc(double radius, double cutoffAngle) {
super(radius);
this.cutoffAngle = Math.clamp(cutoffAngle, 0, Math.PI * 2);
}
+ /**
+ * Creates a cylindrical-wedge arc with the given radius, height, and angular span.
+ *
+ * @param radius the radius of the arc; clamped to at least {@link Shape#EPSILON}
+ * @param height the vertical extent of the arc; clamped to {@code >= 0}
+ * @param cutoffAngle the angular span of the arc in radians; clamped to {@code [0, 2π]}
+ */
public Arc(double radius, double height, double cutoffAngle) {
super(radius, height);
this.cutoffAngle = Math.clamp(cutoffAngle, 0, Math.PI * 2);
}
+ /**
+ * Generates surface points by delegating to {@link #generateFilled(List, double)} so that
+ * the surface of an arc sector is treated as a filled disc segment rather than just an outline.
+ *
+ * @param points the list to append generated points to; must not be null
+ * @param density the desired spacing between points
+ */
@Override
- public void generateSurface(Set points, double density) {
+ public void generateSurface(List points, double density) {
generateFilled(points, density);
}
+ /**
+ * The surface of an arc is drawn filled, so its density is estimated the same way.
+ */
+ @Override
+ public double computeDensity(SamplingStyle style, int targetPointCount) {
+ return super.computeDensity(style == SamplingStyle.SURFACE ? SamplingStyle.FILL : style, targetPointCount);
+ }
+
+ /**
+ * {@inheritDoc}
+ *
+ * @return the cutoff angle in radians, in the range {@code [0, 2π]}
+ */
@Override
public double getCutoffAngle() {
return this.cutoffAngle;
}
+ /**
+ * {@inheritDoc}
+ * Clamps the given angle to {@code [0, 2π]} and invalidates the point cache.
+ *
+ * @param cutoffAngle the new cutoff angle in radians; clamped to {@code [0, 2π]}
+ */
@Override
public void setCutoffAngle(double cutoffAngle) {
this.cutoffAngle = Math.clamp(cutoffAngle, 0, Math.PI * 2);
invalidate();
}
+ /**
+ * Returns {@code true} if {@code point} is within the parent {@link Circle}'s disc/cylinder
+ * and its XZ angle is within the cutoff span. The angle is measured from the positive X axis
+ * and normalised to {@code [0, 2π]} using {@code atan2(z, x)}.
+ *
+ * @param point the point to test, in local coordinates
+ * @param tolerance how far outside the exact shape still counts as contained
+ * @return {@code true} if the point lies inside this arc sector
+ */
@Override
- public boolean contains(Vector3d point) {
- if (!super.contains(point)) return false;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ if (!super.containsLocal(point, tolerance)) return false;
+ if (cutoffAngle >= Math.PI * 2 - EPSILON) return true;
+ double distance = Math.sqrt(point.x * point.x + point.z * point.z);
+ // the axis itself belongs to every sector
+ if (distance <= tolerance) return true;
double angle = Math.atan2(point.z, point.x);
if (angle < 0) angle += 2 * Math.PI;
- return angle <= cutoffAngle;
+ // allow the tolerance, as an angle at this distance, on either side of the sector
+ double slack = tolerance / distance;
+ return angle <= cutoffAngle + slack || angle >= 2 * Math.PI - slack;
}
+ /**
+ * Returns a deep copy of this arc with identical radius, height, cutoff angle, and base
+ * transform state.
+ *
+ * @return a new {@link Arc} equal to this one
+ */
@Override
public Shape clone() {
return this.copyTo(new Arc(this.getRadius(), this.getHeight(), cutoffAngle));
}
+ /**
+ * Returns a human-readable description of this arc, including its radius, cutoff angle, and height.
+ *
+ * @return a string of the form {@code Arc{radius=..., cutoffAngle=..., height=...}}
+ */
@Override
public String toString() {
return "Arc{radius=" + this.getRadius() + ", cutoffAngle=" + cutoffAngle + ", height=" + this.getHeight() + '}';
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/BezierCurve.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/BezierCurve.java
index 734f01a..b526907 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/BezierCurve.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/BezierCurve.java
@@ -1,11 +1,11 @@
package com.sovdee.shapes.shapes;
import com.sovdee.shapes.sampling.SamplingStyle;
+import com.sovdee.shapes.util.VectorUtil;
import org.joml.Vector3d;
import java.util.ArrayList;
import java.util.List;
-import java.util.Set;
import java.util.function.Supplier;
/**
@@ -17,50 +17,97 @@ public class BezierCurve extends AbstractShape {
private List controlPoints;
private Supplier> controlPointsSupplier;
+ /**
+ * Creates a static Bezier curve from a fixed list of control points.
+ * The points are deep-copied so subsequent mutation of the list has no effect.
+ *
+ * @param controlPoints the control points defining the curve; must contain at least 2 elements
+ * @throws IllegalArgumentException if fewer than 2 control points are provided
+ */
public BezierCurve(List controlPoints) {
super();
if (controlPoints.size() < 2)
throw new IllegalArgumentException("A bezier curve must have at least 2 control points.");
- this.controlPoints = new ArrayList<>();
+ this.controlPoints = new ArrayList<>(controlPoints.size());
for (Vector3d cp : controlPoints)
this.controlPoints.add(new Vector3d(cp));
}
+ /**
+ * Creates a dynamic Bezier curve whose control points are re-fetched from {@code controlPointsSupplier}
+ * on every render call. The shape is automatically marked {@link #setDynamic(boolean) dynamic}.
+ * The supplier is invoked once during construction to validate the initial point count.
+ *
+ * @param controlPointsSupplier a supplier that returns the live control points; must return
+ * at least 2 points on every invocation
+ * @throws IllegalArgumentException if the initial supplier result contains fewer than 2 points
+ */
public BezierCurve(Supplier> controlPointsSupplier) {
super();
this.controlPointsSupplier = controlPointsSupplier;
List pts = controlPointsSupplier.get();
if (pts.size() < 2)
throw new IllegalArgumentException("A bezier curve must have at least 2 control points.");
- this.controlPoints = new ArrayList<>();
- for (Vector3d cp : pts)
- this.controlPoints.add(new Vector3d(cp));
+ this.controlPoints = copyOf(pts);
setDynamic(true);
}
+ private static List copyOf(List points) {
+ List copy = new ArrayList<>(points.size());
+ for (Vector3d point : points)
+ copy.add(new Vector3d(point));
+ return copy;
+ }
+
+ /**
+ * Re-reads the control point supplier, if any, and invalidates the curve when a control point moved.
+ */
+ @Override
+ public void refresh() {
+ if (controlPointsSupplier == null)
+ return;
+ List pts = controlPointsSupplier.get();
+ if (pts.size() < 2 || pts.equals(controlPoints))
+ return;
+ this.controlPoints = copyOf(pts);
+ invalidate();
+ }
+
+ /**
+ * Copy constructor: creates a static Bezier curve with deep-copied control points from
+ * {@code curve}. The supplier is not copied; the result is always a static curve.
+ *
+ * @param curve the source curve to copy control points from; must not be null
+ */
public BezierCurve(BezierCurve curve) {
super();
- this.controlPoints = new ArrayList<>();
+ this.controlPoints = new ArrayList<>(curve.controlPoints.size());
for (Vector3d cp : curve.controlPoints)
this.controlPoints.add(new Vector3d(cp));
}
+ /**
+ * Generates points along the Bezier curve using the de Casteljau algorithm and appends them
+ * to {@code points}. If a control-points supplier is set it is invoked now to refresh the
+ * control point list before sampling.
+ *
+ * The number of steps is {@code estimateLength() / density}, so smaller {@code density} values
+ * produce a finer approximation of the smooth curve.
+ *
+ * @param points the list to append generated points to; must not be null
+ * @param density the desired arc-length spacing between consecutive curve samples
+ */
@Override
- public void generateOutline(Set points, double density) {
- if (controlPointsSupplier != null) {
- List pts = controlPointsSupplier.get();
- this.controlPoints = new ArrayList<>();
- for (Vector3d cp : pts)
- this.controlPoints.add(new Vector3d(cp));
- }
- int steps = (int) (estimateLength() / density);
+ public void generateOutline(List points, double density) {
+ int steps = segments(estimateLength(), density);
int n = controlPoints.size();
Vector3d[] temp = new Vector3d[n];
for (int i = 0; i < n; i++)
temp[i] = new Vector3d();
- for (int step = 0; step < steps; step++) {
+ // include both ends of the curve
+ for (int step = 0; step <= steps; step++) {
double t = (double) step / steps;
double nt = 1 - t;
for (int i = 0; i < n; i++)
@@ -82,21 +129,42 @@ private double estimateLength() {
return dist;
}
+ /**
+ * Computes the density required to produce approximately {@code targetPointCount} points along
+ * this curve. The result is {@code estimateLength() / targetPointCount}, where
+ * {@code estimateLength()} is the sum of straight-line distances between consecutive control points.
+ *
+ * @param style ignored; the Bezier curve has only one meaningful sampling mode
+ * @param targetPointCount the desired number of curve samples; clamped to at least 1
+ * @return the density value to pass to {@link #generateOutline(List, double)}
+ */
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
- int count = Math.max(targetPointCount, 1);
- return estimateLength() / count;
+ // n segments produce n + 1 points
+ int segments = Math.max(targetPointCount - 1, 1);
+ return estimateLength() / segments;
}
+ /**
+ * Returns {@code true} if {@code point} lies approximately on the curve.
+ * The test uses a high-density sampling of the curve (approximately one sample per {@code 0.1}
+ * units of chord length) and checks whether any sampled point is within {@link Shape#EPSILON}
+ * of {@code point}.
+ *
+ * @param point the point to test, in local coordinates
+ * @param tolerance how far outside the exact shape still counts as contained
+ * @return {@code true} if the point is within {@link Shape#EPSILON} of the curve
+ */
@Override
- public boolean contains(Vector3d point) {
- // Approximate: check distance to nearest sampled point
- int samples = Math.max((int) (estimateLength() / 0.1), 10);
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ // Approximate: test against the curve traced as a polyline
+ int samples = Math.max(segments(estimateLength(), 0.05), 16);
int n = controlPoints.size();
Vector3d[] temp = new Vector3d[n];
for (int i = 0; i < n; i++) temp[i] = new Vector3d();
-
- for (int step = 0; step <= samples; step++) {
+ Vector3d previous = new Vector3d(controlPoints.get(0));
+ double limit = tolerance * tolerance;
+ for (int step = 1; step <= samples; step++) {
double t = (double) step / samples;
double nt = 1 - t;
for (int i = 0; i < n; i++) temp[i].set(controlPoints.get(i));
@@ -105,34 +173,57 @@ public boolean contains(Vector3d point) {
temp[i].mul(nt).add(new Vector3d(temp[i + 1]).mul(t));
}
}
- if (point.distance(temp[0]) <= EPSILON) return true;
+ if (VectorUtil.distanceToSegmentSquared(point, previous, temp[0]) <= limit) return true;
+ previous.set(temp[0]);
}
return false;
}
+ /**
+ * Returns the current list of control points. For dynamic curves this reflects the most
+ * recently fetched values from the supplier (i.e. after the last {@link #generateOutline} call).
+ *
+ * @return the live control point list; modifications affect the internal state directly
+ */
public List getControlPoints() {
return controlPoints;
}
+ /**
+ * Replaces the control points of this curve with a deep copy of {@code controlPoints} and
+ * invalidates the point cache. The supplier is not updated.
+ *
+ * @param controlPoints the new control points; must not be null or empty
+ */
public void setControlPoints(List controlPoints) {
- this.controlPoints = new ArrayList<>();
+ this.controlPoints = new ArrayList<>(controlPoints.size());
for (Vector3d cp : controlPoints)
this.controlPoints.add(new Vector3d(cp));
invalidate();
}
+ /**
+ * Returns the supplier used to refresh control points on each render call, or {@code null}
+ * if this is a static curve constructed from a fixed point list.
+ *
+ * @return the control-points supplier, or {@code null} for static curves
+ */
public Supplier> getControlPointsSupplier() {
return controlPointsSupplier;
}
+ /**
+ * Returns a deep copy of this curve. If a control-points supplier is present the clone shares
+ * the same supplier reference (suppliers are not themselves cloneable). Otherwise, control
+ * points are deep-copied. Base transform state is copied via {@link #copyTo(Shape)}.
+ *
+ * @return a new {@link BezierCurve} with the same geometry and transform state
+ */
@Override
public Shape clone() {
- BezierCurve clone;
- if (controlPointsSupplier != null) {
- clone = new BezierCurve(controlPointsSupplier);
- } else {
- clone = new BezierCurve(this);
- }
+ // copy the current control points rather than re-reading the supplier, so the copy has identical geometry
+ BezierCurve clone = new BezierCurve(this);
+ clone.controlPointsSupplier = this.controlPointsSupplier;
return this.copyTo(clone);
}
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Circle.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Circle.java
index 5e7b510..38864b3 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Circle.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Circle.java
@@ -3,19 +3,57 @@
import com.sovdee.shapes.sampling.SamplingStyle;
import org.joml.Vector3d;
-import java.util.LinkedHashSet;
-import java.util.Set;
-
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * A circle (or cylinder when {@code height > 0}) centred at the local origin in the XZ plane.
+ *
+ * With {@code height == 0} the three generation modes produce:
+ *
+ * - {@link #generateOutline} — a ring of points at the given radius
+ * - {@link #generateSurface} — a filled disc (solid circle)
+ * - {@link #generateFilled} — same as surface for a flat shape
+ *
+ * With {@code height > 0} the modes produce:
+ *
+ * - {@link #generateOutline} — two rings at Y = 0 and Y = height, connected by vertical lines
+ * - {@link #generateSurface} — a full cylinder (two discs + wall)
+ * - {@link #generateFilled} — a solid cylindrical volume
+ *
+ *
+ * The protected field {@code cutoffAngle} is inherited by {@link Arc} to limit the angular span.
+ * In a plain {@code Circle} this is always {@code 2π}. All angles are measured from the positive
+ * X axis in the XZ plane.
+ *
+ * {@code Circle} implements both {@link RadialShape} and {@link LWHShape}; the {@code length} and
+ * {@code width} dimensions are not meaningful for a circle and return/accept {@code 0}. Only
+ * {@code height} is active via {@link LWHShape}.
+ */
public class Circle extends AbstractShape implements RadialShape, LWHShape {
+ private static final double FULL_CIRCLE = 2 * Math.PI;
+
private double radius;
protected double cutoffAngle;
private double height;
+ /**
+ * Creates a flat circle (height = 0) with the given radius.
+ *
+ * @param radius the radius of the circle; clamped to at least {@link Shape#EPSILON}
+ */
public Circle(double radius) {
this(radius, 0);
}
+ /**
+ * Creates a circle or cylinder with the given radius and height.
+ * A height of {@code 0} produces a flat 2-D circle.
+ *
+ * @param radius the radius; clamped to at least {@link Shape#EPSILON}
+ * @param height the vertical extent; clamped to {@code >= 0}
+ */
public Circle(double radius, double height) {
super();
this.radius = Math.max(radius, Shape.EPSILON);
@@ -25,96 +63,140 @@ public Circle(double radius, double height) {
// --- Static calculation methods ---
- public static Set calculateCircle(double radius, double density, double cutoffAngle) {
- Set points = new LinkedHashSet<>();
- double stepSize = density / radius;
- for (double theta = 0; theta < cutoffAngle; theta += stepSize) {
+ /**
+ * Appends points evenly spaced along a circular arc of the given {@code radius} in the XZ
+ * plane. The angular step is {@code density / radius} radians, so arc-length spacing between
+ * consecutive points equals approximately {@code density}.
+ *
+ * @param points the list to append to; must not be null
+ * @param radius the radius of the circle
+ * @param density the desired arc-length spacing between points
+ * @param cutoffAngle the angular span to cover, in radians ({@code [0, 2π]})
+ */
+ public static void calculateCircle(List points, double radius, double density, double cutoffAngle) {
+ boolean full = cutoffAngle >= FULL_CIRCLE - Shape.EPSILON;
+ double angle = full ? FULL_CIRCLE : cutoffAngle;
+ int steps = segments(angle * radius, density);
+ // a full circle closes on itself, so its last point would repeat the first; an arc includes both ends
+ int last = full ? steps - 1 : steps;
+ if (points instanceof ArrayList al)
+ al.ensureCapacity(points.size() + last + 1);
+ for (int i = 0; i <= last; i++) {
+ double theta = angle * i / steps;
points.add(new Vector3d(Math.cos(theta) * radius, 0, Math.sin(theta) * radius));
}
- return points;
}
- public static Set calculateDisc(double radius, double density, double cutoffAngle) {
- Set points = new LinkedHashSet<>();
- for (double subRadius = density; subRadius < radius; subRadius += density) {
- points.addAll(calculateCircle(subRadius, density, cutoffAngle));
+ /**
+ * Appends points filling the area of a disc sector in the XZ plane by stacking concentric
+ * rings from {@code density} to {@code radius} (inclusive) at intervals of {@code density}.
+ * Each ring is generated by {@link #calculateCircle}.
+ *
+ * @param points the list to append to; must not be null
+ * @param radius the outer radius of the disc
+ * @param density the desired spacing between points and between concentric rings
+ * @param cutoffAngle the angular span of the sector, in radians ({@code [0, 2π]})
+ */
+ public static void calculateDisc(List points, double radius, double density, double cutoffAngle) {
+ points.add(new Vector3d(0, 0, 0));
+ int rings = segments(radius, density);
+ for (int i = 1; i <= rings; i++) {
+ calculateCircle(points, radius * i / rings, density, cutoffAngle);
}
- points.addAll(calculateCircle(radius, density, cutoffAngle));
- return points;
}
- public static Set calculateCylinder(double radius, double height, double density, double cutoffAngle) {
- Set points = calculateDisc(radius, density, cutoffAngle);
- // Top disc via direct loop
- Set top = new LinkedHashSet<>();
- for (Vector3d v : points) {
- top.add(new Vector3d(v.x, height, v.z));
+ /**
+ * Appends points filling a cylindrical (or wedge-cylinder) volume. The method generates:
+ *
+ * - A bottom disc at Y = 0.
+ * - A top disc at Y = {@code height} (copied from the bottom disc).
+ * - The curved wall, filled vertically via {@link #fillVertically}.
+ *
+ *
+ * @param points the list to append to; must not be null
+ * @param radius the radius of the cylinder
+ * @param height the height of the cylinder; must be positive
+ * @param density the desired spacing between points
+ * @param cutoffAngle the angular span of the cylinder sector, in radians ({@code [0, 2π]})
+ */
+ public static void calculateCylinder(List points, double radius, double height, double density, double cutoffAngle) {
+ // Bottom disc
+ int discStart = points.size();
+ calculateDisc(points, radius, density, cutoffAngle);
+ int discEnd = points.size();
+ // Wall: copies of the outer ring between the two discs. The discs already contain the rings at the
+ // bottom and top, so the base ring is only generated to be copied, and is then removed.
+ calculateCircle(points, radius, density, cutoffAngle);
+ int ringEnd = points.size();
+ fillVertically(points, discEnd, height, density, false);
+ points.subList(discEnd, ringEnd).clear();
+ // Top disc - copy bottom disc at height
+ for (int i = discStart; i < discEnd; i++) {
+ Vector3d v = points.get(i);
+ points.add(new Vector3d(v.x, height, v.z));
}
- points.addAll(top);
- // Wall
- Set wall = calculateCircle(radius, density, cutoffAngle);
- fillVertically(wall, height, density);
- points.addAll(wall);
- return points;
}
// --- Generation methods ---
@Override
- public void generateOutline(Set points, double density) {
- Set circle = calculateCircle(radius, density, cutoffAngle);
+ public void generateOutline(List points, double density) {
+ int start = points.size();
+ calculateCircle(points, radius, density, cutoffAngle);
if (height != 0) {
- fillVertically(circle, height, density);
- points.addAll(circle);
- } else {
- points.addAll(circle);
+ fillVertically(points, start, height, density);
}
}
@Override
- public void generateSurface(Set points, double density) {
+ public void generateSurface(List points, double density) {
if (height != 0)
- points.addAll(calculateCylinder(radius, height, density, cutoffAngle));
+ calculateCylinder(points, radius, height, density, cutoffAngle);
else
- points.addAll(calculateDisc(radius, density, cutoffAngle));
+ calculateDisc(points, radius, density, cutoffAngle);
}
@Override
- public void generateFilled(Set points, double density) {
- Set disc = calculateDisc(radius, density, cutoffAngle);
+ public void generateFilled(List points, double density) {
+ int start = points.size();
+ calculateDisc(points, radius, density, cutoffAngle);
if (height != 0) {
- fillVertically(disc, height, density);
- points.addAll(disc);
- } else {
- points.addAll(disc);
+ fillVertically(points, start, height, density);
}
}
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(targetPointCount, 1);
+ double arcLength = cutoffAngle * radius;
+ double discArea = cutoffAngle * 0.5 * radius * radius;
return switch (style) {
case OUTLINE -> {
- if (height == 0) yield cutoffAngle * radius / count;
- double circumference = cutoffAngle * radius;
- double wallArea = circumference * height;
- yield Math.sqrt((circumference + wallArea) / count);
+ if (height == 0) yield arcLength / count;
+ // with a height, the outline is the wall
+ yield Math.sqrt(arcLength * height / count);
}
case SURFACE -> {
- double discArea = cutoffAngle * 0.5 * radius * radius;
- double wallArea = cutoffAngle * radius * height;
- yield Math.sqrt((discArea + wallArea) / count);
+ if (height == 0) yield Math.sqrt(discArea / count);
+ yield Math.sqrt((2 * discArea + arcLength * height) / count);
+ }
+ case FILL -> {
+ // a flat circle has no volume: it is filled as a disc
+ if (height == 0) yield Math.sqrt(discArea / count);
+ yield Math.cbrt(discArea * height / count);
}
- case FILL -> Math.cbrt(cutoffAngle * 0.5 * radius * radius * height / count);
};
}
@Override
- public boolean contains(Vector3d point) {
- double distSq = point.x * point.x + point.z * point.z;
- if (distSq > radius * radius) return false;
- if (height > 0) return point.y >= 0 && point.y <= height;
- return Math.abs(point.y) < EPSILON;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ if (height > 0) {
+ if (point.y < -tolerance || point.y > height + tolerance) return false;
+ } else if (Math.abs(point.y) > tolerance) {
+ return false;
+ }
+ double maxDistance = radius + tolerance;
+ return point.x * point.x + point.z * point.z <= maxDistance * maxDistance;
}
@Override
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Cuboid.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Cuboid.java
index 57b1e0c..8526ec4 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Cuboid.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Cuboid.java
@@ -3,21 +3,40 @@
import com.sovdee.shapes.sampling.SamplingStyle;
import org.joml.Vector3d;
-import java.util.Set;
+import java.util.List;
import java.util.function.Supplier;
/**
- * A cuboid shape, defined either by dimensions or by two corner vectors.
- * For dynamic (entity-following) cuboids, use the plugin-side DynamicCuboid wrapper.
+ * A cuboid (rectangular prism) shape, defined either by explicit length/width/height dimensions
+ * or by two opposing corner {@link Vector3d} positions. The cuboid is always axis-aligned in
+ * local space and centred at the origin, offset by any {@code centerOffset} computed from the
+ * corner positions.
+ *
+ * When constructed from two {@link java.util.function.Supplier Supplier<Vector3d>} corners the
+ * cuboid is marked as {@link AbstractShape#setDynamic(boolean) dynamic}, meaning the corner
+ * positions are re-evaluated each time the cuboid is sampled (see {@link #refresh()}).
+ *
+ * For entity-following dynamic cuboids in the plugin layer, use the {@code DynamicCuboid} wrapper.
*/
public class Cuboid extends AbstractShape implements LWHShape {
private double halfLength, halfWidth, halfHeight;
- private double lengthStep, widthStep, heightStep;
private Vector3d centerOffset = new Vector3d(0, 0, 0);
private Supplier cornerASupplier;
private Supplier cornerBSupplier;
+ // the corners last read from the suppliers, to detect when they move
+ private Vector3d lastCornerA;
+ private Vector3d lastCornerB;
+ /**
+ * Constructs a cuboid centred at the local origin with the given dimensions.
+ * Each half-dimension is clamped to at least {@link Shape#EPSILON} to prevent
+ * degenerate geometry.
+ *
+ * @param length extent along the X axis (total, not half)
+ * @param width extent along the Z axis (total, not half)
+ * @param height extent along the Y axis (total, not half)
+ */
public Cuboid(double length, double width, double height) {
super();
this.halfWidth = Math.max(width / 2, Shape.EPSILON);
@@ -25,106 +44,207 @@ public Cuboid(double length, double width, double height) {
this.halfHeight = Math.max(height / 2, Shape.EPSILON);
}
+ /**
+ * Constructs a cuboid from two opposing corner positions expressed as world-space
+ * {@link Vector3d} values. The cuboid's dimensions are derived from the axis-aligned
+ * bounding box of the two corners, and the {@code centerOffset} is set to the midpoint
+ * so that drawing is centred correctly.
+ *
+ * @param cornerA first corner of the cuboid
+ * @param cornerB second corner, diagonally opposite to {@code cornerA}
+ * @throws IllegalArgumentException if both corners are equal
+ */
public Cuboid(Vector3d cornerA, Vector3d cornerB) {
super();
if (cornerA.equals(cornerB))
throw new IllegalArgumentException("Cuboid corners cannot be equal.");
- this.halfLength = Math.abs(cornerB.x - cornerA.x) / 2;
- this.halfWidth = Math.abs(cornerB.z - cornerA.z) / 2;
- this.halfHeight = Math.abs(cornerB.y - cornerA.y) / 2;
- centerOffset = new Vector3d(cornerB).add(cornerA).mul(0.5);
+ setCorners(cornerA, cornerB);
}
+ /**
+ * Constructs a dynamic cuboid whose corners are provided by {@link Supplier} functions.
+ * The suppliers are called once during construction to compute initial dimensions,
+ * and again before every sampling (see {@link #refresh()}) so that the cuboid tracks
+ * positions that change over time (e.g. entity locations).
+ *
+ * This constructor marks the shape as {@link AbstractShape#setDynamic(boolean) dynamic}.
+ *
+ * @param cornerA supplier returning the first corner position
+ * @param cornerB supplier returning the second corner position, diagonally opposite
+ */
public Cuboid(Supplier cornerA, Supplier cornerB) {
super();
this.cornerASupplier = cornerA;
this.cornerBSupplier = cornerB;
- Vector3d a = cornerA.get();
- Vector3d b = cornerB.get();
- this.halfLength = Math.max(Math.abs(b.x - a.x) / 2, Shape.EPSILON);
- this.halfWidth = Math.max(Math.abs(b.z - a.z) / 2, Shape.EPSILON);
- this.halfHeight = Math.max(Math.abs(b.y - a.y) / 2, Shape.EPSILON);
+ this.lastCornerA = new Vector3d(cornerA.get());
+ this.lastCornerB = new Vector3d(cornerB.get());
+ setCorners(lastCornerA, lastCornerB);
setDynamic(true);
}
- private void calculateSteps(double density) {
- widthStep = 2 * halfWidth / Math.round(2 * halfWidth / density);
- lengthStep = 2 * halfLength / Math.round(2 * halfLength / density);
- heightStep = 2 * halfHeight / Math.round(2 * halfHeight / density);
+ /**
+ * Sizes the cuboid to span the two corners, and centers it between them.
+ */
+ private void setCorners(Vector3d cornerA, Vector3d cornerB) {
+ this.halfLength = Math.max(Math.abs(cornerB.x - cornerA.x) / 2, Shape.EPSILON);
+ this.halfWidth = Math.max(Math.abs(cornerB.z - cornerA.z) / 2, Shape.EPSILON);
+ this.halfHeight = Math.max(Math.abs(cornerB.y - cornerA.y) / 2, Shape.EPSILON);
+ this.centerOffset = new Vector3d(cornerB).add(cornerA).mul(0.5);
}
+ /**
+ * Re-reads the corner suppliers, if any, and invalidates the cuboid when a corner moved.
+ */
@Override
- public void beforeSampling(double density) {
- if (cornerASupplier != null && cornerBSupplier != null) {
- Vector3d a = cornerASupplier.get();
- Vector3d b = cornerBSupplier.get();
- this.halfLength = Math.max(Math.abs(b.x - a.x) / 2, Shape.EPSILON);
- this.halfWidth = Math.max(Math.abs(b.z - a.z) / 2, Shape.EPSILON);
- this.halfHeight = Math.max(Math.abs(b.y - a.y) / 2, Shape.EPSILON);
- }
- calculateSteps(density);
- }
-
- @Override
- public void afterSampling(Set points) {
- points.forEach(vector -> vector.add(centerOffset));
+ public void refresh() {
+ if (cornerASupplier == null || cornerBSupplier == null)
+ return;
+ Vector3d a = cornerASupplier.get();
+ Vector3d b = cornerBSupplier.get();
+ if (a.equals(lastCornerA) && b.equals(lastCornerB))
+ return;
+ lastCornerA = new Vector3d(a);
+ lastCornerB = new Vector3d(b);
+ setCorners(a, b);
+ invalidate();
}
+ /**
+ * Generates the 12-edge wireframe of the cuboid. Points are placed along each of the
+ * four parallel edges in the X, Y, and Z directions using the pre-computed step sizes.
+ * Corner vertices are included; interior edge steps along non-primary directions avoid
+ * re-adding the already-placed corner points.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the target spacing between adjacent points (pre-computed step sizes
+ * are used instead of {@code density} directly)
+ */
@Override
- public void generateOutline(Set points, double density) {
- for (double x = -halfLength; x <= halfLength; x += lengthStep) {
+ public void generateOutline(List points, double density) {
+ int start = points.size();
+ int xSegments = segments(2 * halfLength, density);
+ int ySegments = segments(2 * halfHeight, density);
+ int zSegments = segments(2 * halfWidth, density);
+ // the four edges along x include the corners; the other edges only add the points between them
+ for (int i = 0; i <= xSegments; i++) {
+ double x = -halfLength + 2 * halfLength * i / xSegments;
points.add(new Vector3d(x, -halfHeight, -halfWidth));
points.add(new Vector3d(x, -halfHeight, halfWidth));
points.add(new Vector3d(x, halfHeight, -halfWidth));
points.add(new Vector3d(x, halfHeight, halfWidth));
}
- for (double y = -halfHeight + heightStep; y < halfHeight; y += heightStep) {
+ for (int i = 1; i < ySegments; i++) {
+ double y = -halfHeight + 2 * halfHeight * i / ySegments;
points.add(new Vector3d(-halfLength, y, -halfWidth));
points.add(new Vector3d(-halfLength, y, halfWidth));
points.add(new Vector3d(halfLength, y, -halfWidth));
points.add(new Vector3d(halfLength, y, halfWidth));
}
- for (double z = -halfWidth + widthStep; z < halfWidth; z += widthStep) {
+ for (int i = 1; i < zSegments; i++) {
+ double z = -halfWidth + 2 * halfWidth * i / zSegments;
points.add(new Vector3d(-halfLength, -halfHeight, z));
points.add(new Vector3d(-halfLength, halfHeight, z));
points.add(new Vector3d(halfLength, -halfHeight, z));
points.add(new Vector3d(halfLength, halfHeight, z));
}
+ applyCenterOffset(points, start);
}
+ /**
+ * Generates points covering all six faces of the cuboid. The top and bottom (XZ) faces are
+ * sampled as full grids; the front/back (XY) and left/right (YZ) faces fill in the remaining
+ * interior rows/columns to avoid duplicating edge points already added by the adjacent faces.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the target spacing between adjacent points (pre-computed step sizes
+ * are used instead of {@code density} directly)
+ */
@Override
- public void generateSurface(Set points, double density) {
- for (double x = -halfLength; x <= halfLength; x += lengthStep) {
- for (double z = -halfWidth; z <= halfWidth; z += widthStep) {
+ public void generateSurface(List points, double density) {
+ int start = points.size();
+ int xSegments = segments(2 * halfLength, density);
+ int ySegments = segments(2 * halfHeight, density);
+ int zSegments = segments(2 * halfWidth, density);
+ // top and bottom faces, including their edges
+ for (int i = 0; i <= xSegments; i++) {
+ double x = -halfLength + 2 * halfLength * i / xSegments;
+ for (int k = 0; k <= zSegments; k++) {
+ double z = -halfWidth + 2 * halfWidth * k / zSegments;
points.add(new Vector3d(x, -halfHeight, z));
points.add(new Vector3d(x, halfHeight, z));
}
}
- for (double y = -halfHeight + heightStep; y < halfHeight; y += heightStep) {
- for (double z = -halfWidth; z <= halfWidth; z += widthStep) {
+ // the remaining faces, without the edges already covered
+ for (int j = 1; j < ySegments; j++) {
+ double y = -halfHeight + 2 * halfHeight * j / ySegments;
+ for (int k = 0; k <= zSegments; k++) {
+ double z = -halfWidth + 2 * halfWidth * k / zSegments;
points.add(new Vector3d(-halfLength, y, z));
points.add(new Vector3d(halfLength, y, z));
}
- }
- for (double x = -halfLength + lengthStep; x < halfLength; x += lengthStep) {
- for (double y = -halfHeight + heightStep; y < halfHeight; y += heightStep) {
+ for (int i = 1; i < xSegments; i++) {
+ double x = -halfLength + 2 * halfLength * i / xSegments;
points.add(new Vector3d(x, y, -halfWidth));
points.add(new Vector3d(x, y, halfWidth));
}
}
+ applyCenterOffset(points, start);
}
+ /**
+ * Generates a uniform 3-D grid of points filling the interior of the cuboid. Every lattice
+ * site within {@code [-halfLength, halfLength] × [-halfHeight, halfHeight] × [-halfWidth, halfWidth]}
+ * is included, using the pre-computed axis step sizes.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the target spacing between adjacent points (pre-computed step sizes
+ * are used instead of {@code density} directly)
+ */
@Override
- public void generateFilled(Set points, double density) {
- for (double x = -halfLength; x <= halfLength; x += lengthStep) {
- for (double y = -halfHeight; y <= halfHeight; y += heightStep) {
- for (double z = -halfWidth; z <= halfWidth; z += widthStep) {
+ public void generateFilled(List points, double density) {
+ int start = points.size();
+ int xSegments = segments(2 * halfLength, density);
+ int ySegments = segments(2 * halfHeight, density);
+ int zSegments = segments(2 * halfWidth, density);
+ for (int i = 0; i <= xSegments; i++) {
+ double x = -halfLength + 2 * halfLength * i / xSegments;
+ for (int j = 0; j <= ySegments; j++) {
+ double y = -halfHeight + 2 * halfHeight * j / ySegments;
+ for (int k = 0; k <= zSegments; k++) {
+ double z = -halfWidth + 2 * halfWidth * k / zSegments;
points.add(new Vector3d(x, y, z));
}
}
}
+ applyCenterOffset(points, start);
}
+ /**
+ * Moves the points generated since {@code start} from around the origin to around the cuboid's center.
+ */
+ private void applyCenterOffset(List points, int start) {
+ if (centerOffset.x == 0 && centerOffset.y == 0 && centerOffset.z == 0)
+ return;
+ for (int i = start; i < points.size(); i++) {
+ points.get(i).add(centerOffset);
+ }
+ }
+
+ /**
+ * Estimates the point spacing required to produce approximately {@code targetPointCount} points
+ * for the given {@link SamplingStyle}.
+ *
+ * - OUTLINE: {@code density = totalEdgeLength / count}, where total edge length
+ * is {@code 8 * (L/2 + H/2 + W/2)}
+ * - SURFACE: {@code density = sqrt(totalSurfaceArea / count)}, where surface area
+ * is {@code 2*(L*H + L*W + H*W)}
+ * - FILL: {@code density = cbrt(volume / count)}, where volume is {@code L*W*H}
+ *
+ *
+ * @param style the sampling style (OUTLINE, SURFACE, or FILL)
+ * @param targetPointCount the desired number of output points
+ * @return the estimated point spacing to achieve the target count
+ */
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(1, targetPointCount);
@@ -135,52 +255,115 @@ public double computeDensity(SamplingStyle style, int targetPointCount) {
};
}
+ /**
+ * Returns {@code true} if the given point lies inside or on the surface of this cuboid.
+ * Tests are performed in local (centred) space: the point is considered contained when
+ * {@code |x| ≤ halfLength && |y| ≤ halfHeight && |z| ≤ halfWidth}.
+ *
+ * @param point the point to test, in local shape space
+ * @param tolerance how far outside the exact shape still counts as contained
+ * @return {@code true} if {@code point} is within the axis-aligned bounds of the cuboid
+ */
@Override
- public boolean contains(Vector3d point) {
- return Math.abs(point.x) <= halfLength &&
- Math.abs(point.y) <= halfHeight &&
- Math.abs(point.z) <= halfWidth;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ point.sub(centerOffset);
+ return Math.abs(point.x) <= halfLength + tolerance &&
+ Math.abs(point.y) <= halfHeight + tolerance &&
+ Math.abs(point.z) <= halfWidth + tolerance;
}
+ /**
+ * Returns the total length of the cuboid along the X axis ({@code halfLength * 2}).
+ *
+ * @return the full X-axis extent
+ */
@Override
public double getLength() { return halfLength * 2; }
+ /**
+ * Sets the total length of the cuboid along the X axis. Values below {@link Shape#EPSILON}
+ * are clamped to {@code EPSILON} to prevent degenerate geometry. Invalidates the point cache.
+ *
+ * @param length the new X-axis extent (total, not half)
+ */
@Override
public void setLength(double length) {
this.halfLength = Math.max(length / 2, Shape.EPSILON);
invalidate();
}
+ /**
+ * Returns the total width of the cuboid along the Z axis ({@code halfWidth * 2}).
+ *
+ * @return the full Z-axis extent
+ */
@Override
public double getWidth() { return halfWidth * 2; }
+ /**
+ * Sets the total width of the cuboid along the Z axis. Values below {@link Shape#EPSILON}
+ * are clamped to {@code EPSILON}. Invalidates the point cache.
+ *
+ * @param width the new Z-axis extent (total, not half)
+ */
@Override
public void setWidth(double width) {
this.halfWidth = Math.max(width / 2, Shape.EPSILON);
invalidate();
}
+ /**
+ * Returns the total height of the cuboid along the Y axis ({@code halfHeight * 2}).
+ *
+ * @return the full Y-axis extent
+ */
@Override
public double getHeight() { return halfHeight * 2; }
+ /**
+ * Sets the total height of the cuboid along the Y axis. Values below {@link Shape#EPSILON}
+ * are clamped to {@code EPSILON}. Invalidates the point cache.
+ *
+ * @param height the new Y-axis extent (total, not half)
+ */
@Override
public void setHeight(double height) {
this.halfHeight = Math.max(height / 2, Shape.EPSILON);
invalidate();
}
+ /**
+ * Returns the {@link Supplier} used to compute the first corner of this cuboid, or
+ * {@code null} if this cuboid was not constructed with suppliers.
+ *
+ * @return the corner-A position supplier, or {@code null}
+ */
public Supplier getCornerASupplier() { return cornerASupplier; }
+
+ /**
+ * Returns the {@link Supplier} used to compute the second corner of this cuboid, or
+ * {@code null} if this cuboid was not constructed with suppliers.
+ *
+ * @return the corner-B position supplier, or {@code null}
+ */
public Supplier getCornerBSupplier() { return cornerBSupplier; }
+ /**
+ * Creates a deep copy of this cuboid, preserving all dimensions, the corner suppliers
+ * (if present), the {@code centerOffset}, and all inherited {@link AbstractShape} state
+ * copied via {@link AbstractShape#copyTo(AbstractShape)}.
+ *
+ * @return a new {@link Cuboid} identical to this one
+ */
@Override
public Shape clone() {
- Cuboid cuboid;
- if (cornerASupplier != null && cornerBSupplier != null) {
- cuboid = new Cuboid(cornerASupplier, cornerBSupplier);
- } else {
- cuboid = new Cuboid(getLength(), getWidth(), getHeight());
- }
+ // copy the current state rather than re-reading the suppliers, so the copy has identical geometry
+ Cuboid cuboid = new Cuboid(getLength(), getWidth(), getHeight());
cuboid.centerOffset = new Vector3d(this.centerOffset);
+ cuboid.cornerASupplier = this.cornerASupplier;
+ cuboid.cornerBSupplier = this.cornerBSupplier;
+ cuboid.lastCornerA = this.lastCornerA;
+ cuboid.lastCornerB = this.lastCornerB;
return this.copyTo(cuboid);
}
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/CutoffShape.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/CutoffShape.java
index 19d3760..ab773fd 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/CutoffShape.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/CutoffShape.java
@@ -4,6 +4,21 @@
* Represents a shape that has a cutoff angle, like an arc.
*/
public interface CutoffShape extends Shape {
+
+ /**
+ * Returns the angular cutoff that limits how much of the shape's circumference is generated.
+ * The value is in radians in the range {@code [0, 2π]}, where {@code 2π} produces the full shape
+ * and smaller values truncate it to a partial arc or wedge.
+ *
+ * @return the cutoff angle in radians
+ */
double getCutoffAngle();
+
+ /**
+ * Sets the angular cutoff for this shape. Values are clamped to {@code [0, 2π]} by implementations.
+ * A value of {@code 2π} restores the full shape; a value of {@code 0} produces no points.
+ *
+ * @param cutoffAngle the new cutoff angle in radians; clamped to {@code [0, 2π]}
+ */
void setCutoffAngle(double cutoffAngle);
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipse.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipse.java
index eb99dad..62fdaa4 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipse.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipse.java
@@ -4,21 +4,51 @@
import org.joml.Vector3d;
import java.util.ArrayList;
-import java.util.LinkedHashSet;
import java.util.List;
-import java.util.Set;
+/**
+ * An ellipse (or extruded elliptical cylinder) defined by two radii along the X and Z axes
+ * and an optional height along the Y axis.
+ *
+ * When {@code height} is zero the shape is a flat 2-D ellipse lying in the XZ plane.
+ * When {@code height} is positive the shape is extruded into a full cylinder-like solid
+ * whose cross-sections are ellipses.
+ *
+ * Point sampling is delegated to the public static helpers {@link #calculateEllipse},
+ * {@link #calculateEllipticalDisc}, and {@link #calculateCylinder}, which are also reused by
+ * {@link Ellipsoid} and {@link EllipticalArc}. An arc cutoff is stored in {@link #cutoffAngle}
+ * (inherited by {@link EllipticalArc}) and defaults to {@code 2π} for a full ellipse.
+ */
public class Ellipse extends AbstractShape implements LWHShape {
+ private static final double FULL_CIRCLE = 2 * Math.PI;
+
private double xRadius;
private double zRadius;
private double height;
protected double cutoffAngle;
+ /**
+ * Constructs a flat 2-D ellipse with the given X- and Z-axis radii and zero height.
+ * Equivalent to {@code new Ellipse(xRadius, zRadius, 0)}.
+ *
+ * @param xRadius the semi-axis length along the X axis; clamped to at least {@link Shape#EPSILON}
+ * @param zRadius the semi-axis length along the Z axis; clamped to at least {@link Shape#EPSILON}
+ */
public Ellipse(double xRadius, double zRadius) {
this(xRadius, zRadius, 0);
}
+ /**
+ * Constructs a (possibly extruded) ellipse. When {@code height} is zero the result is a flat
+ * ellipse in the XZ plane. When {@code height} is positive the outline consists of a vertical
+ * ellipse ring extruded upward, the surface is a closed cylinder, and the fill is a solid
+ * elliptical prism.
+ *
+ * @param xRadius the semi-axis length along the X axis; clamped to at least {@link Shape#EPSILON}
+ * @param zRadius the semi-axis length along the Z axis; clamped to at least {@link Shape#EPSILON}
+ * @param height the extrusion distance along the Y axis; clamped to at least {@code 0}
+ */
public Ellipse(double xRadius, double zRadius, double height) {
super();
this.xRadius = Math.max(xRadius, Shape.EPSILON);
@@ -29,22 +59,41 @@ public Ellipse(double xRadius, double zRadius, double height) {
// --- Static calculation methods ---
- private static double ellipseCircumference(double r1, double r2) {
+ static double ellipseCircumference(double r1, double r2) {
double a = Math.max(r1, r2);
double b = Math.min(r1, r2);
+ if (!(a + b > 0))
+ return 0;
double h = Math.pow(a - b, 2) / Math.pow(a + b, 2);
return Math.PI * (a + b) * (1 + 3 * h / (10 + Math.sqrt(4 - 3 * h)));
}
- public static List calculateEllipse(double r1, double r2, double density, double cutoffAngle) {
- List points = new ArrayList<>();
+ /**
+ * Appends points along the perimeter of an ellipse with semi-axes {@code r1} (X) and
+ * {@code r2} (Z), using an arc-length-adaptive angle step so that consecutive points are
+ * spaced approximately {@code density} units apart.
+ *
+ * Sampling stops when the accumulated angle reaches {@code cutoffAngle}. Pass {@code 2π}
+ * for a complete ellipse.
+ *
+ * @param points the list to which points are appended
+ * @param r1 semi-axis length along the X axis
+ * @param r2 semi-axis length along the Z axis
+ * @param density desired arc-length spacing between consecutive points
+ * @param cutoffAngle maximum sweep angle in radians ({@code 0} to {@code 2π})
+ */
+ public static void calculateEllipse(List points, double r1, double r2, double density, double cutoffAngle) {
double circumference = ellipseCircumference(r1, r2);
+ boolean full = cutoffAngle >= FULL_CIRCLE - Shape.EPSILON;
- int steps = (int) Math.round(circumference / density);
+ long steps = Math.round(circumference / density);
+ if (points instanceof ArrayList al)
+ al.ensureCapacity(points.size() + (int) Math.min(steps * Math.min(cutoffAngle, FULL_CIRCLE) / FULL_CIRCLE + 1, Integer.MAX_VALUE - 8));
double theta = 0;
double angleStep = 0;
- for (int i = 0; i < steps; i++) {
- if (theta > cutoffAngle) {
+ for (long i = 0; i < steps; i++) {
+ // a full ellipse stops before wrapping onto its first point; an arc stops once past its end
+ if (full ? theta >= FULL_CIRCLE - angleStep / 2 : theta > cutoffAngle) {
break;
}
points.add(new Vector3d(r1 * Math.cos(theta), 0, r2 * Math.sin(theta)));
@@ -53,116 +102,239 @@ public static List calculateEllipse(double r1, double r2, double densi
angleStep = density / Math.sqrt(dx * dx + dy * dy);
theta += angleStep;
}
- return points;
}
- public static Set calculateEllipticalDisc(double r1, double r2, double density, double cutoffAngle) {
- Set points = new LinkedHashSet<>();
- int steps = (int) Math.round(Math.max(r1, r2) / density);
- double r;
- for (double i = 1; i <= steps; i += 1) {
- r = i / steps;
- points.addAll(calculateEllipse(r1 * r, r2 * r, density, cutoffAngle));
+ /**
+ * Appends points filling the area of an elliptical disc (filled 2-D ellipse) by sampling
+ * concentric ellipses at uniform radial increments from the outermost radius down to zero.
+ * Each ring is generated by {@link #calculateEllipse} with proportionally scaled radii.
+ *
+ * @param points the list to which points are appended
+ * @param r1 outer semi-axis length along the X axis
+ * @param r2 outer semi-axis length along the Z axis
+ * @param density desired arc-length spacing used for both the ring step and {@link #calculateEllipse}
+ * @param cutoffAngle angular cutoff applied to each ring ({@code 2π} for a full disc)
+ */
+ public static void calculateEllipticalDisc(List points, double r1, double r2, double density, double cutoffAngle) {
+ points.add(new Vector3d(0, 0, 0));
+ int rings = segments(Math.max(r1, r2), density);
+ for (int i = 1; i <= rings; i++) {
+ double r = (double) i / rings;
+ calculateEllipse(points, r1 * r, r2 * r, density, cutoffAngle);
}
- return points;
}
- public static Set calculateCylinder(double r1, double r2, double height, double density, double cutoffAngle) {
- Set points = calculateEllipticalDisc(r1, r2, density, cutoffAngle);
- // Top disc via direct loop
- Set top = new LinkedHashSet<>();
- for (Vector3d v : points) {
- top.add(new Vector3d(v.x, height, v.z));
+ /**
+ * Appends points covering a solid elliptical cylinder: bottom disc, top disc (offset by
+ * {@code height} along Y), and the lateral wall extruded vertically between them.
+ *
+ * The bottom and top discs are generated via {@link #calculateEllipticalDisc}; the wall is
+ * generated via {@link #calculateEllipse} and then extended vertically using the inherited
+ * {@code fillVertically} helper.
+ *
+ * @param points the list to which points are appended
+ * @param r1 semi-axis along the X axis
+ * @param r2 semi-axis along the Z axis
+ * @param height extrusion distance along the Y axis
+ * @param density desired spacing between adjacent points
+ * @param cutoffAngle angular cutoff applied to discs and the elliptical wall ({@code 2π} for full)
+ */
+ public static void calculateCylinder(List points, double r1, double r2, double height, double density, double cutoffAngle) {
+ // Bottom disc
+ int discStart = points.size();
+ calculateEllipticalDisc(points, r1, r2, density, cutoffAngle);
+ int discEnd = points.size();
+ // Wall: copies of the outer ring between the two discs. The discs already contain the rings at the
+ // bottom and top, so the base ring is only generated to be copied, and is then removed.
+ calculateEllipse(points, r1, r2, density, cutoffAngle);
+ int ringEnd = points.size();
+ fillVertically(points, discEnd, height, density, false);
+ points.subList(discEnd, ringEnd).clear();
+ // Top disc - copy bottom disc at height
+ for (int i = discStart; i < discEnd; i++) {
+ Vector3d v = points.get(i);
+ points.add(new Vector3d(v.x, height, v.z));
}
- points.addAll(top);
- // Wall
- Set wall = new LinkedHashSet<>(calculateEllipse(r1, r2, density, cutoffAngle));
- fillVertically(wall, height, density);
- points.addAll(wall);
- return points;
}
// --- Generation methods ---
+ /**
+ * Generates the outline of this ellipse. For a flat ellipse ({@code height == 0}) this is just
+ * the perimeter arc. When {@code height > 0} the outline ring is extruded vertically to form a
+ * rectangular strip connecting the bottom arc to the top arc.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the desired spacing between adjacent points
+ */
@Override
- public void generateOutline(Set points, double density) {
- Set ellipse = new LinkedHashSet<>(calculateEllipse(xRadius, zRadius, density, cutoffAngle));
+ public void generateOutline(List points, double density) {
+ int start = points.size();
+ calculateEllipse(points, xRadius, zRadius, density, cutoffAngle);
if (height != 0) {
- fillVertically(ellipse, height, density);
- points.addAll(ellipse);
- } else {
- points.addAll(ellipse);
+ fillVertically(points, start, height, density);
}
}
+ /**
+ * Generates the surface of this ellipse. When {@code height == 0} the surface is the filled
+ * elliptical disc in the XZ plane. When {@code height > 0} the surface consists of the top
+ * and bottom discs plus the lateral wall, computed by {@link #calculateCylinder}.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the desired spacing between adjacent points
+ */
@Override
- public void generateSurface(Set points, double density) {
+ public void generateSurface(List points, double density) {
if (height != 0)
- points.addAll(calculateCylinder(xRadius, zRadius, height, density, cutoffAngle));
+ calculateCylinder(points, xRadius, zRadius, height, density, cutoffAngle);
else
- points.addAll(calculateEllipticalDisc(xRadius, zRadius, density, cutoffAngle));
+ calculateEllipticalDisc(points, xRadius, zRadius, density, cutoffAngle);
}
+ /**
+ * Generates a solid fill of this ellipse. For a flat ellipse ({@code height == 0}) this is
+ * identical to the surface (the filled disc). When {@code height > 0} the bottom disc is
+ * generated then extended vertically by {@code fillVertically} to produce a solid elliptical prism.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the desired spacing between adjacent points
+ */
@Override
- public void generateFilled(Set points, double density) {
- Set disc = calculateEllipticalDisc(xRadius, zRadius, density, cutoffAngle);
+ public void generateFilled(List points, double density) {
+ int start = points.size();
+ calculateEllipticalDisc(points, xRadius, zRadius, density, cutoffAngle);
if (height != 0) {
- fillVertically(disc, height, density);
- points.addAll(disc);
- } else {
- points.addAll(disc);
+ fillVertically(points, start, height, density);
}
}
+ /**
+ * Estimates the point spacing required to produce approximately {@code targetPointCount} points
+ * for the given {@link SamplingStyle}.
+ *
+ * - OUTLINE: uses Ramanujan's first approximation for the ellipse circumference divided
+ * by {@code count}
+ * - SURFACE / FILL: {@code density = sqrt(π·xRadius·zRadius / count)}, the spacing
+ * that gives the target count over the disc area
+ *
+ *
+ * @param style the sampling style (OUTLINE, SURFACE, or FILL)
+ * @param targetPointCount the desired number of output points
+ * @return the estimated point spacing to achieve the target count
+ */
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(targetPointCount, 1);
+ double fraction = Math.min(cutoffAngle, FULL_CIRCLE) / FULL_CIRCLE;
+ double arcLength = ellipseCircumference(xRadius, zRadius) * fraction;
+ double discArea = Math.PI * xRadius * zRadius * fraction;
return switch (style) {
case OUTLINE -> {
- double h = (xRadius - zRadius) * (xRadius - zRadius) / ((xRadius + zRadius) + (xRadius + zRadius));
- double circumference = Math.PI * (xRadius + zRadius) * (1 + (3 * h / (10 + Math.sqrt(4 - 3 * h))));
- yield circumference / count;
+ if (height == 0) yield arcLength / count;
+ // with a height, the outline is the wall
+ yield Math.sqrt(arcLength * height / count);
+ }
+ case SURFACE -> {
+ if (height == 0) yield Math.sqrt(discArea / count);
+ yield Math.sqrt((2 * discArea + arcLength * height) / count);
+ }
+ case FILL -> {
+ // a flat ellipse has no volume: it is filled as a disc
+ if (height == 0) yield Math.sqrt(discArea / count);
+ yield Math.cbrt(discArea * height / count);
}
- case SURFACE, FILL -> Math.sqrt((Math.PI * xRadius * zRadius) / count);
};
}
+ /**
+ * Returns {@code true} if the given point lies inside or on the boundary of this ellipse.
+ * The test first checks the normalised ellipse equation {@code (x/xRadius)² + (z/zRadius)² ≤ 1}.
+ * If the shape has height, the Y coordinate must additionally satisfy {@code 0 ≤ y ≤ height};
+ * otherwise the point must lie in the XZ plane ({@code |y| < EPSILON}).
+ *
+ * @param point the point to test in local shape space
+ * @param tolerance how far outside the exact shape still counts as contained
+ * @return {@code true} if the point is contained within the ellipse (or cylinder)
+ */
@Override
- public boolean contains(Vector3d point) {
- double nx = point.x / xRadius;
- double nz = point.z / zRadius;
- if (nx * nx + nz * nz > 1) return false;
- if (height > 0) return point.y >= 0 && point.y <= height;
- return Math.abs(point.y) < EPSILON;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ if (height > 0) {
+ if (point.y < -tolerance || point.y > height + tolerance) return false;
+ } else if (Math.abs(point.y) > tolerance) {
+ return false;
+ }
+ double nx = point.x / (xRadius + tolerance);
+ double nz = point.z / (zRadius + tolerance);
+ return nx * nx + nz * nz <= 1;
}
+ /**
+ * Returns the full diameter of the ellipse along the X axis ({@code xRadius * 2}).
+ *
+ * @return the total X-axis extent
+ */
@Override
public double getLength() { return xRadius * 2; }
+ /**
+ * Sets the X-axis semi-axis from half of {@code length}. Values below {@link Shape#EPSILON}
+ * are clamped. Invalidates the point cache.
+ *
+ * @param length the new total X-axis extent (diameter, not radius)
+ */
@Override
public void setLength(double length) {
xRadius = Math.max(length / 2, Shape.EPSILON);
invalidate();
}
+ /**
+ * Returns the full diameter of the ellipse along the Z axis ({@code zRadius * 2}).
+ *
+ * @return the total Z-axis extent
+ */
@Override
public double getWidth() { return zRadius * 2; }
+ /**
+ * Sets the Z-axis semi-axis from half of {@code width}. Values below {@link Shape#EPSILON}
+ * are clamped. Invalidates the point cache.
+ *
+ * @param width the new total Z-axis extent (diameter, not radius)
+ */
@Override
public void setWidth(double width) {
zRadius = Math.max(width / 2, Shape.EPSILON);
invalidate();
}
+ /**
+ * Returns the extrusion height along the Y axis, or {@code 0} for a flat ellipse.
+ *
+ * @return the Y-axis extrusion distance
+ */
@Override
public double getHeight() { return height; }
+ /**
+ * Sets the extrusion height along the Y axis. A value of {@code 0} produces a flat 2-D ellipse.
+ * Negative values are clamped to {@code 0}. Invalidates the point cache.
+ *
+ * @param height the new Y-axis extrusion distance
+ */
@Override
public void setHeight(double height) {
this.height = Math.max(height, 0);
invalidate();
}
+ /**
+ * Creates a deep copy of this ellipse, preserving radii, height, the inherited cutoff angle,
+ * and all {@link AbstractShape} state copied via {@link AbstractShape#copyTo(AbstractShape)}.
+ *
+ * @return a new {@link Ellipse} identical to this one
+ */
@Override
public Shape clone() {
return this.copyTo(new Ellipse(xRadius, zRadius, height));
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipsoid.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipsoid.java
index cab4100..6b7433d 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipsoid.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Ellipsoid.java
@@ -5,10 +5,21 @@
import org.joml.Quaterniond;
import org.joml.Vector3d;
-import java.util.LinkedHashSet;
+import java.util.ArrayList;
import java.util.List;
-import java.util.Set;
+/**
+ * A 3-D ellipsoid defined by three independent semi-axis radii along the X, Y, and Z axes.
+ *
+ * Outline sampling produces the three principal great-circle ellipses (XZ, XY, YZ planes).
+ * Surface sampling generates a latitude-strip decomposition: the longest horizontal cross-section
+ * ellipse (XZ or XY/YZ depending on which radius is larger) is used as the profile, and rings
+ * at each latitude are computed from the ellipsoid equation. Filled sampling nests concentric
+ * scaled ellipsoids to fill the interior.
+ *
+ * A point {@code (x, y, z)} is inside the ellipsoid when
+ * {@code (x/xRadius)² + (y/yRadius)² + (z/zRadius)² ≤ 1}.
+ */
public class Ellipsoid extends AbstractShape implements LWHShape {
private static final Quaterniond XY_ROTATION = new Quaterniond().rotateX(Math.PI / 2);
@@ -17,6 +28,14 @@ public class Ellipsoid extends AbstractShape implements LWHShape {
protected double yRadius;
protected double zRadius;
+ /**
+ * Constructs an ellipsoid with the given semi-axis lengths. Each radius is clamped to at
+ * least {@link Shape#EPSILON} to prevent degenerate geometry.
+ *
+ * @param xRadius semi-axis length along the X axis
+ * @param yRadius semi-axis length along the Y axis
+ * @param zRadius semi-axis length along the Z axis
+ */
public Ellipsoid(double xRadius, double yRadius, double zRadius) {
super();
this.xRadius = Math.max(xRadius, Shape.EPSILON);
@@ -24,67 +43,104 @@ public Ellipsoid(double xRadius, double yRadius, double zRadius) {
this.zRadius = Math.max(zRadius, Shape.EPSILON);
}
+ /**
+ * Generates the wireframe outline of the ellipsoid: three full great-circle ellipses in the
+ * XZ (horizontal), XY, and YZ planes. The XY and YZ ellipses are rotated into position using
+ * pre-computed quaternion constants so they lie correctly in their respective planes.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the desired spacing between adjacent points along each ellipse
+ */
@Override
- public void generateOutline(Set points, double density) {
- points.addAll(Ellipse.calculateEllipse(xRadius, zRadius, density, 2 * Math.PI));
- points.addAll(VectorUtil.transform(XY_ROTATION, Ellipse.calculateEllipse(xRadius, yRadius, density, 2 * Math.PI)));
- points.addAll(VectorUtil.transform(ZY_ROTATION, Ellipse.calculateEllipse(yRadius, zRadius, density, 2 * Math.PI)));
+ public void generateOutline(List points, double density) {
+ Ellipse.calculateEllipse(points, xRadius, zRadius, density, 2 * Math.PI);
+ int start = points.size();
+ Ellipse.calculateEllipse(points, xRadius, yRadius, density, 2 * Math.PI);
+ VectorUtil.transform(XY_ROTATION, points, start);
+ start = points.size();
+ Ellipse.calculateEllipse(points, yRadius, zRadius, density, 2 * Math.PI);
+ VectorUtil.transform(ZY_ROTATION, points, start);
}
+ /**
+ * Generates points covering the surface of the ellipsoid using a latitude-strip approach.
+ * The longest in-plane cross-section ellipse (XY or YZ depending on whether {@code xRadius >
+ * zRadius}) is used as the profile from which latitude angles are derived. At each latitude
+ * a horizontal ring scaled by {@code cos(θ)} is added, along with its mirror below the equator.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the desired spacing between adjacent points
+ */
@Override
- public void generateSurface(Set points, double density) {
- List ellipse;
+ public void generateSurface(List points, double density) {
+ List ellipse = new ArrayList<>();
if (xRadius > zRadius) {
- ellipse = VectorUtil.transform(XY_ROTATION, Ellipse.calculateEllipse(xRadius, yRadius, density, 2 * Math.PI));
+ Ellipse.calculateEllipse(ellipse, xRadius, yRadius, density, 2 * Math.PI);
+ VectorUtil.transform(XY_ROTATION, ellipse);
} else {
- ellipse = VectorUtil.transform(ZY_ROTATION, Ellipse.calculateEllipse(yRadius, zRadius, density, 2 * Math.PI));
+ Ellipse.calculateEllipse(ellipse, yRadius, zRadius, density, 2 * Math.PI);
+ VectorUtil.transform(ZY_ROTATION, ellipse);
}
- points.addAll(generateEllipsoid(ellipse, 1, density));
+ generateEllipsoid(points, ellipse, 1, density);
}
+ /**
+ * Generates points filling the interior of the ellipsoid by nesting concentric scaled copies
+ * of the surface, stepping the scale factor from 1 down to 0. Each scaled shell is generated
+ * by the same latitude-strip method used in {@link #generateSurface}, applied to a proportionally
+ * scaled version of the radii.
+ *
+ * @param points the list to which generated points are appended
+ * @param density the desired spacing between adjacent points
+ */
@Override
- public void generateFilled(Set points, double density) {
- List ellipse;
+ public void generateFilled(List points, double density) {
double radius = Math.max(xRadius, zRadius);
int steps = (int) Math.round(radius / density);
+ List ellipse = new ArrayList<>();
for (int i = steps; i > 0; i--) {
double r = (i / (double) steps);
+ ellipse.clear();
if (xRadius > zRadius) {
- ellipse = VectorUtil.transform(XY_ROTATION, Ellipse.calculateEllipse(xRadius * r, yRadius * r, density, 2 * Math.PI));
+ Ellipse.calculateEllipse(ellipse, xRadius * r, yRadius * r, density, 2 * Math.PI);
+ VectorUtil.transform(XY_ROTATION, ellipse);
} else {
- ellipse = VectorUtil.transform(ZY_ROTATION, Ellipse.calculateEllipse(yRadius * r, zRadius * r, density, 2 * Math.PI));
+ Ellipse.calculateEllipse(ellipse, yRadius * r, zRadius * r, density, 2 * Math.PI);
+ VectorUtil.transform(ZY_ROTATION, ellipse);
}
- points.addAll(generateEllipsoid(ellipse, r, density));
+ generateEllipsoid(points, ellipse, r, density);
}
}
- private Set generateEllipsoid(List ellipse, double radius, double density) {
- Set points = new LinkedHashSet<>();
+ private void generateEllipsoid(List points, List ellipse, double radius, double density) {
for (int i = 0; i < Math.ceil(ellipse.size() / 4.0); i++) {
double y = ellipse.get(i).y;
- double theta = Math.asin(y / (yRadius * radius));
- for (Vector3d v2 : Ellipse.calculateEllipse(radius * xRadius * Math.cos(theta), radius * zRadius * Math.cos(theta), density, 2 * Math.PI)) {
- points.add(new Vector3d(v2.x, y, v2.z));
- points.add(new Vector3d(v2.x, -y, v2.z));
+ // the equator is added once, after the loop
+ if (Math.abs(y) <= EPSILON)
+ continue;
+ double theta = Math.asin(Math.clamp(y / (yRadius * radius), -1.0, 1.0));
+ // Add ring points, setting y in-place and adding mirrored copies
+ int ringStart = points.size();
+ Ellipse.calculateEllipse(points, radius * xRadius * Math.cos(theta), radius * zRadius * Math.cos(theta), density, 2 * Math.PI);
+ int ringEnd = points.size();
+ for (int j = ringStart; j < ringEnd; j++) {
+ Vector3d v = points.get(j);
+ v.y = y;
+ if (Math.abs(y) > EPSILON) {
+ points.add(new Vector3d(v.x, -y, v.z));
+ }
}
}
- points.addAll(Ellipse.calculateEllipse(radius * xRadius, radius * zRadius, density, 2 * Math.PI));
- return points;
+ Ellipse.calculateEllipse(points, radius * xRadius, radius * zRadius, density, 2 * Math.PI);
}
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(targetPointCount, 1);
return switch (style) {
- case OUTLINE -> {
- double h = (xRadius - yRadius) * (xRadius - yRadius) / ((xRadius + yRadius) + (xRadius + yRadius));
- double circumferenceXY = Math.PI * (xRadius + yRadius) * (1 + (3 * h / (10 + Math.sqrt(4 - 3 * h))));
- h = (xRadius - zRadius) * (xRadius - zRadius) / ((xRadius + zRadius) + (xRadius + zRadius));
- double circumferenceXZ = Math.PI * (xRadius + zRadius) * (1 + (3 * h / (10 + Math.sqrt(4 - 3 * h))));
- h = (yRadius - zRadius) * (yRadius - zRadius) / ((yRadius + zRadius) + (yRadius + zRadius));
- double circumferenceYZ = Math.PI * (yRadius + zRadius) * (1 + (3 * h / (10 + Math.sqrt(4 - 3 * h))));
- yield (circumferenceXY + circumferenceXZ + circumferenceYZ) / count;
- }
+ case OUTLINE -> (Ellipse.ellipseCircumference(xRadius, yRadius)
+ + Ellipse.ellipseCircumference(xRadius, zRadius)
+ + Ellipse.ellipseCircumference(yRadius, zRadius)) / count;
case SURFACE -> {
double surfaceArea = 4 * Math.PI * Math.pow((Math.pow(xRadius * yRadius, 1.6) + Math.pow(xRadius * zRadius, 1.6) + Math.pow(zRadius * yRadius, 1.6)) / 3, 1 / 1.6);
yield Math.sqrt(surfaceArea / count);
@@ -97,10 +153,10 @@ public double computeDensity(SamplingStyle style, int targetPointCount) {
}
@Override
- public boolean contains(Vector3d point) {
- double nx = point.x / xRadius;
- double ny = point.y / yRadius;
- double nz = point.z / zRadius;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ double nx = point.x / (xRadius + tolerance);
+ double ny = point.y / (yRadius + tolerance);
+ double nz = point.z / (zRadius + tolerance);
return nx * nx + ny * ny + nz * nz <= 1;
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/EllipticalArc.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/EllipticalArc.java
index faa7541..167567e 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/EllipticalArc.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/EllipticalArc.java
@@ -1,8 +1,9 @@
package com.sovdee.shapes.shapes;
+import com.sovdee.shapes.sampling.SamplingStyle;
import org.joml.Vector3d;
-import java.util.Set;
+import java.util.List;
public class EllipticalArc extends Ellipse implements CutoffShape {
@@ -16,10 +17,18 @@ public EllipticalArc(double xRadius, double zRadius, double height, double cutof
}
@Override
- public void generateSurface(Set points, double density) {
+ public void generateSurface(List points, double density) {
generateFilled(points, density);
}
+ /**
+ * The surface of an arc is drawn filled, so its density is estimated the same way.
+ */
+ @Override
+ public double computeDensity(SamplingStyle style, int targetPointCount) {
+ return super.computeDensity(style == SamplingStyle.SURFACE ? SamplingStyle.FILL : style, targetPointCount);
+ }
+
@Override
public double getCutoffAngle() {
return cutoffAngle;
@@ -32,11 +41,18 @@ public void setCutoffAngle(double cutoffAngle) {
}
@Override
- public boolean contains(Vector3d point) {
- if (!super.contains(point)) return false;
- double angle = Math.atan2(point.z, point.x);
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ if (!super.containsLocal(point, tolerance)) return false;
+ if (cutoffAngle >= Math.PI * 2 - EPSILON) return true;
+ double distance = Math.sqrt(point.x * point.x + point.z * point.z);
+ // the axis itself belongs to every sector
+ if (distance <= tolerance) return true;
+ // the cutoff of an elliptical arc is a parametric angle, so compare in the unit circle's space
+ double angle = Math.atan2(point.z / (getWidth() / 2), point.x / (getLength() / 2));
if (angle < 0) angle += 2 * Math.PI;
- return angle <= cutoffAngle;
+ // allow the tolerance, as an angle at this distance, on either side of the sector
+ double slack = tolerance / distance;
+ return angle <= cutoffAngle + slack || angle >= 2 * Math.PI - slack;
}
@Override
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Heart.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Heart.java
index a82ff16..93e2e84 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Heart.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Heart.java
@@ -1,10 +1,11 @@
package com.sovdee.shapes.shapes;
import com.sovdee.shapes.sampling.SamplingStyle;
+import com.sovdee.shapes.util.VectorUtil;
import org.joml.Vector3d;
-import java.util.LinkedHashSet;
-import java.util.Set;
+import java.util.ArrayList;
+import java.util.List;
public class Heart extends AbstractShape implements LWHShape {
@@ -19,48 +20,72 @@ public Heart(double length, double width, double eccentricity) {
this.eccentricity = Math.max(eccentricity, 1);
}
- private static Set calculateHeart(double length, double width, double eccentricity, double density) {
- Set points = new LinkedHashSet<>();
- double angleStep = 4 / 3.0 * density / (width + length);
- for (double theta = 0; theta < Math.PI * 2; theta += angleStep) {
- double x = width * Math.pow(Math.sin(theta), 3);
- double y = length * (Math.cos(theta) - 1 / eccentricity * Math.cos(2 * theta) - 1.0 / 6 * Math.cos(3 * theta) - 1.0 / 16 * Math.cos(4 * theta));
- points.add(new Vector3d(x, 0, y));
+ private static void calculateHeart(List points, double length, double width, double eccentricity, double density) {
+ int steps = Math.max(segments(Math.PI * 2 * (width + length) * 3 / 4, density), 3);
+ if (points instanceof ArrayList al)
+ al.ensureCapacity(points.size() + steps);
+ for (int i = 0; i < steps; i++) {
+ points.add(heartPoint(length, width, eccentricity, Math.PI * 2 * i / steps));
}
- return points;
+ }
+
+ /**
+ * @return the point on the heart curve at the given parametric angle
+ */
+ private static Vector3d heartPoint(double length, double width, double eccentricity, double theta) {
+ double x = width * Math.pow(Math.sin(theta), 3);
+ double y = length * (Math.cos(theta) - 1 / eccentricity * Math.cos(2 * theta) - 1.0 / 6 * Math.cos(3 * theta) - 1.0 / 16 * Math.cos(4 * theta));
+ return new Vector3d(x, 0, y);
+ }
+
+ /**
+ * Traces the outline of this heart as a closed polygon.
+ *
+ * @param resolution the number of vertices
+ */
+ List outlinePolygon(int resolution) {
+ List polygon = new ArrayList<>(resolution);
+ for (int i = 0; i < resolution; i++) {
+ polygon.add(heartPoint(length / 2, width / 2, eccentricity, Math.PI * 2 * i / resolution));
+ }
+ return polygon;
}
@Override
- public void generateOutline(Set points, double density) {
- points.addAll(calculateHeart(length / 2, width / 2, eccentricity, density));
+ public void generateOutline(List points, double density) {
+ calculateHeart(points, length / 2, width / 2, eccentricity, density);
}
@Override
- public void generateSurface(Set points, double density) {
+ public void generateSurface(List points, double density) {
for (double w = width, l = length; w > 0 && l > 0; w -= density * 1.5, l -= density * 1.5) {
- points.addAll(calculateHeart(l / 2, w / 2, eccentricity, density));
+ calculateHeart(points, l / 2, w / 2, eccentricity, density);
}
}
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
- return 0.25; // No good formula available
+ int count = Math.max(targetPointCount, 1);
+ return switch (style) {
+ // the outline is stepped by angle, at this many points per unit of density
+ case OUTLINE -> Math.PI * 2 * (width / 2 + length / 2) * 3 / 4 / count;
+ case SURFACE, FILL -> {
+ // The surface is drawn as concentric outlines 1.5 densities apart, shrinking to nothing,
+ // so on average each has half the points of the outermost one.
+ double outline = Math.PI * 2 * (width / 2 + length / 2) * 3 / 4;
+ double rings = Math.min(width, length) / 1.5;
+ yield Math.sqrt(outline * rings / 2 / count);
+ }
+ };
}
@Override
- public boolean contains(Vector3d point) {
- // Approximate: check if point is within parametric heart boundary
- if (Math.abs(point.y) > EPSILON) return false;
- double x = point.x;
- double z = point.z;
- double hw = width / 2;
- double hl = length / 2;
- if (hw < EPSILON || hl < EPSILON) return false;
- // Normalize and check parametric distance
- double nx = x / hw;
- double nz = z / hl;
- // Simple bounding check
- return nx * nx + nz * nz <= 4;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ if (Math.abs(point.y) > tolerance) return false;
+ // Approximate: test against the outline traced as a polygon
+ List outline = outlinePolygon(256);
+ return VectorUtil.isInPolygonXZ(outline, point.x, point.z)
+ || VectorUtil.isNearPolygonXZ(outline, point.x, point.z, tolerance);
}
@Override
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Helix.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Helix.java
index 4062b1e..9ed9256 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Helix.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Helix.java
@@ -3,8 +3,8 @@
import com.sovdee.shapes.sampling.SamplingStyle;
import org.joml.Vector3d;
-import java.util.LinkedHashSet;
-import java.util.Set;
+import java.util.ArrayList;
+import java.util.List;
public class Helix extends AbstractShape implements RadialShape, LWHShape {
@@ -30,52 +30,62 @@ public Helix(double radius, double height, double slope, int direction) {
this.direction = direction;
}
- private static Set calculateHelix(double radius, double height, double slope, int direction, double density) {
- Set points = new LinkedHashSet<>();
+ private static void calculateHelix(List points, double radius, double height, double slope, int direction, double density) {
if (radius <= 0 || height <= 0) {
- return points;
+ return;
}
- double loops = Math.abs(height / slope);
- double length = slope * slope + radius * radius;
- double stepSize = density / length;
- for (double t = 0; t < loops; t += stepSize) {
+ // the helix is parameterised by its angle: one radian covers this much arc length
+ double totalAngle = Math.abs(height / slope);
+ double lengthPerRadian = Math.sqrt(slope * slope + radius * radius);
+ int steps = segments(totalAngle * lengthPerRadian, density);
+ if (points instanceof ArrayList al)
+ al.ensureCapacity(points.size() + steps + 1);
+ for (int i = 0; i <= steps; i++) {
+ double t = totalAngle * i / steps;
double x = radius * Math.cos(direction * t);
double z = radius * Math.sin(direction * t);
points.add(new Vector3d(x, t * slope, z));
}
- return points;
}
@Override
- public void generateOutline(Set points, double density) {
- points.addAll(calculateHelix(radius, height, slope, direction, density));
+ public void generateOutline(List points, double density) {
+ calculateHelix(points, radius, height, slope, direction, density);
}
@Override
- public void generateSurface(Set points, double density) {
- for (double r = radius; r > 0; r -= density) {
- points.addAll(calculateHelix(r, height, slope, direction, density));
+ public void generateSurface(List points, double density) {
+ int rings = segments(radius, density);
+ for (int i = rings; i >= 1; i--) {
+ calculateHelix(points, radius * i / rings, height, slope, direction, density);
}
}
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(targetPointCount, 1);
+ double totalAngle = height / slope;
return switch (style) {
- case OUTLINE -> Math.sqrt(slope * slope + radius * radius) * (height / slope) / count;
- case FILL, SURFACE -> Math.sqrt(slope * slope + radius * radius * (height / slope) / count);
+ case OUTLINE -> Math.sqrt(slope * slope + radius * radius) * totalAngle / count;
+ case FILL, SURFACE -> {
+ // area of the helicoid swept between the axis and the helix
+ double area = totalAngle * 0.5 * (radius * Math.sqrt(slope * slope + radius * radius)
+ + slope * slope * Math.log((radius + Math.sqrt(slope * slope + radius * radius)) / slope));
+ yield Math.sqrt(area / count);
+ }
};
}
@Override
- public boolean contains(Vector3d point) {
- // Approximate: check distance to nearest helix point
- if (point.y < 0 || point.y > height) return false;
- double t = point.y / slope;
- double helixX = radius * Math.cos(direction * t);
- double helixZ = radius * Math.sin(direction * t);
- double dist = Math.sqrt((point.x - helixX) * (point.x - helixX) + (point.z - helixZ) * (point.z - helixZ));
- return dist <= EPSILON;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ // Approximate: compare against the point of the helix at the same height
+ if (point.y < -tolerance || point.y > height + tolerance) return false;
+ double y = Math.clamp(point.y, 0.0, height);
+ double t = y / slope;
+ double dx = point.x - radius * Math.cos(direction * t);
+ double dz = point.z - radius * Math.sin(direction * t);
+ double dy = point.y - y;
+ return dx * dx + dy * dy + dz * dz <= tolerance * tolerance;
}
public double getSlope() { return slope; }
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/IrregularPolygon.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/IrregularPolygon.java
index 1a6092c..b041b30 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/IrregularPolygon.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/IrregularPolygon.java
@@ -1,13 +1,13 @@
package com.sovdee.shapes.shapes;
import com.sovdee.shapes.sampling.SamplingStyle;
+import com.sovdee.shapes.util.VectorUtil;
import org.joml.Vector3d;
import java.util.ArrayList;
import java.util.Collection;
-import java.util.LinkedHashSet;
import java.util.List;
-import java.util.Set;
+
public class IrregularPolygon extends AbstractShape implements LWHShape {
@@ -46,17 +46,25 @@ private void setBounds(Collection vertices) {
}
@Override
- public void generateOutline(Set points, double density) {
- points.addAll(Line.connectPoints(vertices, density));
- points.addAll(Line.calculateLine(vertices.get(0), vertices.get(vertices.size() - 1), density));
+ public void generateOutline(List points, double density) {
+ int start = points.size();
+ // one edge per vertex, each without its end point, so every vertex appears exactly once
+ int count = vertices.size();
+ for (int i = 0; i < count; i++) {
+ Line.calculateLine(points, vertices.get(i), vertices.get((i + 1) % count), density, false);
+ }
if (height != 0) {
- Set upperPoints = new LinkedHashSet<>();
- for (Vector3d v : points) {
- upperPoints.add(new Vector3d(v.x, height, v.z));
+ int end = points.size();
+ for (int i = start; i < end; i++) {
+ Vector3d v = points.get(i);
+ points.add(new Vector3d(v.x, height, v.z));
}
- points.addAll(upperPoints);
+ // vertical edges, without the vertices that the two outlines already contain
+ int layers = segments(height, density);
for (Vector3d v : vertices) {
- points.addAll(Line.calculateLine(v, new Vector3d(v.x, height, v.z), density));
+ for (int layer = 1; layer < layers; layer++) {
+ points.add(new Vector3d(v.x, height * layer / layers, v.z));
+ }
}
}
}
@@ -65,31 +73,24 @@ public void generateOutline(Set points, double density) {
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(targetPointCount, 1);
double perimeter = 0;
- for (int i = 0; i < vertices.size() - 1; i++) {
- perimeter += vertices.get(i).distance(vertices.get(i + 1));
+ for (int i = 0; i < vertices.size(); i++) {
+ perimeter += vertices.get(i).distance(vertices.get((i + 1) % vertices.size()));
}
- perimeter += vertices.get(0).distance(vertices.get(vertices.size() - 1));
- perimeter *= 2;
- perimeter += vertices.size() * height;
- return perimeter / count;
+ if (height == 0)
+ return perimeter / count;
+ // both outlines plus one vertical edge per vertex
+ return (2 * perimeter + vertices.size() * height) / count;
}
@Override
- public boolean contains(Vector3d point) {
- if (height > 0 && (point.y < 0 || point.y > height)) return false;
- if (height == 0 && Math.abs(point.y) > EPSILON) return false;
- // Ray casting algorithm on XZ plane
- int n = vertices.size();
- boolean inside = false;
- for (int i = 0, j = n - 1; i < n; j = i++) {
- double xi = vertices.get(i).x, zi = vertices.get(i).z;
- double xj = vertices.get(j).x, zj = vertices.get(j).z;
- if ((zi > point.z) != (zj > point.z) &&
- point.x < (xj - xi) * (point.z - zi) / (zj - zi) + xi) {
- inside = !inside;
- }
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ if (height > 0) {
+ if (point.y < -tolerance || point.y > height + tolerance) return false;
+ } else if (Math.abs(point.y) > tolerance) {
+ return false;
}
- return inside;
+ return VectorUtil.isInPolygonXZ(vertices, point.x, point.z)
+ || VectorUtil.isNearPolygonXZ(vertices, point.x, point.z, tolerance);
}
@Override
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/LWHShape.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/LWHShape.java
index 54ce72a..829bb6f 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/LWHShape.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/LWHShape.java
@@ -4,10 +4,49 @@
* Represents a shape that has a length, width, and/or height.
*/
public interface LWHShape extends Shape {
+
+ /**
+ * Returns the length of this shape along its primary axis (typically X).
+ * Not all implementors use all three dimensions; those that do not use length may return {@code 0}.
+ *
+ * @return the length, in the shape's local units
+ */
double getLength();
+
+ /**
+ * Sets the length of this shape along its primary axis.
+ *
+ * @param length the new length, in the shape's local units
+ */
void setLength(double length);
+
+ /**
+ * Returns the width of this shape (typically along the Z axis).
+ * Not all implementors use all three dimensions; those that do not use width may return {@code 0}.
+ *
+ * @return the width, in the shape's local units
+ */
double getWidth();
+
+ /**
+ * Sets the width of this shape.
+ *
+ * @param width the new width, in the shape's local units
+ */
void setWidth(double width);
+
+ /**
+ * Returns the height of this shape (typically along the Y axis).
+ * A height of {@code 0} collapses the shape to a flat, 2-D cross-section.
+ *
+ * @return the height, in the shape's local units
+ */
double getHeight();
+
+ /**
+ * Sets the height of this shape. A value of {@code 0} collapses the shape to a 2-D cross-section.
+ *
+ * @param height the new height, in the shape's local units; must be {@code >= 0}
+ */
void setHeight(double height);
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Line.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Line.java
index 7c830d4..bf39fb7 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Line.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Line.java
@@ -1,172 +1,361 @@
package com.sovdee.shapes.shapes;
import com.sovdee.shapes.sampling.SamplingStyle;
+import com.sovdee.shapes.util.VectorUtil;
import org.joml.Vector3d;
-import java.util.LinkedHashSet;
+import java.util.ArrayList;
import java.util.List;
-import java.util.Set;
import java.util.function.Supplier;
/**
- * A line shape defined by two vector endpoints.
- * Supports both static endpoints and dynamic suppliers for entity-following.
+ * A straight-line segment defined by two vector endpoints, lying along the direction from start
+ * to end. The line implements {@link LWHShape} where only {@code length} (the distance between
+ * the endpoints) is meaningful; {@code width} and {@code height} always return {@code 0}.
+ *
+ * Both static and dynamic (supplier-based) endpoints are supported. Dynamic lines automatically
+ * mark themselves as {@link AbstractShape#isDynamic() dynamic} so the point cache is invalidated
+ * every frame.
+ *
*/
public class Line extends AbstractShape implements LWHShape {
+ // The current endpoints. For a dynamic line these are the values last read from the suppliers.
+ private final Vector3d start = new Vector3d();
+ private final Vector3d end = new Vector3d();
private Supplier startSupplier;
private Supplier endSupplier;
+ /**
+ * Constructs a line from the origin {@code (0, 0, 0)} to the given endpoint.
+ *
+ * @param end the far endpoint of the line; must differ from the origin
+ */
public Line(Vector3d end) {
this(new Vector3d(0, 0, 0), end);
}
+ /**
+ * Constructs a static line between two explicit endpoints.
+ * The supplied vectors are copied so subsequent external mutations do not affect this shape.
+ *
+ * @param start the starting endpoint
+ * @param end the ending endpoint; must differ from {@code start}
+ * @throws IllegalArgumentException if {@code start} equals {@code end}
+ */
public Line(Vector3d start, Vector3d end) {
super();
if (start.equals(end))
throw new IllegalArgumentException("Start and end locations cannot be the same.");
- final Vector3d s = new Vector3d(start);
- final Vector3d e = new Vector3d(end);
- this.startSupplier = () -> new Vector3d(s);
- this.endSupplier = () -> new Vector3d(e);
+ this.start.set(start);
+ this.end.set(end);
}
+ /**
+ * Constructs a dynamic line whose endpoints are resolved fresh each frame via suppliers.
+ * This variant marks the shape as {@link AbstractShape#isDynamic() dynamic} so points are
+ * regenerated every draw call (useful for entity-following lines).
+ *
+ * @param start a supplier that returns the current start position
+ * @param end a supplier that returns the current end position
+ */
public Line(Supplier start, Supplier end) {
super();
this.startSupplier = start;
this.endSupplier = end;
+ this.start.set(start.get());
+ this.end.set(end.get());
setDynamic(true);
}
/**
- * Calculates points along a line from start to end with the given density.
+ * Copies the endpoints and suppliers of another line without re-reading the suppliers,
+ * so the copy describes exactly the same geometry as the original.
+ */
+ private Line(Line line) {
+ super();
+ this.start.set(line.start);
+ this.end.set(line.end);
+ this.startSupplier = line.startSupplier;
+ this.endSupplier = line.endSupplier;
+ }
+
+ /**
+ * Calculates points along a line from start to end with the given density,
+ * adding them directly to the provided list.
*/
- public static Set calculateLine(Vector3d start, Vector3d end, double density) {
- Set points = new LinkedHashSet<>();
- Vector3d direction = new Vector3d(end).sub(start);
- double length = direction.length();
- double step = length / Math.round(length / density);
- direction.normalize().mul(step);
+ public static void calculateLine(List points, Vector3d start, Vector3d end, double density) {
+ calculateLine(points, start, end, density, true);
+ }
- Vector3d current = new Vector3d(start);
- int count = (int) (length / step);
- for (int i = 0; i <= count; i++) {
- points.add(new Vector3d(current));
- current.add(direction);
+ /**
+ * Appends evenly spaced points along the segment from {@code start} to {@code end}, roughly
+ * {@code density} apart. The start point is always included.
+ *
+ * @param points the list to append the generated points to
+ * @param start the start of the segment
+ * @param end the end of the segment
+ * @param density the desired spacing between consecutive points
+ * @param includeEnd whether to include the end point. Pass {@code false} when chaining segments,
+ * so shared corners are not generated twice.
+ */
+ public static void calculateLine(List points, Vector3d start, Vector3d end, double density, boolean includeEnd) {
+ double length = start.distance(end);
+ if (!(length > 0)) {
+ // a degenerate segment is a single point
+ if (includeEnd)
+ points.add(new Vector3d(start));
+ return;
+ }
+ int segments = segments(length, density);
+ int last = includeEnd ? segments : segments - 1;
+ if (points instanceof ArrayList al)
+ al.ensureCapacity(points.size() + last + 1);
+ for (int i = 0; i <= last; i++) {
+ points.add(new Vector3d(start).lerp(end, (double) i / segments));
}
- return points;
}
/**
- * Connects a list of points with lines, returning all intermediate points.
+ * Connects a list of control points with lines, adding all intermediate points
+ * directly to the provided list. Duplicate points at junctions are removed.
*/
- public static Set connectPoints(List points, double density) {
- Set connectedPoints = new LinkedHashSet<>();
- for (int i = 0; i < points.size() - 1; i++) {
- connectedPoints.addAll(calculateLine(points.get(i), points.get(i + 1), density));
+ public static void connectPoints(List result, List controlPoints, double density) {
+ int last = controlPoints.size() - 2;
+ for (int i = 0; i <= last; i++) {
+ // only the final segment contributes its end point, so each junction appears once
+ calculateLine(result, controlPoints.get(i), controlPoints.get(i + 1), density, i == last);
}
- return connectedPoints;
}
+ /**
+ * Re-reads the endpoint suppliers, if any, and invalidates the line when an endpoint moved.
+ */
+ @Override
+ public void refresh() {
+ boolean changed = false;
+ if (startSupplier != null) {
+ Vector3d value = startSupplier.get();
+ if (!start.equals(value)) {
+ start.set(value);
+ changed = true;
+ }
+ }
+ if (endSupplier != null) {
+ Vector3d value = endSupplier.get();
+ if (!end.equals(value)) {
+ end.set(value);
+ changed = true;
+ }
+ }
+ if (changed)
+ invalidate();
+ }
+
+ /**
+ * Generates outline points along the line from start to end at the given density.
+ * Delegates to {@link #calculateLine(List, Vector3d, Vector3d, double)}.
+ *
+ * @param points the list to which sampled points are appended
+ * @param density the approximate spacing between consecutive points
+ */
@Override
- public void generateOutline(Set points, double density) {
- points.addAll(calculateLine(getStart(), getEnd(), density));
+ public void generateOutline(List points, double density) {
+ calculateLine(points, start, end, density);
}
+ /**
+ * Returns the current start position by invoking the start supplier.
+ *
+ * @return the start endpoint vector (a fresh copy for dynamic lines)
+ */
public Vector3d getStart() {
- return startSupplier.get();
+ refresh();
+ return new Vector3d(start);
}
+ /**
+ * Sets a new static start endpoint. The vector is copied internally so subsequent
+ * external mutations do not affect this shape. Invalidates the point cache.
+ *
+ * @param start the new start position
+ */
public void setStart(Vector3d start) {
- final Vector3d s = new Vector3d(start);
- this.startSupplier = () -> new Vector3d(s);
+ this.start.set(start);
+ this.startSupplier = null;
+ setDynamic(endSupplier != null);
invalidate();
}
+ /**
+ * Returns the current end position by invoking the end supplier.
+ *
+ * @return the end endpoint vector (a fresh copy for dynamic lines)
+ */
public Vector3d getEnd() {
- return endSupplier.get();
+ refresh();
+ return new Vector3d(end);
}
+ /**
+ * Sets a new static end endpoint. The vector is copied internally so subsequent
+ * external mutations do not affect this shape. Invalidates the point cache.
+ *
+ * @param end the new end position
+ */
public void setEnd(Vector3d end) {
- final Vector3d e = new Vector3d(end);
- this.endSupplier = () -> new Vector3d(e);
+ this.end.set(end);
+ this.endSupplier = null;
+ setDynamic(startSupplier != null);
invalidate();
}
+ /**
+ * Returns the raw supplier used to resolve the start position each frame.
+ *
+ * @return the start {@link Supplier}
+ */
public Supplier getStartSupplier() {
return startSupplier;
}
+ /**
+ * Replaces the start supplier without invalidating the point cache.
+ * Intended for dynamic-line bookkeeping; prefer {@link #setStart(Vector3d)} for
+ * static updates that should trigger re-sampling.
+ *
+ * @param startSupplier the new start supplier
+ */
public void setStartSupplier(Supplier startSupplier) {
this.startSupplier = startSupplier;
+ setDynamic(startSupplier != null || endSupplier != null);
}
+ /**
+ * Returns the raw supplier used to resolve the end position each frame.
+ *
+ * @return the end {@link Supplier}
+ */
public Supplier getEndSupplier() {
return endSupplier;
}
+ /**
+ * Replaces the end supplier without invalidating the point cache.
+ * Intended for dynamic-line bookkeeping; prefer {@link #setEnd(Vector3d)} for
+ * static updates that should trigger re-sampling.
+ *
+ * @param endSupplier the new end supplier
+ */
public void setEndSupplier(Supplier endSupplier) {
this.endSupplier = endSupplier;
+ setDynamic(startSupplier != null || endSupplier != null);
}
+ /**
+ * Computes the inter-point density required to distribute {@code targetPointCount} points
+ * evenly along the line. Density equals {@code length / targetPointCount}.
+ *
+ * @param style ignored; a line has no surface or fill variant
+ * @param targetPointCount the desired number of sampled points
+ * @return the spacing between consecutive points
+ */
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
- int count = Math.max(targetPointCount, 1);
- return new Vector3d(getEnd()).sub(getStart()).length() / count;
+ // n segments produce n + 1 points
+ int segments = Math.max(targetPointCount - 1, 1);
+ return getLength() / segments;
}
+ /**
+ * Returns {@code true} if {@code point} lies on the line segment within {@link #EPSILON}
+ * tolerance. Uses parametric projection: {@code t = (point-start)·(end-start) / |end-start|²},
+ * then checks that the closest point on the segment equals {@code point}.
+ *
+ * @param point the point to test
+ * @param tolerance how far outside the exact shape still counts as contained
+ * @return {@code true} if the point is on the segment
+ */
@Override
- public boolean contains(Vector3d point) {
- Vector3d start = getStart();
- Vector3d end = getEnd();
- Vector3d line = new Vector3d(end).sub(start);
- double len = line.length();
- if (len < EPSILON) return point.distance(start) < EPSILON;
- Vector3d toPoint = new Vector3d(point).sub(start);
- double t = toPoint.dot(line) / (len * len);
- if (t < 0 || t > 1) return false;
- Vector3d closest = new Vector3d(start).add(new Vector3d(line).mul(t));
- return point.distance(closest) <= EPSILON;
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ return VectorUtil.distanceToSegmentSquared(point, start, end) <= tolerance * tolerance;
}
+ /**
+ * Returns the Euclidean distance between the start and end endpoints.
+ *
+ * @return the length of the line segment
+ */
@Override
public double getLength() {
- return new Vector3d(getStart()).sub(getEnd()).length();
+ refresh();
+ return start.distance(end);
}
+ /**
+ * Rescales the line so its total length equals {@code length} by moving the end endpoint
+ * along the current direction while keeping the start fixed. Invalidates the point cache.
+ *
+ * @param length the new length; clamped to at least {@link Shape#EPSILON}
+ */
@Override
public void setLength(double length) {
length = Math.max(length, Shape.EPSILON);
Vector3d start = getStart();
- Vector3d end = getEnd();
- Vector3d direction = new Vector3d(end).sub(start).normalize();
- Vector3d newEnd = new Vector3d(start).add(direction.mul(length));
- setEnd(newEnd);
+ Vector3d direction = getEnd().sub(start);
+ if (direction.lengthSquared() == 0)
+ return;
+ setEnd(start.add(direction.normalize().mul(length)));
}
+ /**
+ * Always returns {@code 0}; a line has no width dimension.
+ *
+ * @return {@code 0}
+ */
@Override
public double getWidth() { return 0; }
+ /**
+ * No-op; a line has no width dimension.
+ *
+ * @param width ignored
+ */
@Override
public void setWidth(double width) { }
+ /**
+ * Always returns {@code 0}; a line has no height dimension.
+ *
+ * @return {@code 0}
+ */
@Override
public double getHeight() { return 0; }
+ /**
+ * No-op; a line has no height dimension.
+ *
+ * @param height ignored
+ */
@Override
public void setHeight(double height) { }
+ /**
+ * Returns a deep copy of this line, preserving dynamic vs. static endpoint mode and all
+ * inherited {@link AbstractShape} state.
+ *
+ * @return a new {@link Line} with identical configuration
+ */
@Override
public Shape clone() {
- Line clone;
- if (isDynamic()) {
- clone = new Line(this.startSupplier, this.endSupplier);
- } else {
- clone = new Line(getStart(), getEnd());
- }
- return this.copyTo(clone);
+ return this.copyTo(new Line(this));
}
+ /**
+ * Returns a human-readable description of this line including its start and end positions.
+ *
+ * @return a string of the form {@code "Line from to "}
+ */
public String toString() {
return "Line from " + getStart() + " to " + getEnd();
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/PolyShape.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/PolyShape.java
index 51a75f9..f0f38f9 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/PolyShape.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/PolyShape.java
@@ -4,8 +4,37 @@
* Represents a shape that has a number of sides and a side length.
*/
public interface PolyShape extends Shape {
+
+ /**
+ * Returns the number of sides (faces or edges) of this polygonal shape.
+ * Must be at least {@code 3} for a valid polygon.
+ *
+ * @return the number of sides
+ */
int getSides();
+
+ /**
+ * Sets the number of sides for this polygonal shape.
+ * Values below the minimum supported by the implementation should be clamped or rejected.
+ *
+ * @param sides the new number of sides; must be {@code >= 3}
+ */
void setSides(int sides);
+
+ /**
+ * Returns the length of each side of this polygonal shape, in local units.
+ * The circumradius of a regular n-gon with side length {@code s} is
+ * {@code r = s / (2 * sin(π / n))}.
+ *
+ * @return the side length, in local units
+ */
double getSideLength();
+
+ /**
+ * Sets the side length for this polygonal shape.
+ * Changing the side length typically invalidates cached geometry.
+ *
+ * @param sideLength the new side length, in local units; must be {@code > 0}
+ */
void setSideLength(double sideLength);
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RadialShape.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RadialShape.java
index 3ffa825..78357a3 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RadialShape.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RadialShape.java
@@ -5,6 +5,20 @@
* The radius must be greater than 0.
*/
public interface RadialShape extends Shape {
+
+ /**
+ * Returns the radius of this shape.
+ * The radius is always positive (implementations should enforce {@code radius > 0}).
+ *
+ * @return the radius, in the shape's local units
+ */
double getRadius();
+
+ /**
+ * Sets the radius of this shape. The radius must be greater than {@code 0}; values at or
+ * below zero should be clamped or rejected by the implementing class.
+ *
+ * @param radius the new radius, in the shape's local units
+ */
void setRadius(double radius);
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Rectangle.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Rectangle.java
index 03f8555..d26e8c5 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Rectangle.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/Rectangle.java
@@ -3,24 +3,43 @@
import com.sovdee.shapes.sampling.SamplingStyle;
import org.joml.Vector3d;
-import java.util.Set;
+import java.util.List;
import java.util.function.Supplier;
/**
- * A rectangle shape, defined by a plane and dimensions.
- * For dynamic (entity-following) rectangles, use the plugin-side DynamicRectangle wrapper.
+ * A flat rectangular shape aligned to one of the three axis-aligned planes (XZ, XY, or YZ).
+ * The rectangle is centred at the origin of the shape's local coordinate space; an optional
+ * centre offset is applied when corners are supplied, shifting the origin to the midpoint of
+ * the two corners.
+ *
+ * Implements {@link LWHShape} where {@code length} and {@code width} describe the two in-plane
+ * dimensions; {@code height} is always {@code 0}. The orientation plane is chosen via the
+ * {@link Plane} enum.
+ *
+ *
+ * For entity-following rectangles whose corners track moving locations, use the plugin-side
+ * {@code DynamicRectangle} wrapper rather than the supplier constructor directly.
+ *
*/
public class Rectangle extends AbstractShape implements LWHShape {
private Plane plane;
private double halfLength;
private double halfWidth;
- private double lengthStep = 1.0;
- private double widthStep = 1.0;
private Vector3d centerOffset = new Vector3d(0, 0, 0);
private Supplier cornerASupplier;
private Supplier cornerBSupplier;
+ // the corners last read from the suppliers, to detect when they move
+ private Vector3d lastCornerA;
+ private Vector3d lastCornerB;
+ /**
+ * Constructs a rectangle centred at the local origin with explicit dimensions.
+ *
+ * @param length the extent along the first axis of {@code plane}; clamped to at least {@link Shape#EPSILON}
+ * @param width the extent along the second axis of {@code plane}; clamped to at least {@link Shape#EPSILON}
+ * @param plane the axis-aligned plane in which the rectangle lies
+ */
public Rectangle(double length, double width, Plane plane) {
super();
this.plane = plane;
@@ -28,11 +47,48 @@ public Rectangle(double length, double width, Plane plane) {
this.halfWidth = Math.max(width / 2, Shape.EPSILON);
}
+ /**
+ * Constructs a static rectangle from two opposite corner positions.
+ * The centre offset is computed from the midpoint of the two corners (projected onto
+ * {@code plane} so the off-axis component is zeroed).
+ *
+ * @param cornerA the first corner of the rectangle
+ * @param cornerB the diagonally opposite corner; must differ from {@code cornerA}
+ * @param plane the axis-aligned plane in which the rectangle lies
+ * @throws IllegalArgumentException if {@code cornerA} equals {@code cornerB}
+ */
public Rectangle(Vector3d cornerA, Vector3d cornerB, Plane plane) {
super();
if (cornerA.equals(cornerB))
throw new IllegalArgumentException("Corners cannot be the same.");
this.plane = plane;
+ setCorners(cornerA, cornerB);
+ }
+
+ /**
+ * Constructs a dynamic rectangle whose corners are resolved each frame via suppliers.
+ * The shape is marked as {@link AbstractShape#isDynamic() dynamic} so points are regenerated
+ * every draw call. The initial dimensions are computed from the suppliers' first values.
+ *
+ * @param cornerA a supplier providing the current position of the first corner
+ * @param cornerB a supplier providing the current position of the diagonally opposite corner
+ * @param plane the axis-aligned plane in which the rectangle lies
+ */
+ public Rectangle(Supplier cornerA, Supplier cornerB, Plane plane) {
+ super();
+ this.plane = plane;
+ this.cornerASupplier = cornerA;
+ this.cornerBSupplier = cornerB;
+ this.lastCornerA = new Vector3d(cornerA.get());
+ this.lastCornerB = new Vector3d(cornerB.get());
+ setCorners(lastCornerA, lastCornerB);
+ setDynamic(true);
+ }
+
+ /**
+ * Sizes the rectangle to span the two corners, and centers it between them within its plane.
+ */
+ private void setCorners(Vector3d cornerA, Vector3d cornerB) {
setLengthWidth(cornerA, cornerB);
centerOffset = new Vector3d(cornerB).add(cornerA).mul(0.5);
switch (plane) {
@@ -42,15 +98,21 @@ public Rectangle(Vector3d cornerA, Vector3d cornerB, Plane plane) {
}
}
- public Rectangle(Supplier cornerA, Supplier cornerB, Plane plane) {
- super();
- this.plane = plane;
- this.cornerASupplier = cornerA;
- this.cornerBSupplier = cornerB;
- Vector3d a = cornerA.get();
- Vector3d b = cornerB.get();
- setLengthWidth(a, b);
- setDynamic(true);
+ /**
+ * Re-reads the corner suppliers, if any, and invalidates the rectangle when a corner moved.
+ */
+ @Override
+ public void refresh() {
+ if (cornerASupplier == null || cornerBSupplier == null)
+ return;
+ Vector3d a = cornerASupplier.get();
+ Vector3d b = cornerBSupplier.get();
+ if (a.equals(lastCornerA) && b.equals(lastCornerB))
+ return;
+ lastCornerA = new Vector3d(a);
+ lastCornerB = new Vector3d(b);
+ setCorners(a, b);
+ invalidate();
}
private void setLengthWidth(Vector3d cornerA, Vector3d cornerB) {
@@ -62,8 +124,8 @@ private void setLengthWidth(Vector3d cornerA, Vector3d cornerB) {
case XZ, YZ -> Math.abs(cornerA.z - cornerB.z);
case XY -> Math.abs(cornerA.y - cornerB.y);
};
- this.halfWidth = Math.abs(width) / 2;
- this.halfLength = Math.abs(length) / 2;
+ this.halfWidth = Math.max(Math.abs(width) / 2, Shape.EPSILON);
+ this.halfLength = Math.max(Math.abs(length) / 2, Shape.EPSILON);
}
private Vector3d vectorFromLengthWidth(double length, double width) {
@@ -74,47 +136,73 @@ private Vector3d vectorFromLengthWidth(double length, double width) {
};
}
- private void calculateSteps(double density) {
- lengthStep = 2 * halfWidth / Math.round(2 * halfWidth / density);
- widthStep = 2 * halfLength / Math.round(2 * halfLength / density);
- }
-
- @Override
- public void beforeSampling(double density) {
- if (cornerASupplier != null && cornerBSupplier != null) {
- Vector3d a = cornerASupplier.get();
- Vector3d b = cornerBSupplier.get();
- setLengthWidth(a, b);
- }
- calculateSteps(density);
- }
-
+ /**
+ * Generates outline (perimeter) points for the rectangle. Points are placed along all four
+ * edges, roughly {@code density} apart.
+ *
+ * @param points the list to which outline points are appended
+ * @param density the approximate spacing between consecutive points (used implicitly via step sizes)
+ */
@Override
- public void afterSampling(Set points) {
- points.forEach(vector -> vector.add(centerOffset));
- }
-
- @Override
- public void generateOutline(Set points, double density) {
- for (double l = -halfLength + widthStep; l < halfLength; l += widthStep) {
+ public void generateOutline(List points, double density) {
+ int start = points.size();
+ int lengthSegments = segments(2 * halfLength, density);
+ int widthSegments = segments(2 * halfWidth, density);
+ // the two sides along the width include the corners; the other two only add the points between them
+ for (int i = 1; i < lengthSegments; i++) {
+ double l = -halfLength + 2 * halfLength * i / lengthSegments;
points.add(vectorFromLengthWidth(l, -halfWidth));
points.add(vectorFromLengthWidth(l, halfWidth));
}
- for (double w = -halfWidth; w <= halfWidth; w += lengthStep) {
+ for (int i = 0; i <= widthSegments; i++) {
+ double w = -halfWidth + 2 * halfWidth * i / widthSegments;
points.add(vectorFromLengthWidth(-halfLength, w));
points.add(vectorFromLengthWidth(halfLength, w));
}
+ applyCenterOffset(points, start);
}
+ /**
+ * Generates surface (filled plane) points for the rectangle by sampling a uniform grid
+ * across both in-plane axes.
+ *
+ * @param points the list to which surface points are appended
+ * @param density the approximate spacing between consecutive points (used implicitly via step sizes)
+ */
@Override
- public void generateSurface(Set points, double density) {
- for (double w = -halfWidth; w <= halfWidth; w += lengthStep) {
- for (double l = -halfLength; l <= halfLength; l += widthStep) {
+ public void generateSurface(List points, double density) {
+ int start = points.size();
+ int lengthSegments = segments(2 * halfLength, density);
+ int widthSegments = segments(2 * halfWidth, density);
+ for (int i = 0; i <= widthSegments; i++) {
+ double w = -halfWidth + 2 * halfWidth * i / widthSegments;
+ for (int j = 0; j <= lengthSegments; j++) {
+ double l = -halfLength + 2 * halfLength * j / lengthSegments;
points.add(vectorFromLengthWidth(l, w));
}
}
+ applyCenterOffset(points, start);
+ }
+
+ /**
+ * Moves the points generated since {@code start} from around the origin to around the rectangle's center.
+ */
+ private void applyCenterOffset(List points, int start) {
+ if (centerOffset.x == 0 && centerOffset.y == 0 && centerOffset.z == 0)
+ return;
+ for (int i = start; i < points.size(); i++) {
+ points.get(i).add(centerOffset);
+ }
}
+ /**
+ * Computes the inter-point density needed to reach {@code targetPointCount} sampled points.
+ * For SURFACE/FILL: {@code sqrt(area / count)}. For OUTLINE: {@code perimeter / count}.
+ *
+ * @param style the sampling style that determines which formula is used
+ * @param targetPointCount the desired number of points
+ * @return the computed density
+ */
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(targetPointCount, 1);
@@ -124,68 +212,162 @@ public double computeDensity(SamplingStyle style, int targetPointCount) {
};
}
+ /**
+ * Returns {@code true} if {@code point} lies within (or on the boundary of) the rectangle,
+ * including the constraint that it lies on the rectangle's plane (within {@link #EPSILON}).
+ *
+ * @param point the point to test in local coordinates
+ * @param tolerance how far outside the exact shape still counts as contained
+ * @return {@code true} if the point is inside the rectangle
+ */
@Override
- public boolean contains(Vector3d point) {
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ point.sub(centerOffset);
+ double l = halfLength + tolerance;
+ double w = halfWidth + tolerance;
return switch (plane) {
- case XZ -> Math.abs(point.x) <= halfLength && Math.abs(point.z) <= halfWidth && Math.abs(point.y) < EPSILON;
- case XY -> Math.abs(point.x) <= halfLength && Math.abs(point.y) <= halfWidth && Math.abs(point.z) < EPSILON;
- case YZ -> Math.abs(point.y) <= halfLength && Math.abs(point.z) <= halfWidth && Math.abs(point.x) < EPSILON;
+ case XZ -> Math.abs(point.x) <= l && Math.abs(point.z) <= w && Math.abs(point.y) <= tolerance;
+ case XY -> Math.abs(point.x) <= l && Math.abs(point.y) <= w && Math.abs(point.z) <= tolerance;
+ case YZ -> Math.abs(point.y) <= l && Math.abs(point.z) <= w && Math.abs(point.x) <= tolerance;
};
}
+ /**
+ * Returns the full length of the rectangle (twice the internal half-length).
+ *
+ * @return the length along the first in-plane axis
+ */
@Override
public double getLength() { return halfLength * 2; }
+ /**
+ * Sets the rectangle's length and invalidates the point cache.
+ *
+ * @param length the new full length; clamped to at least {@link Shape#EPSILON}
+ */
@Override
public void setLength(double length) {
this.halfLength = Math.max(length / 2, Shape.EPSILON);
invalidate();
}
+ /**
+ * Returns the full width of the rectangle (twice the internal half-width).
+ *
+ * @return the width along the second in-plane axis
+ */
@Override
public double getWidth() { return halfWidth * 2; }
+ /**
+ * Sets the rectangle's width and invalidates the point cache.
+ *
+ * @param width the new full width; clamped to at least {@link Shape#EPSILON}
+ */
@Override
public void setWidth(double width) {
this.halfWidth = Math.max(width / 2, Shape.EPSILON);
invalidate();
}
+ /**
+ * Always returns {@code 0}; a rectangle has no height dimension.
+ *
+ * @return {@code 0}
+ */
@Override
public double getHeight() { return 0; }
+ /**
+ * No-op; a rectangle has no height dimension.
+ *
+ * @param height ignored
+ */
@Override
public void setHeight(double height) { }
+ /**
+ * Returns the axis-aligned {@link Plane} in which this rectangle lies.
+ *
+ * @return the current plane
+ */
public Plane getPlane() { return plane; }
+ /**
+ * Sets the axis-aligned plane and invalidates the point cache.
+ *
+ * @param plane the new plane orientation
+ */
public void setPlane(Plane plane) {
this.plane = plane;
invalidate();
}
+ /**
+ * Returns the supplier used to resolve the first corner for dynamic rectangles, or
+ * {@code null} if the rectangle was constructed from static dimensions or corners.
+ *
+ * @return the corner A supplier, or {@code null}
+ */
public Supplier getCornerASupplier() { return cornerASupplier; }
+
+ /**
+ * Returns the supplier used to resolve the second corner for dynamic rectangles, or
+ * {@code null} if the rectangle was constructed from static dimensions or corners.
+ *
+ * @return the corner B supplier, or {@code null}
+ */
public Supplier getCornerBSupplier() { return cornerBSupplier; }
+ /**
+ * Returns a deep copy of this rectangle, preserving dynamic vs. static corner mode, the
+ * centre offset, and all inherited {@link AbstractShape} state.
+ *
+ * @return a new {@link Rectangle} with identical configuration
+ */
@Override
public Shape clone() {
- Rectangle rectangle;
- if (cornerASupplier != null && cornerBSupplier != null) {
- rectangle = new Rectangle(cornerASupplier, cornerBSupplier, plane);
- } else {
- rectangle = new Rectangle(this.getLength(), this.getWidth(), plane);
- }
+ // copy the current state rather than re-reading the suppliers, so the copy has identical geometry
+ Rectangle rectangle = new Rectangle(this.getLength(), this.getWidth(), plane);
rectangle.centerOffset = new Vector3d(this.centerOffset);
+ rectangle.cornerASupplier = this.cornerASupplier;
+ rectangle.cornerBSupplier = this.cornerBSupplier;
+ rectangle.lastCornerA = this.lastCornerA;
+ rectangle.lastCornerB = this.lastCornerB;
return this.copyTo(rectangle);
}
+ /**
+ * Returns a human-readable description including the plane name, length, and width.
+ *
+ * @return a string of the form {@code " rectangle with length and width "}
+ */
@Override
public String toString() {
String axis = this.plane.toString().toLowerCase();
return axis + " rectangle with length " + this.getLength() + " and width " + this.getWidth();
}
+ /**
+ * Identifies which of the three axis-aligned planes a {@link Rectangle} lies in.
+ *
+ * - {@link #XZ} - the horizontal ground plane (Y = 0)
+ * - {@link #XY} - the vertical frontal plane (Z = 0)
+ * - {@link #YZ} - the vertical lateral plane (X = 0)
+ *
+ */
public enum Plane {
- XZ, XY, YZ
+ /**
+ * The horizontal XZ plane; length along X, width along Z.
+ */
+ XZ,
+ /**
+ * The vertical XY plane; length along X, width along Y.
+ */
+ XY,
+ /**
+ * The vertical YZ plane; length along Y, width along Z.
+ */
+ YZ
}
}
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolygon.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolygon.java
index 87705b3..188ce58 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolygon.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolygon.java
@@ -4,148 +4,341 @@
import com.sovdee.shapes.util.VectorUtil;
import org.joml.Vector3d;
-import java.util.LinkedHashSet;
-import java.util.Set;
-
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * A regular polygon (or regular prism when {@code height > 0}) with equal-length sides and equal
+ * interior angles, oriented in the XZ plane. The circumscribed circle has the given {@code radius},
+ * and each side subtends an angle of {@code 2π / sides} at the centre.
+ *
+ * When {@code height == 0} the shape is a flat polygon; when {@code height > 0} it becomes a
+ * prism extruded along the Y axis. The shape implements {@link PolyShape}, {@link RadialShape},
+ * and {@link LWHShape}; {@code length} and {@code width} from {@link LWHShape} always return
+ * {@code 0} for this shape — only {@code height} is meaningful.
+ *
+ *
+ * The minimum number of sides is 3 (triangle); the maximum interior angle per side is
+ * {@code 2π/3} (i.e. a minimum of 3 sides is enforced when setting via angle).
+ *
+ */
public class RegularPolygon extends AbstractShape implements PolyShape, RadialShape, LWHShape {
+ // The side count is the source of truth; the angle is always derived from it,
+ // so repeated conversions cannot drift or truncate.
+ private int sides;
private double angle;
private double radius;
private double height;
+ /**
+ * Constructs a flat regular polygon (height = 0) with the given number of sides and radius.
+ *
+ * @param sides the number of sides; determines the vertex angle as {@code 2π / sides}
+ * @param radius the circumscribed (outer) radius; clamped to at least {@link Shape#EPSILON}
+ */
public RegularPolygon(int sides, double radius) {
this((Math.PI * 2) / sides, radius, 0);
}
+ /**
+ * Constructs a flat regular polygon (height = 0) with an explicit vertex angle and radius.
+ * The number of sides is derived as {@code floor(2π / angle)}.
+ *
+ * @param angle the angular size of each side in radians; clamped to {@code [ε, 2π/3]}
+ * @param radius the circumscribed (outer) radius; clamped to at least {@link Shape#EPSILON}
+ */
public RegularPolygon(double angle, double radius) {
this(angle, radius, 0);
}
+ /**
+ * Constructs a regular prism with the given number of sides, circumscribed radius, and height.
+ * When {@code height == 0} this is equivalent to {@link #RegularPolygon(int, double)}.
+ *
+ * @param sides the number of sides
+ * @param radius the circumscribed (outer) radius; clamped to at least {@link Shape#EPSILON}
+ * @param height the extrusion height along the Y axis; {@code 0} for a flat polygon
+ */
public RegularPolygon(int sides, double radius, double height) {
this((Math.PI * 2) / sides, radius, height);
}
+ /**
+ * Constructs a regular prism with an explicit vertex angle, radius, and height.
+ * This is the canonical constructor; all other constructors delegate here.
+ *
+ * @param angle the angular size of each side in radians; clamped to {@code [ε, 2π/3]}
+ * @param radius the circumscribed (outer) radius; clamped to at least {@link Shape#EPSILON}
+ * @param height the extrusion height along the Y axis; {@code 0} for a flat polygon
+ */
public RegularPolygon(double angle, double radius, double height) {
super();
- this.angle = Math.clamp(angle, Shape.EPSILON, Math.PI * 2 / 3);
+ setSideCount(sidesFromAngle(angle));
this.radius = Math.max(radius, Shape.EPSILON);
this.height = Math.max(height, 0);
}
- // --- Static calculation methods ---
+ /**
+ * @return the number of sides a polygon with the given exterior angle has, at least 3
+ */
+ private static int sidesFromAngle(double angle) {
+ double sides = Math.round(Math.PI * 2 / Math.max(angle, Shape.EPSILON));
+ return (int) Math.clamp(sides, 3, 100_000);
+ }
- public static Set calculateRegularPolygon(double radius, double angle, double density, boolean wireframe) {
- angle = Math.max(angle, Shape.EPSILON);
+ private void setSideCount(int sides) {
+ this.sides = Math.max(sides, 3);
+ this.angle = Math.PI * 2 / this.sides;
+ }
- Set points = new LinkedHashSet<>();
- double apothem = radius * Math.cos(angle / 2);
- double radiusStep = radius / Math.round(apothem / density);
+ /**
+ * Appends the outline of a regular polygon: one edge per side, each without its end point,
+ * so every vertex appears exactly once.
+ */
+ private static void calculatePolygonRing(List points, double radius, int sides, double density) {
+ double angle = Math.PI * 2 / sides;
+ Vector3d vertex = new Vector3d(radius, 0, 0);
+ for (int side = 0; side < sides; side++) {
+ Line.calculateLine(points,
+ VectorUtil.rotateAroundY(new Vector3d(vertex), side * angle),
+ VectorUtil.rotateAroundY(new Vector3d(vertex), (side + 1) * angle),
+ density, false);
+ }
+ }
+
+ // --- Static calculation methods ---
+
+ /**
+ * Samples points on (or filling) a regular polygon in the XZ plane.
+ *
+ * When {@code wireframe} is {@code true} only the perimeter edges are sampled. When
+ * {@code false}, concentric rings from the outer radius inward are filled (surface mode),
+ * with a centre point added explicitly.
+ *
+ * The apothem is {@code radius * cos(angle/2)}; the radial step between rings is
+ * {@code radius / round(apothem / density)}.
+ *
+ * @param points the list to which sampled points are appended
+ * @param radius the circumscribed radius of the polygon
+ * @param angle the angular size of each side in radians ({@code 2π / sides})
+ * @param density the approximate spacing between consecutive points
+ * @param wireframe {@code true} to sample only the outer perimeter; {@code false} to fill
+ */
+ public static void calculateRegularPolygon(List points, double radius, double angle, double density, boolean wireframe) {
+ int sides = sidesFromAngle(angle);
if (wireframe) {
- radiusStep = 2 * radius;
- } else {
- points.add(new Vector3d(0, 0, 0));
+ calculatePolygonRing(points, radius, sides, density);
+ return;
}
- for (double subRadius = radius; subRadius >= 0; subRadius -= radiusStep) {
- Vector3d vertex = new Vector3d(subRadius, 0, 0);
- for (double i = 0; i < 2 * Math.PI; i += angle) {
- points.addAll(Line.calculateLine(
- VectorUtil.rotateAroundY(new Vector3d(vertex), i),
- VectorUtil.rotateAroundY(new Vector3d(vertex), i + angle),
- density));
- }
+ // concentric rings from the outline inwards, plus the center
+ double apothem = radius * Math.cos(Math.PI / sides);
+ int rings = segments(apothem, density);
+ for (int ring = rings; ring >= 1; ring--) {
+ calculatePolygonRing(points, radius * ring / rings, sides, density);
}
- return points;
+ points.add(new Vector3d(0, 0, 0));
}
- public static Set calculateRegularPrism(double radius, double angle, double height, double density, boolean wireframe) {
- Set points = new LinkedHashSet<>();
- Vector3d vertex = new Vector3d(radius, 0, 0);
- for (double i = 0; i < 2 * Math.PI; i += angle) {
- Vector3d currentVertex = VectorUtil.rotateAroundY(new Vector3d(vertex), i);
- for (Vector3d vector : Line.calculateLine(currentVertex, VectorUtil.rotateAroundY(new Vector3d(vertex), i + angle), density)) {
- points.add(vector);
- if (wireframe) {
- points.add(new Vector3d(vector.x, height, vector.z));
- } else {
- points.addAll(Line.calculateLine(vector, new Vector3d(vector.x, height, vector.z), density));
+ /**
+ * Samples points on (or filling) a regular prism extruded along the Y axis.
+ *
+ * For each side of the polygon, the bottom edge is sampled using
+ * {@link Line#calculateLine(List, Vector3d, Vector3d, double)}, then either vertical edge
+ * points are paired (wireframe) or filled columns are generated up to {@code height}.
+ * Vertical pillar edges at each vertex are always included in wireframe mode.
+ *
+ *
+ * @param points the list to which sampled points are appended
+ * @param radius the circumscribed radius of the prism's base
+ * @param angle the angular size of each side in radians ({@code 2π / sides})
+ * @param height the extrusion height along the Y axis
+ * @param density the approximate spacing between consecutive points
+ * @param wireframe {@code true} to sample only the edges; {@code false} to fill the lateral faces
+ */
+ public static void calculateRegularPrism(List points, double radius, double angle, double height, double density, boolean wireframe) {
+ int sides = sidesFromAngle(angle);
+ double sideAngle = Math.PI * 2 / sides;
+ // bottom ring
+ int ringStart = points.size();
+ calculatePolygonRing(points, radius, sides, density);
+ int ringEnd = points.size();
+ if (wireframe) {
+ // top ring
+ for (int i = ringStart; i < ringEnd; i++) {
+ Vector3d v = points.get(i);
+ points.add(new Vector3d(v.x, height, v.z));
+ }
+ // vertical edges, without the vertices that the rings already contain
+ int layers = segments(height, density);
+ Vector3d vertex = new Vector3d(radius, 0, 0);
+ for (int side = 0; side < sides; side++) {
+ Vector3d corner = VectorUtil.rotateAroundY(new Vector3d(vertex), side * sideAngle);
+ for (int layer = 1; layer < layers; layer++) {
+ points.add(new Vector3d(corner.x, height * layer / layers, corner.z));
}
}
- if (wireframe)
- points.addAll(Line.calculateLine(currentVertex, new Vector3d(currentVertex.x, height, currentVertex.z), density));
+ } else {
+ // walls: the ring repeated up to the top
+ fillVertically(points, ringStart, height, density, true);
}
- return points;
}
// --- Generation methods ---
+ /**
+ * Generates outline (perimeter) points. For flat polygons this is the outer edge; for prisms
+ * this includes both the top/bottom edges and the vertical pillar edges at each vertex.
+ *
+ * @param points the list to which outline points are appended
+ * @param density the approximate spacing between consecutive points
+ */
@Override
- public void generateOutline(Set points, double density) {
+ public void generateOutline(List points, double density) {
if (height == 0)
- points.addAll(calculateRegularPolygon(this.radius, this.angle, density, true));
+ calculateRegularPolygon(points, this.radius, this.angle, density, true);
else
- points.addAll(calculateRegularPrism(this.radius, this.angle, this.height, density, true));
+ calculateRegularPrism(points, this.radius, this.angle, this.height, density, true);
}
+ /**
+ * Generates surface points. For flat polygons this samples the filled face; for prisms this
+ * samples the lateral faces (not the top/bottom caps).
+ *
+ * @param points the list to which surface points are appended
+ * @param density the approximate spacing between consecutive points
+ */
@Override
- public void generateSurface(Set points, double density) {
+ public void generateSurface(List points, double density) {
if (height == 0)
- points.addAll(calculateRegularPolygon(this.radius, this.angle, density, false));
+ calculateRegularPolygon(points, this.radius, this.angle, density, false);
else
- points.addAll(calculateRegularPrism(this.radius, this.angle, this.height, density, false));
+ calculateRegularPrism(points, this.radius, this.angle, this.height, density, false);
}
+ /**
+ * Generates filled interior points. For flat polygons this is identical to surface mode.
+ * For prisms, a surface polygon is generated and then replicated vertically using
+ * {@link AbstractShape#fillVertically} to fill the volume.
+ *
+ * @param points the list to which filled points are appended
+ * @param density the approximate spacing between consecutive points
+ */
@Override
- public void generateFilled(Set points, double density) {
+ public void generateFilled(List points, double density) {
if (height == 0)
generateSurface(points, density);
else {
- Set polygon = calculateRegularPolygon(this.radius, this.angle, density, false);
- fillVertically(polygon, height, density);
- points.addAll(polygon);
+ int start = points.size();
+ calculateRegularPolygon(points, this.radius, this.angle, density, false);
+ fillVertically(points, start, height, density);
}
}
+ /**
+ * Computes the density needed to achieve {@code targetPointCount} sampled points.
+ * Uses the following formulas (where {@code s = sides}, {@code r = radius},
+ * {@code θ = angle}, {@code h = height}):
+ *
+ * - OUTLINE (flat): {@code 2·s·r·sin(θ/2) / count}
+ * - OUTLINE (prism): {@code (4·s·r·sin(θ/2) + h·s) / count}
+ * - SURFACE (flat): {@code sqrt(s·r²·sin(θ)/2 / count)}
+ * - SURFACE (prism): {@code (s·r²·sin(θ) + sideLength·s·h) / count}
+ * - FILL: {@code s·r²·sin(θ)·h / count}
+ *
+ *
+ * @param style determines which area/perimeter formula to apply
+ * @param targetPointCount the desired number of points
+ * @return the computed density
+ */
@Override
public double computeDensity(SamplingStyle style, int targetPointCount) {
int count = Math.max(targetPointCount, 1);
- int sides = getSides();
+ double perimeter = sides * getSideLength();
+ double area = sides * radius * radius * Math.sin(angle) / 2;
return switch (style) {
case OUTLINE -> {
if (height == 0)
- yield 2 * sides * radius * Math.sin(angle / 2) / count;
- yield (4 * sides * radius * Math.sin(angle / 2) + height * sides) / count;
+ yield perimeter / count;
+ // both rings plus one vertical edge per vertex
+ yield (2 * perimeter + sides * height) / count;
}
case SURFACE -> {
if (height == 0)
- yield Math.sqrt(sides * radius * radius * Math.sin(angle) / 2 / count);
- yield (sides * radius * radius * Math.sin(angle) + getSideLength() * sides * height) / count;
+ yield Math.sqrt(area / count);
+ // the surface of a prism is its walls
+ yield Math.sqrt(perimeter * height / count);
+ }
+ case FILL -> {
+ // a flat polygon has no volume: it is filled as a surface
+ if (height == 0)
+ yield Math.sqrt(area / count);
+ yield Math.cbrt(area * height / count);
}
- case FILL -> (sides * radius * radius * Math.sin(angle) * height) / count;
};
}
+ /**
+ * Returns {@code true} if {@code point} lies within the polygon (or prism) in local
+ * coordinates. For flat polygons the point must lie in the XZ plane (|y| < ε). For prisms
+ * the Y coordinate must be in {@code [0, height]}. The XZ containment check uses the apothem
+ * and the angular position to test against the actual polygon boundary.
+ *
+ * @param point the point to test in local coordinates
+ * @param tolerance how far outside the exact shape still counts as contained
+ * @return {@code true} if the point is inside the polygon or prism
+ */
@Override
- public boolean contains(Vector3d point) {
- if (height > 0 && (point.y < 0 || point.y > height)) return false;
- if (height == 0 && Math.abs(point.y) > EPSILON) return false;
- // Check if point is within the polygon on XZ plane using inscribed radius
- double dist = Math.sqrt(point.x * point.x + point.z * point.z);
+ protected boolean containsLocal(Vector3d point, double tolerance) {
+ if (height > 0) {
+ if (point.y < -tolerance || point.y > height + tolerance) return false;
+ } else if (Math.abs(point.y) > tolerance) {
+ return false;
+ }
+ double distance = Math.sqrt(point.x * point.x + point.z * point.z);
+ if (distance > radius + tolerance) return false;
+ // Fold the point's angle into a single side: [0, angle), with the side's midpoint at angle / 2.
+ // The vertices sit at multiples of the angle, and the polygon is symmetric about the x-axis.
+ double folded = Math.atan2(point.z, point.x) % angle;
+ if (folded < 0) folded += angle;
double apothem = radius * Math.cos(angle / 2);
- return dist <= radius && dist <= apothem / Math.cos(Math.atan2(point.z, point.x) % angle - angle / 2);
+ return distance * Math.cos(folded - angle / 2) <= apothem + tolerance;
}
+ /**
+ * Returns the number of sides, computed as {@code floor(2π / angle)}.
+ *
+ * @return the number of sides of this polygon
+ */
@Override
- public int getSides() { return (int) (Math.PI * 2 / this.angle); }
-
+ public int getSides() { return sides; }
+
+ /**
+ * Sets the number of sides by recomputing the vertex angle as {@code 2π / sides}.
+ * Minimum of 3 sides is enforced. Invalidates the point cache.
+ *
+ * @param sides the desired number of sides; clamped to at least 3
+ */
@Override
public void setSides(int sides) {
- this.angle = (Math.PI * 2) / Math.max(sides, 3);
+ setSideCount(sides);
invalidate();
}
+ /**
+ * Returns the edge length of each side, equal to {@code 2 * radius * sin(angle / 2)}.
+ *
+ * @return the side length
+ */
@Override
public double getSideLength() { return this.radius * 2 * Math.sin(this.angle / 2); }
+ /**
+ * Sets the radius so that the edge length equals {@code sideLength}, keeping the current
+ * angle (and thus side count) unchanged. Invalidates the point cache.
+ *
+ * @param sideLength the desired edge length; clamped to at least {@link Shape#EPSILON}
+ */
@Override
public void setSideLength(double sideLength) {
sideLength = Math.max(sideLength, Shape.EPSILON);
@@ -154,41 +347,93 @@ public void setSideLength(double sideLength) {
invalidate();
}
+ /**
+ * Returns the circumscribed (outer) radius of the polygon.
+ *
+ * @return the radius
+ */
@Override
public double getRadius() { return this.radius; }
+ /**
+ * Sets the circumscribed radius and invalidates the point cache.
+ *
+ * @param radius the new radius; clamped to at least {@link Shape#EPSILON}
+ */
@Override
public void setRadius(double radius) {
this.radius = Math.max(radius, Shape.EPSILON);
invalidate();
}
+ /**
+ * Always returns {@code 0}; length is not a distinct dimension of this shape.
+ *
+ * @return {@code 0}
+ */
@Override
public double getLength() { return 0; }
+ /**
+ * No-op; length is not a distinct dimension of this shape.
+ *
+ * @param length ignored
+ */
@Override
public void setLength(double length) { }
+ /**
+ * Always returns {@code 0}; width is not a distinct dimension of this shape.
+ *
+ * @return {@code 0}
+ */
@Override
public double getWidth() { return 0; }
+ /**
+ * No-op; width is not a distinct dimension of this shape.
+ *
+ * @param width ignored
+ */
@Override
public void setWidth(double width) { }
+ /**
+ * Returns the extrusion height of the prism along the Y axis, or {@code 0} for a flat polygon.
+ *
+ * @return the height
+ */
@Override
public double getHeight() { return height; }
+ /**
+ * Sets the extrusion height and invalidates the point cache. A value of {@code 0} produces a
+ * flat polygon; positive values produce a prism.
+ *
+ * @param height the new height; clamped to at least {@code 0}
+ */
@Override
public void setHeight(double height) {
this.height = Math.max(height, 0);
invalidate();
}
+ /**
+ * Returns a deep copy of this polygon, preserving angle, radius, height, and all inherited
+ * {@link AbstractShape} state.
+ *
+ * @return a new {@link RegularPolygon} with identical configuration
+ */
@Override
public Shape clone() {
- return this.copyTo(new RegularPolygon(angle, radius, height));
+ return this.copyTo(new RegularPolygon(sides, radius, height));
}
+ /**
+ * Returns a human-readable description of this polygon including side count and radius.
+ *
+ * @return a string of the form {@code "regular polygon with sides and radius "}
+ */
@Override
public String toString() {
return "regular polygon with " + getSides() + " sides and radius " + getRadius();
diff --git a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolyhedron.java b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolyhedron.java
index ec0042b..c7a4b38 100644
--- a/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolyhedron.java
+++ b/shapes-lib/src/main/java/com/sovdee/shapes/shapes/RegularPolyhedron.java
@@ -1,13 +1,27 @@
package com.sovdee.shapes.shapes;
import com.sovdee.shapes.sampling.SamplingStyle;
+import com.sovdee.shapes.util.VectorUtil;
import org.joml.Quaterniond;
import org.joml.Vector3d;
-import java.util.HashSet;
-import java.util.LinkedHashSet;
-import java.util.Set;
+import java.util.List;
+/**
+ * One of the five Platonic solids (regular convex polyhedra), specifically the subset with
+ * triangular or pentagonal faces: tetrahedron (4 faces), octahedron (8 faces), dodecahedron
+ * (12 faces), and icosahedron (20 faces). The shape is centred at the origin and scaled so that
+ * the circumscribed sphere has the given {@code radius}.
+ *
+ * Each face is generated independently using pre-computed quaternion rotations ({@code TETRAHEDRON_FACES},
+ * etc.) that orient a canonical face into its correct position. Surface and outline points per face
+ * are produced via {@link RegularPolygon#calculateRegularPolygon}.
+ *
+ *
+ * The {@link #contains(Vector3d)} check uses a conservative inscribed-sphere test rather than an
+ * exact half-plane test.
+ *
+ */
public class RegularPolyhedron extends AbstractShape implements RadialShape, PolyShape {
private static final Quaterniond[] TETRAHEDRON_FACES = {
@@ -43,7 +57,10 @@ public class RegularPolyhedron extends AbstractShape implements RadialShape, Pol
new Quaterniond(0.8090169943749475, 0.0, -0.46708617948135794, 0.35682208977309),
new Quaterniond(-0.5, -0.5, -0.6454972243679027, 0.288675134594813),
new Quaterniond(0.0, 0.0, 0.9341723589627157, 0.35682208977309),
- new Quaterniond(-0.8090169943749475, 0.5, 0.110264089708268, -0.288675134594813)
+ new Quaterniond(-0.8090169943749475, 0.5, 0.110264089708268, -0.288675134594813),
+ new Quaterniond(0.8090169943749477, 0.0, 0.11026408970826802, 0.5773502691896257),
+ new Quaterniond(-0.8090169943749475, -0.5, -0.110264089708268, 0.288675134594813),
+ new Quaterniond(0.8090169943749475, -0.5, 0.110264089708268, -0.288675134594813)
};
private static final Quaterniond[] DODECAHEDRON_FACES = {
new Quaterniond(0.0, 0.3090169943749475, 0.0, 0.9510565162951536),
@@ -72,6 +89,13 @@ public class RegularPolyhedron extends AbstractShape implements RadialShape, Pol
private double radius;
private int faces;
+ /**
+ * Constructs a regular polyhedron with the given circumscribed radius and face count.
+ * Only face counts of 4, 8, 12, and 20 are valid; any other value defaults to 4 (tetrahedron).
+ *
+ * @param radius the circumscribed sphere radius; clamped to at least {@link Shape#EPSILON}
+ * @param faces the number of faces; must be 4, 8, 12, or 20 (defaults to 4 otherwise)
+ */
public RegularPolyhedron(double radius, int faces) {
super();
this.radius = Math.max(radius, Shape.EPSILON);
@@ -81,45 +105,64 @@ public RegularPolyhedron(double radius, int faces) {
};
}
+ /**
+ * Generates wireframe (edge) outline points for each face of the polyhedron by applying
+ * the face-specific quaternion rotation to outline points of a regular polygon face.
+ *
+ * @param points the list to which outline points are appended
+ * @param density the approximate spacing between consecutive points
+ */
@Override
- public void generateOutline(Set points, double density) {
- points.addAll(switch (faces) {
- case 4 -> generatePolyhedron(TETRAHEDRON_FACES, radius, density, SamplingStyle.OUTLINE);
- case 8 -> generatePolyhedron(OCTAHEDRON_FACES, radius, density, SamplingStyle.OUTLINE);
- case 20 -> generatePolyhedron(ICOSAHEDRON_FACES, radius, density, SamplingStyle.OUTLINE);
- case 12 -> generatePolyhedron(DODECAHEDRON_FACES, radius, density, SamplingStyle.OUTLINE);
- default -> new HashSet<>();
- });
+ public void generateOutline(List points, double density) {
+ Quaterniond[] rotations = getFaceRotations();
+ if (rotations != null)
+ generatePolyhedron(points, rotations, radius, density, SamplingStyle.OUTLINE);
}
+ /**
+ * Generates surface points covering all faces of the polyhedron. Each face is filled
+ * with a concentric-ring polygon pattern and then rotated into place.
+ *
+ * @param points the list to which surface points are appended
+ * @param density the approximate spacing between consecutive points
+ */
@Override
- public void generateSurface(Set points, double density) {
- points.addAll(switch (faces) {
- case 4 -> generatePolyhedron(TETRAHEDRON_FACES, radius, density, SamplingStyle.SURFACE);
- case 8 -> generatePolyhedron(OCTAHEDRON_FACES, radius, density, SamplingStyle.SURFACE);
- case 20 -> generatePolyhedron(ICOSAHEDRON_FACES, radius, density, SamplingStyle.SURFACE);
- case 12 -> generatePolyhedron(DODECAHEDRON_FACES, radius, density, SamplingStyle.SURFACE);
- default -> new HashSet<>();
- });
+ public void generateSurface(List points, double density) {
+ Quaterniond[] rotations = getFaceRotations();
+ if (rotations != null)
+ generatePolyhedron(points, rotations, radius, density, SamplingStyle.SURFACE);
}
+ /**
+ * Generates filled interior points by stacking concentric scaled copies of the surface from
+ * {@code radius} down to {@code 0} in steps of {@code radius / round(radius / density)}.
+ *
+ * @param points the list to which filled points are appended
+ * @param density the approximate spacing between consecutive points
+ */
@Override
- public void generateFilled(Set points, double density) {
- double step = radius / Math.round(radius / density);
- Quaterniond[] rotations = switch (faces) {
+ public void generateFilled(List points, double density) {
+ Quaterniond[] rotations = getFaceRotations();
+ if (rotations == null) return;
+ // concentric shells from the surface inwards, plus the center
+ int shells = segments(radius, density);
+ for (int shell = shells; shell >= 1; shell--) {
+ generatePolyhedron(points, rotations, radius * shell / shells, density, SamplingStyle.SURFACE);
+ }
+ points.add(new Vector3d(0, 0, 0));
+ }
+
+ private Quaterniond[] getFaceRotations() {
+ return switch (faces) {
case 4 -> TETRAHEDRON_FACES;
case 8 -> OCTAHEDRON_FACES;
case 12 -> DODECAHEDRON_FACES;
case 20 -> ICOSAHEDRON_FACES;
- default -> new Quaterniond[0];
+ default -> null;
};
- for (double i = radius; i > 0; i -= step) {
- points.addAll(generatePolyhedron(rotations, i, density, SamplingStyle.SURFACE));
- }
}
- private Set generatePolyhedron(Quaterniond[] rotations, double radius, double density, SamplingStyle style) {
- Set points = new LinkedHashSet<>();
+ private void generatePolyhedron(List points, Quaterniond[] rotations, double radius, double density, SamplingStyle style) {
int sides = this.faces == 12 ? 5 : 3;
double sideLength = switch (faces) {
case 4 -> radius / TETRA_R2SL;
@@ -135,51 +178,69 @@ private Set generatePolyhedron(Quaterniond[] rotations, double radius,
case 20 -> sideLength * ICOSA_INSC;
default -> 1;
};
+ int polyhedronStart = points.size();
Vector3d offset = new Vector3d(0, inscribedRadius, 0);
double faceRadius = sideLength / (2 * Math.sin(Math.PI / sides));
for (Quaterniond rotation : rotations) {
- Set