dcel-map-generator 0.2.2__tar.gz

dcel_map_generator-0.2.2/.github/workflows/deploy-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Build frontend
+        working-directory: frontend
+        run: npm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: frontend/dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

dcel_map_generator-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,180 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Verify release tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PY_VERSION="$(python - <<'PY'
+          import tomllib
+          with open("pyproject.toml", "rb") as fh:
+              print(tomllib.load(fh)["project"]["version"])
+          PY
+          )"
+          FRONTEND_VERSION="$(python - <<'PY'
+          import json
+          with open("frontend/package.json", "r", encoding="utf-8") as fh:
+              print(json.load(fh)["version"])
+          PY
+          )"
+          if [ "$TAG_VERSION" != "$PY_VERSION" ]; then
+            echo "Tag version $TAG_VERSION does not match pyproject version $PY_VERSION"
+            exit 1
+          fi
+          if [ "$TAG_VERSION" != "$FRONTEND_VERSION" ]; then
+            echo "Tag version $TAG_VERSION does not match frontend version $FRONTEND_VERSION"
+            exit 1
+          fi
+
+      - name: Install Python dependencies
+        run: uv sync --dev
+
+      - name: Run Python tests
+        run: uv run pytest
+
+      - name: Build Python distributions
+        run: uv build
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Build frontend
+        working-directory: frontend
+        run: npm run build
+
+      - name: Prepare release artifact directory
+        run: mkdir -p release-artifacts
+
+      - name: Pack frontend npm package
+        working-directory: frontend
+        run: npm pack --pack-destination ../release-artifacts
+
+      - name: Create release archives
+        run: |
+          cp frontend/public/map_bundle.json release-artifacts/map_bundle.json
+          cp docs/atlantis-map.png release-artifacts/atlantis-map.png
+          tar -C frontend/dist -czf release-artifacts/frontend-dist.tar.gz .
+          tar -C examples -czf release-artifacts/atlantis-example-inputs.tar.gz atlantis
+
+      - name: Upload Python distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/*
+
+      - name: Upload frontend distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: frontend-dist
+          path: |
+            release-artifacts/frontend-dist.tar.gz
+            release-artifacts/*.tgz
+
+      - name: Upload example assets
+        uses: actions/upload-artifact@v4
+        with:
+          name: example-assets
+          path: |
+            release-artifacts/map_bundle.json
+            release-artifacts/atlantis-map.png
+            release-artifacts/atlantis-example-inputs.tar.gz
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*
+            release-artifacts/frontend-dist.tar.gz
+            release-artifacts/*.tgz
+            release-artifacts/map_bundle.json
+            release-artifacts/atlantis-map.png
+            release-artifacts/atlantis-example-inputs.tar.gz
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download Python distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+  publish-npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: release
+    environment:
+      name: npm
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download frontend package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: frontend-dist
+          path: release-artifacts
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Resolve frontend package tarball
+        id: frontend-package
+        run: |
+          shopt -s nullglob
+          tarballs=(release-artifacts/*.tgz)
+          if [ "${#tarballs[@]}" -ne 1 ]; then
+            echo "Expected exactly one frontend package tarball, found ${#tarballs[@]}"
+            ls -la release-artifacts
+            exit 1
+          fi
+          echo "path=./${tarballs[0]}" >> "$GITHUB_OUTPUT"
+
+      - name: Publish renderer package to npm
+        run: npm publish "${{ steps.frontend-package.outputs.path }}" --access public --provenance

dcel_map_generator-0.2.2/.github/workflows/semver-release.yml

@@ -0,0 +1,56 @@
+name: Semver Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+concurrency:
+  group: semver-release-main
+  cancel-in-progress: false
+
+jobs:
+  version-and-tag:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Determine next version
+        id: semver
+        run: python scripts/semver_release.py plan
+
+      - name: Stop when no release is needed
+        if: steps.semver.outputs.changed != 'true'
+        run: echo "No unreleased commits since the latest semantic version tag."
+
+      - name: Apply release version
+        if: steps.semver.outputs.changed == 'true'
+        run: python scripts/semver_release.py apply --version "${{ steps.semver.outputs.version }}"
+
+      - name: Commit and tag release
+        if: steps.semver.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml dcel_builder/__init__.py frontend/package.json frontend/package-lock.json
+          git commit -m "Release v${{ steps.semver.outputs.version }}"
+          git tag "v${{ steps.semver.outputs.version }}"
+          git push origin main --follow-tags
+
+      - name: Trigger release workflow
+        if: steps.semver.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run release.yml --ref "v${{ steps.semver.outputs.version }}"

dcel_map_generator-0.2.2/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+uv.lock
+
+# Distribution / packaging
+dist/
+build/
+node_modules/
+frontend/dist-lib/
+frontend/*.tgz
+*.egg-info/
+*.egg
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+*.tsbuildinfo
+
+# Linting
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*.claude/
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Output files
+dcel_map.json
+dcel_map.png
+debug_label_map.png
+local/
+scripts/__pycache__/
+
+# Secrets / env
+.env
+.env.*
+*.secret

dcel_map_generator-0.2.2/AGENTS.md

@@ -0,0 +1,23 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`dcel_builder/` contains the application code and CLI entry point (`__main__.py`). The current runtime path is small: `tree_loader.py` validates the hierarchy input, `hierarchy.py` builds the recursive raster subdivision, `raster_dcel.py` converts the leaf raster into polygons/DCEL, and `render.py` produces preview PNGs. Core DCEL types and JSON I/O live in `dcel.py` and `serializer.py`. Tests are split into `tests/unit/` for module behavior and `tests/integration/` for CLI/pipeline coverage. Repository-root JSON files are the current sample inputs; generated outputs should stay untracked.
+
+## Build, Test, and Development Commands
+Use Python 3.11+.
+
+- `uv sync --dev`: install runtime and development dependencies.
+- `uv run pytest`: run the full test suite.
+- `uv run pytest tests/unit/test_hierarchy.py`: run a focused unit test file while iterating.
+- `uv run ruff check .`: lint imports and basic style issues.
+- `uv run ruff format .`: apply formatting before opening a PR.
+- `uv run python -m dcel_builder` or `uv run dcel-map`: run the CLI locally.
+
+## Coding Style & Naming Conventions
+Follow PEP 8 with 4-space indentation and a maximum line length of 100 characters, matching `ruff` settings in `pyproject.toml`. Use `snake_case` for modules, functions, variables, and test files; use `PascalCase` only for classes. Keep modules narrowly scoped by responsibility. Prefer explicit type-friendly function signatures and small pure helpers for geometry transforms.
+
+## Testing Guidelines
+Tests use `pytest` and are discovered from `tests/`. Name new files `test_<feature>.py` and new tests `test_<behavior>`. Add unit tests for deterministic logic and integration tests when CLI behavior, JSON I/O, or full pipeline assembly changes. Run `uv run pytest` before submitting changes; update or add fixture data only when behavior intentionally changes.
+
+## Commit & Pull Request Guidelines
+Recent history favors short, imperative commit subjects such as `Implement foundational modules`. Keep the first line concise and descriptive. Pull requests should explain the behavioral change, mention affected modules or specs, and note test coverage. Include sample command output or updated artifact references when CLI behavior or generated map outputs change.

dcel_map_generator-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alonso Cancino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dcel_map_generator-0.2.2/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: dcel-map-generator
+Version: 0.2.2
+Summary: Generate a leaf-level DCEL map from a hierarchical zone tree
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: networkx>=3.4
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: shapely>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DCEL Map Generator
+
+Generate whimsical continent-style maps from a rooted hierarchy and export them as:
+
+- a leaf-level DCEL
+- a rendered preview image
+- a frontend-ready bundle for an interactive zoomable map
+
+This repo is the reusable core. Domain-specific map projects can keep their own hierarchy data and consume this generator/render stack.
+
+[Live Demo](https://alonso-cancino.github.io/map-generator/)
+
+![Atlantis demo map](docs/atlantis-map.png)
+
+## What It Does
+
+The pipeline is tree-first:
+
+1. load a rooted hierarchy from `examples/atlantis/zone_edges.json`
+2. generate a continent mask
+3. recursively partition each parent region among its children
+4. extract leaf polygons from the raster partition
+5. build a DCEL and optional frontend bundle
+
+The bundled demo dataset is a small fantasy world centered on **Atlantis** so you can run the project immediately without bringing your own taxonomy first.
+
+## Quickstart
+
+Requirements:
+
+- Python 3.11+
+- `uv`
+- Node.js 20+ for the frontend demo
+
+Install Python dependencies:
+
+```bash
+uv sync --dev
+```
+
+Generate the demo outputs:
+
+```bash
+uv run python -m dcel_builder \
+  --zone-edges examples/atlantis/zone_edges.json \
+  --tree-stats examples/atlantis/zone_tree_stats.json \
+  --zone-index examples/atlantis/zone_index.json \
+  --output dcel_map.json \
+  --render \
+  --render-output docs/atlantis-map.png \
+  --frontend-bundle frontend/public/map_bundle.json \
+  --validate
+```
+
+Run the interactive renderer locally:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173/`.
+
+## Input Files
+
+The generator expects three JSON files:
+
+- `zone_edges.json`: directed `[parent, child]` pairs forming a rooted tree
+- `zone_index.json`: `{ "id": "name" }` mapping used for labels/tooling
+- `zone_tree_stats.json`: optional sidecar metadata; the generator currently tolerates an empty object
+
+The bundled example describes a three-level fantasy continent:
+
+- `Atlantis`
+- major regions such as `Aurelia Reach`, `Tidehollow`, `Cinder Crown`, `Mistwood`
+- smaller subregions and leaf territories beneath them
+
+The tracked demo inputs live in [`examples/atlantis`](/home/alosc/proyectos/map/examples/atlantis). Private or domain-specific datasets can stay in ignored folders such as `local/`.
+
+## Outputs
+
+- `dcel_map.json`: serialized DCEL
+- `docs/atlantis-map.png`: static render
+- `frontend/public/map_bundle.json`: interactive bundle consumed by the frontend
+
+## GitHub Pages Demo
+
+The frontend is configured for GitHub Pages static hosting. A workflow in `.github/workflows/deploy-pages.yml` builds `frontend/` and publishes the interactive demo using the bundled Atlantis example.
+
+## Versioning
+
+This project uses Semantic Versioning and derives releases from commits on `main`.
+
+- `BREAKING CHANGE` in a commit body, or `type!:` in the subject, increments `MAJOR`
+- subjects starting with `feat`, `add`, or `implement` increment `MINOR`
+- all other changes increment `PATCH`
+
+The automation writes the chosen version into Python and frontend package metadata, commits `Release vX.Y.Z`, and creates the matching `vX.Y.Z` tag.
+
+## Releases
+
+Pushing to `main` triggers the semantic version workflow in `.github/workflows/semver-release.yml`. That workflow computes the next version, commits the versioned files, and pushes the matching release tag. The tag then triggers `.github/workflows/release.yml`.
+
+Each release publishes consumable artifacts:
+
+- Python source distribution and wheel from `dist/`
+- a production frontend archive, `frontend-dist.tar.gz`
+- an npm package tarball for the renderer, `alonso-cancino-dcel-map-frontend-<version>.tgz`
+- the example frontend bundle, `map_bundle.json`
+- the Atlantis example inputs as `atlantis-example-inputs.tar.gz`
+- the demo screenshot, `atlantis-map.png`
+
+You can consume the renderer package from npm by installing the published tarball, or later from the npm registry once it is published there. The library entrypoint exports `MapView`, `loadBundle`, `parseBundle`, and the bundle/type definitions.
+
+When the repository is configured for trusted publishing, the same release workflow also publishes:
+
+- the Python package to PyPI
+- the renderer package to npm
+
+### One-time registry setup
+
+To make automated publishing work, you still need to configure each registry once:
+
+1. PyPI:
+Create the `dcel-map-generator` project on PyPI, then add a Trusted Publisher for this GitHub repository and the workflow file `release.yml`.
+
+2. npm:
+Create the `@alonso-cancino/dcel-map-frontend` package on npm, then add a Trusted Publisher for this GitHub repository and the workflow file `release.yml`.
+
+3. GitHub:
+If you want deployment protection, create `pypi` and `npm` environments in the repository settings to match the workflow.
+
+After that, pushing to `main` will create the next semantic version release and publish both packages automatically.
+
+## Development
+
+```bash
+uv run pytest
+uv run ruff check .
+cd frontend && npm run build
+```
+
+Contributor conventions live in `AGENTS.md`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).