Merge pull request #22 from Gaia3D/develop

mago-3d-terrainer v1.13.0-release

Author: znkim

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# mago-common must be reviewed by maintainer
+/mago-common @znkim

.gitignore

@@ -50,3 +50,4 @@ bin/
 .DS_Store
 Cigolle2014Vector.pdf
 terrainer/gradle.properties
+/.gradle-home/

CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# CONTRIBUTING.md
+
+## Overview
+
+Thank you for contributing!   
+This project is maintained with a focus on consistency across multiple related repositories.
+
+---
+
+## Branch Strategy
+
+* `main` and `develop` branches are managed directly by maintainers
+* Contributors should NOT push directly to `main` or `develop`
+* All changes must be submitted via Pull Request
+
+### Release
+
+* Releases are managed via Git tags
+* No separate release branches are used
+
+---
+
+## Pull Request Guidelines
+
+* All changes must go through Pull Request
+* Keep PRs small and focused (one logical change per PR)
+* Avoid mixing unrelated changes
+
+### PR Description must include:
+
+* What was changed
+* Why it was changed
+* How it was tested (or verified)
+
+---
+
+## Commit Message Convention
+
+Use the following prefixes:
+
+* `feat` - for new features or enhancements
+* `fix` - for bug fixes
+* `chore` - for maintenance tasks (e.g., updating dependencies, formatting)
+* `test` - for adding or updating tests
+* `build` - for build-related changes (e.g., CI configuration)
+* `refactor` - for code restructuring without changing functionality
+
+### Rules
+
+* Messages must be written in **sentence form**
+* `feat` messages must start with an **imperative verb**
+
+### Examples
+
+```
+feat: Add terrain sampling option
+fix: Resolve bounding box overflow issue
+refactor: Simplify voxel processing logic
+chore: Update dependency versions
+```
+
+---
+
+## Common Module Policy (mago-common)
+
+`mago-common` is a shared module used across multiple projects such as:
+
+* mago-3d-tiler
+* mago-3d-terrainer
+
+### Rules
+
+* Only implement **general-purpose and reusable logic**
+* Avoid project-specific code inside `mago-common`
+* Keep the structure simple and broadly applicable
+
+### IMPORTANT
+
+* All modifications must be **carefully reviewed before merging**
+* Changes in common logic may affect multiple projects
+
+---
+
+## Subtree Sync Policy
+
+This repository uses `git subtree` for synchronization.
+
+### Rules
+
+* Do NOT run `git subtree push`
+* Use `git subtree pull` only when syncing
+* Shared logic must be updated at the source before syncing
+
+---
+
+## Review Criteria
+
+Pull Requests will be reviewed based on:
+
+* Reusability (no project-specific logic in common modules)
+* Code clarity and simplicity
+* Avoidance of duplicated logic
+* Minimal and focused changes
+
+---
+
+## Testing
+
+* Add tests when applicable
+* If tests are not included, clearly describe how the change was verified
+
+---
+
+## Notes
+
+If your change affects shared logic or has wide impact,   
+please discuss it before implementation.
+
+When unsure, open an issue first.

build.gradle

@@ -1,6 +1,6 @@
 subprojects {
     group "com.gaia3d"
-    version '1.12.0-release'
+    version '1.13.0-release'
     apply plugin: 'java'
     project.ext.lwjglVersion = "3.3.6"
 
@@ -115,4 +115,4 @@ tasks.register('javadocs', Javadoc) {
     options.encoding = 'UTF-8'
     options.memberLevel = JavadocMemberLevel.PUBLIC
     options.addStringOption('Xdoclint:none', '-quiet')
-}
+}

mago-common/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+#Mon Mar 23 09:30:30 KST 2026
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

mago-common/src/main/java/com/gaia3d/basic/geometry/entities/GaiaPlane.java

@@ -8,7 +8,6 @@
 @Slf4j
 @Getter
 @Setter
-
 public class GaiaPlane {
     private final double a;
     private final double b;
@@ -36,6 +35,14 @@ public GaiaPlane(Vector3d position, Vector3d normal) {
         this.d = -position.dot(normal);
     }
 
+    public static GaiaPlane setPlaneFromPositionAndNormal(Vector3d position, Vector3d normal) {
+        double a = normal.x;
+        double b = normal.y;
+        double c = normal.z;
+        double d = -position.dot(normal);
+        return new GaiaPlane(a, b, c, d);
+    }
+
     public double distanceToPoint(Vector3d point) {
         return a * point.x + b * point.y + c * point.z + d;
     }

mago-common/src/main/java/com/gaia3d/basic/geometry/entities/GaiaTriangle.java

@@ -1,6 +1,7 @@
 package com.gaia3d.basic.geometry.entities;
 
 import com.gaia3d.basic.geometry.GaiaBoundingBox;
+import com.gaia3d.basic.model.GaiaVertex;
 import lombok.Getter;
 import lombok.Setter;
 import lombok.extern.slf4j.Slf4j;
@@ -80,4 +81,12 @@ public Vector3d getBarycenter() {
                 (point1.z + point2.z + point3.z) / 3
         );
     }
+
+    public double area() {
+        Vector3d edge1 = new Vector3d(point2).sub(point1);
+        Vector3d edge2 = new Vector3d(point3).sub(point1);
+        Vector3d crossProduct = new Vector3d();
+        edge1.cross(edge2, crossProduct);
+        return 0.5 * crossProduct.length();
+    }
 }

mago-common/src/main/java/com/gaia3d/basic/geometry/modifier/HalfEdgeModifier.java

@@ -0,0 +1,71 @@
+package com.gaia3d.basic.geometry.modifier;
+
+import com.gaia3d.basic.halfedge.*;
+import lombok.extern.slf4j.Slf4j;
+import org.joml.Matrix4d;
+
+import java.util.List;
+
+@Slf4j
+abstract public class HalfEdgeModifier {
+
+    public void apply(HalfEdgeScene scene) {
+        List<HalfEdgeNode> rootNodes = scene.getNodes();
+        for (HalfEdgeNode node : rootNodes) {
+            applyNode(new Matrix4d(), node);
+        }
+    }
+
+    public void applyNode(Matrix4d parentTransformMatrix, HalfEdgeNode node) {
+        Matrix4d localTransformMatrix = node.getTransformMatrix();
+        Matrix4d productTransformMatrix = new Matrix4d(parentTransformMatrix);
+        productTransformMatrix.mul(localTransformMatrix);
+        List<HalfEdgeNode> children = node.getChildren();
+        if (children != null && !children.isEmpty()) {
+            for (HalfEdgeNode child : children) {
+                applyNode(productTransformMatrix, child);
+            }
+        }
+
+        List<HalfEdgeMesh> meshes = node.getMeshes();
+        for (HalfEdgeMesh mesh : meshes) {
+            applyMesh(productTransformMatrix, mesh);
+        }
+    }
+
+    public void applyMesh(Matrix4d productTransformMatrix, HalfEdgeMesh mesh) {
+        List<HalfEdgePrimitive> primitives = mesh.getPrimitives();
+        for (HalfEdgePrimitive primitive : primitives) {
+            applyPrimitive(productTransformMatrix, primitive);
+        }
+    }
+
+    public void applyPrimitive(Matrix4d productTransformMatrix, HalfEdgePrimitive primitive) {
+        List<HalfEdgeVertex> vertices = primitive.getVertices();
+        for (HalfEdgeVertex vertex : vertices) {
+            applyVertex(productTransformMatrix, vertex);
+        }
+
+        List<HalfEdgeSurface> surfaces = primitive.getSurfaces();
+        for (HalfEdgeSurface surface : surfaces) {
+            // Note: In HalfEdgeScene, the vertices are managed by surfaces, no by primitives
+            List<HalfEdgeVertex> surfaceVertices = surface.getVertices();
+            applySurface(productTransformMatrix, surfaceVertices, surface);
+        }
+    }
+
+    public void applyVertex(Matrix4d productTransformMatrix, HalfEdgeVertex vertex) {
+
+    }
+
+    public void applySurface(Matrix4d productTransformMatrix, List<HalfEdgeVertex> vertices, HalfEdgeSurface surface) {
+        List<HalfEdgeFace> faces = surface.getFaces();
+        for (HalfEdgeFace face : faces) {
+            applyFace(productTransformMatrix, vertices, face);
+        }
+    }
+
+    public void applyFace(Matrix4d productTransformMatrix, List<HalfEdgeVertex> vertices, HalfEdgeFace face) {
+
+    }
+}