GSAP Geometry Core

Java-based geometry and processing engine for parametric 2D shape manufacturing workflows.
It validates incoming shape definitions, resolves parametric data, and generates Java outputs used by downstream preview and execution systems.

What This Project Does

GSAP Geometry Core acts as the processing backend between editor-created shape JSON and manufacturing-ready generated artifacts.

Primary responsibilities:

• Parse and normalize shape JSON (legacy and parametric formats)
• Validate geometric correctness with tolerance-aware rules
• Execute shape-processing pipeline logic
• Generate dual Java output classes per shape (ShapeTransformer + ShapePreview)
• Run as a Redis + MySQL worker in integrated environments

High-Level Architecture

Shape JSON (from editor / DB)
          |
          v
      ShapeLoader
          |
          v
   Domain Model (Point, Edge, Shape, ...)
          |
          v
    GeometryValidator
          |
          v
   Shape Pipeline + Generators
          |
          v
  Generated Java output artifacts

For deeper architecture details, see Documentation/ARCHITECTURE.md.

Key Features

Geometry domain model

• Immutable primitives and edge types (LineEdge, ArcEdge)
• Epsilon-aware comparisons for numerical stability
• Utility methods for perimeter and geometry calculations

Multi-format loading

• Supports legacy v1.0 shape definitions
• Supports v2.0 parametric definitions with expression-based points
• DTO-based parsing boundary to keep domain model safe and strict

Validation engine

• Enforces minimum topology requirements
• Checks closure and edge connectivity
• Flags invalid or degenerate geometry
• Returns aggregated validation errors instead of failing fast on first issue

Parametric dual-output generation

• Produces two Java outputs for each processed shape:
  • ShapeTransformer for execution logic
  • ShapePreview for visualization metadata

See PARAMETRIC_FORMAT.md and DUAL_OUTPUT.md for full contracts.

Repository Structure

GSAP Geometry Core/
|- src/main/java/com/company/gsap/
|  |- model/                # Domain types (edges, points, shape)
|  |- loader/               # JSON parsing + DTOs
|  |- validation/           # Geometry validation rules
|  |- pipeline/             # Shape processing orchestration
|  |- generator/            # Java output generation
|  |- engine/                # Geometry engine, SVG, measurements (adjacent to pipeline)
|  `- worker/                # Redis/MySQL worker runtime
|- src/test/                # Unit and integration-style tests
|- shapes/                  # Input/output working directories
|- Documentation/           # Format specs, architecture, quick reference
|- pom.xml                  # Maven build configuration
`- README.md

Prerequisites

• Java 17+
• Maven 3.6+
• MySQL (for worker/database integration mode)
• Redis (for queue consumption mode)

Build and Test

mvn clean test

Useful commands:

• mvn compile - compile source only
• mvn test - run tests
• mvn -q exec:java - run worker entrypoint (WorkerApplication)
• mvn -q -DskipTests package - build fat jar via shade plugin

Generated jar:

• target/gsap-geometry-worker.jar

Run jar directly:

java -jar target/gsap-geometry-worker.jar

Running Worker Mode

Main class: com.company.gsap.worker.WorkerApplication

The worker:

• Reads jobs from Redis list key
• Fetches and updates shape state in MySQL
• Runs pipeline/generation
• Writes output to configured output directory

Environment Variables

The worker reads these env vars:

• JDBC_URL (optional if MYSQL_* provided)
• MYSQL_HOST (default localhost)
• MYSQL_PORT (default 3306)
• MYSQL_DATABASE (default gsap_editor)
• MYSQL_USER (default root)
• MYSQL_PASSWORD
• REDIS_HOST (default 127.0.0.1)
• REDIS_PORT (default 6379)
• REDIS_PASSWORD (optional)
• SHAPE_JOB_LIST_KEY (default gsap:shape-processing:jobs)
• OUTPUT_DIR (default shapes/output)

Example (PowerShell):

$env:MYSQL_HOST="localhost"
$env:MYSQL_PORT="3306"
$env:MYSQL_DATABASE="gsap_editor"
$env:MYSQL_USER="root"
$env:MYSQL_PASSWORD="your_password"
$env:REDIS_HOST="127.0.0.1"
$env:REDIS_PORT="6379"
$env:SHAPE_JOB_LIST_KEY="gsap:shape-processing:jobs"
$env:OUTPUT_DIR="shapes/output"
mvn -q exec:java

Input and Output Directories

Typical local flow:

• Place shape payloads in shapes/input/ (if running file-based pipeline tooling)
• Generated Java outputs are written to shapes/output/
• Processed/failed input routing depends on pipeline mode and configuration

Example Usage in Code

ShapeLoader loader = new ShapeLoader();
Shape shape = loader.load("path/to/shape.json");

GeometryValidator validator = new GeometryValidator();
ValidationResult result = validator.validate(shape);

if (result.isValid()) {
    System.out.println("Shape valid: " + shape.getName());
} else {
    result.getErrors().forEach(System.err::println);
}

---

🤝 Contributing

This is a personal/Research project. Not currently accepting contributions, but feel free to fork and experiment.

---

How to build and run

In IntelliJ IDEA

1. Import the project as a Maven project (File → Open → project root or pom.xml).
2. Open the Maven tool window (View → Tool Windows → Maven).
3. Build and test: Lifecycle → clean, then test or install.
4. Run the worker: Plugins → exec → exec:java (this starts WorkerApplication; ensure Redis and MySQL are available and env vars are set — see Running Worker Mode).

From the command line

mvn clean test
mvn -q exec:java

exec:java runs the Redis + MySQL worker, not a standalone “watch input folder” CLI. To exercise the JSON pipeline locally, use unit/integration tests or embed ShapePipeline in your own code.

Typical directories

When using file-based tooling or tests, inputs and outputs often live under shapes/input/ and shapes/output/; the worker uses OUTPUT_DIR (default shapes/output) for generated artifacts.

---

Documentation (this repo)

• Documentation/DOCUMENTATION_INDEX.md — navigation
• Documentation/ARCHITECTURE.md — pipeline architecture
• Documentation/PARAMETRIC_FORMAT.md — v2.0 JSON schema
• Documentation/DUAL_OUTPUT.md — generated Java outputs
• Documentation/QUICK_REFERENCE.md — commands and APIs

Troubleshooting

IntelliJ shows many errors on import

Open the project via File → Open → pom.xml → “Open as Project”, then wait for Maven indexing.

Tests fail with InvalidPathException

Resolved in code by using Paths.get(resource.toURI()) instead of URL.getPath() on Windows.

Build warnings about encoding

pom.xml sets <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>.

Runtime and integration

• MySQL connection errors: verify MYSQL_* / JDBC_URL and database availability.
• Redis connection errors: verify REDIS_HOST / REDIS_PORT and server state.
• No generated files: ensure OUTPUT_DIR exists or is creatable; check worker logs.
• Test path issues on Windows: avoid raw URL paths for classpath resources; prefer URI-based resolution.

Roadmap

Project: GSAP Geometry Core
Started: February 2026
Author: Damitha Samarakoon

License

MIT