geojac 0.2.2__tar.gz

geojac-0.2.2/.dockerignore

@@ -0,0 +1,10 @@
+build/
+.venv/
+outputs/
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.git/
+.pytest_cache/

geojac-0.2.2/.envrc

@@ -0,0 +1 @@
+use flake

geojac-0.2.2/.github/workflows/wheels.yml

@@ -0,0 +1,139 @@
+name: Build Wheels
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+    tags:
+      - 'v*'
+  pull_request:
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      # cibuildwheel automatically downloads the cibuildwheel docker images for linux
+      # and runs the build process across different python versions.
+      - name: Cache vcpkg installed packages
+        uses: actions/cache@v4
+        if: runner.os == 'Windows'
+        with:
+          path: C:\vcpkg\installed
+          key: ${{ runner.os }}-vcpkg-boost-full
+          restore-keys: |
+            ${{ runner.os }}-vcpkg-
+
+      # Homebrew bottles are compiled against the runner's OS version.
+      # Capture it so cibuildwheel's deployment target matches exactly,
+      # preventing delocate-wheel from rejecting mismatched LC_BUILD_VERSION.
+      - name: Detect macOS deployment target
+        if: runner.os == 'macOS'
+        id: macos-target
+        run: echo "version=$(sw_vers -productVersion | cut -d. -f1)" >> $GITHUB_OUTPUT
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.22.0
+        env:
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_BEFORE_ALL_LINUX: "dnf install -y gmp-devel mpfr-devel boost-devel"
+          CIBW_BEFORE_ALL_MACOS: "brew install gmp mpfr boost"
+          CIBW_ENVIRONMENT_MACOS: >-
+            MACOSX_DEPLOYMENT_TARGET=${{ steps.macos-target.outputs.version }}
+            CMAKE_OSX_DEPLOYMENT_TARGET=${{ steps.macos-target.outputs.version }}
+          CIBW_BEFORE_ALL_WINDOWS: "vcpkg install boost:x64-windows gmp:x64-windows mpfr:x64-windows"
+          CIBW_BEFORE_BUILD_WINDOWS: "pip install delvewheel"
+          CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: "delvewheel repair --add-path C:\\vcpkg\\installed\\x64-windows\\bin -w {dest_dir} {wheel}"
+          CIBW_SKIP: "cp36-* cp37-* cp38-* pp* *-musllinux_* *i686* *win32*" # Omitir versiones muy viejas o 32 bits
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  benchmark:
+    name: Run thesis benchmark
+    runs-on: ubuntu-24.04
+    if: github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache OSM network data
+        uses: actions/cache@v4
+        with:
+          path: cache/
+          key: osm-cache-barranco-v1
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            python3 python3-pip python3-dev \
+            build-essential cmake git pkg-config \
+            pybind11-dev \
+            libboost-all-dev libgmp-dev libmpfr-dev libcgal-dev \
+            libspatialindex-dev libgeos-dev libproj-dev \
+            libgl1 libglib2.0-0
+          pip3 install -r requirements.txt --break-system-packages
+
+      - name: Build C++ extension
+        run: |
+          mkdir -p build
+          cd build
+          cmake ..
+          make -j$(nproc)
+
+      - name: Run benchmark
+        env:
+          PYTHONPATH: ${{ github.workspace }}/build:${{ github.workspace }}/src
+        run: python3 scripts/run_benchmark.py
+
+      - name: Upload benchmark outputs
+        uses: actions/upload-artifact@v4
+        with:
+          name: tesis-benchmark-results
+          path: outputs/
+          retention-days: 90
+
+  upload_pypi:
+    name: Upload to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    # Se ejecutará automáticamente al pushear a main o al crear un Tag
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

geojac-0.2.2/.gitignore

@@ -0,0 +1,53 @@
+# Build artifacts
+build/
+*.so
+*.o
+*.a
+*.dylib
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.env
+
+# OS
+.DS_Store
+Thumbs.db
+
+# CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+build/Makefile
+*.cmake
+
+# Keep only the main CMakeLists.txt files and root Makefile
+!CMakeLists.txt
+!acj/core/CMakeLists.txt
+!Makefile
+
+# ACJ specific
+cache/
+output/
+outputs/
+*.tar.xz
+
+# NixOs / direnv
+.direnv/
+.venv/

geojac-0.2.2/CMakeLists.txt

@@ -0,0 +1,80 @@
+cmake_minimum_required(VERSION 3.15)
+project(acj_project LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release)
+endif()
+
+find_package(Python3 COMPONENTS Interpreter Development.Module REQUIRED)
+find_package(pybind11 CONFIG REQUIRED)
+
+# Use FetchContent to extract the local CGAL tarball during build
+include(FetchContent)
+FetchContent_Declare(
+  CGAL
+  URL https://github.com/CGAL/cgal/releases/download/v6.0.1/CGAL-6.0.1.tar.xz
+)
+FetchContent_Populate(CGAL)
+
+# PATCH CGAL BUG in AABB_traits_2.h
+file(READ "${cgal_SOURCE_DIR}/include/CGAL/AABB_traits_2.h" AABB_TRAITS_CONTENT)
+string(REPLACE "bb,true)?" "bb)?" AABB_TRAITS_CONTENT "${AABB_TRAITS_CONTENT}")
+file(WRITE "${cgal_SOURCE_DIR}/include/CGAL/AABB_traits_2.h" "${AABB_TRAITS_CONTENT}")
+# CGAL is header-only from 5.0+, just add the include directories
+add_library(CGAL::CGAL INTERFACE IMPORTED)
+target_include_directories(CGAL::CGAL INTERFACE "${cgal_SOURCE_DIR}/include")
+
+# Find Boost (strictly required by CGAL)
+if(NOT WIN32)
+    find_package(Boost REQUIRED)
+endif()
+
+if(WIN32)
+    # === WINDOWS LOGIC ===
+    # Include vcpkg globally for gmp/mpfr and EXACTLY inject Boost include path like the experiment!
+    include_directories("C:/vcpkg/installed/x64-windows/include")
+
+    find_library(GMP_LIBRARY gmp PATHS "C:/vcpkg/installed/x64-windows/lib" NO_DEFAULT_PATH)
+    find_library(MPFR_LIBRARY mpfr PATHS "C:/vcpkg/installed/x64-windows/lib" NO_DEFAULT_PATH)
+    if(GMP_LIBRARY AND MPFR_LIBRARY)
+        target_link_libraries(CGAL::CGAL INTERFACE ${GMP_LIBRARY} ${MPFR_LIBRARY})
+    endif()
+
+elseif(APPLE)
+    # === MACOS LOGIC ===
+    if(TARGET Boost::headers)
+        target_link_libraries(CGAL::CGAL INTERFACE Boost::headers)
+    elseif(TARGET Boost::boost)
+        target_link_libraries(CGAL::CGAL INTERFACE Boost::boost)
+    elseif(Boost_INCLUDE_DIRS)
+        target_include_directories(CGAL::CGAL INTERFACE "${Boost_INCLUDE_DIRS}")
+    endif()
+
+    find_library(GMP_LIBRARY gmp)
+    find_library(MPFR_LIBRARY mpfr)
+    if(GMP_LIBRARY AND MPFR_LIBRARY)
+        target_link_libraries(CGAL::CGAL INTERFACE ${GMP_LIBRARY} ${MPFR_LIBRARY})
+    endif()
+
+else()
+    # === LINUX (UBUNTU) LOGIC ===
+    if(TARGET Boost::headers)
+        target_link_libraries(CGAL::CGAL INTERFACE Boost::headers)
+    elseif(TARGET Boost::boost)
+        target_link_libraries(CGAL::CGAL INTERFACE Boost::boost)
+    elseif(Boost_INCLUDE_DIRS)
+        target_include_directories(CGAL::CGAL INTERFACE "${Boost_INCLUDE_DIRS}")
+    endif()
+
+    find_library(GMP_LIBRARY gmp)
+    find_library(MPFR_LIBRARY mpfr)
+    if(GMP_LIBRARY AND MPFR_LIBRARY)
+        target_link_libraries(CGAL::CGAL INTERFACE ${GMP_LIBRARY} ${MPFR_LIBRARY})
+    endif()
+endif()
+
+add_compile_definitions(CGAL_DO_NOT_USE_BOOST_MP)
+add_subdirectory(src/geojac/core)

geojac-0.2.2/Dockerfile

@@ -0,0 +1,67 @@
+FROM ubuntu:noble
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG uid
+ARG gid
+ARG user
+ARG group
+
+# Ubuntu 24.04 enforces PEP 668 (externally-managed Python).
+# This env var allows pip to install into the system Python without a venv.
+ENV PIP_BREAK_SYSTEM_PACKAGES=1
+
+RUN apt-get update
+RUN apt-get install -y tzdata
+RUN apt-get upgrade -y
+
+RUN echo 'alias ll="ls -l --color -a"' >> /root/.bashrc
+
+# Python 3.12 is the default on ubuntu:noble
+RUN apt-get install -y python3 python3-pip python3-dev python3-venv
+
+# C++ build tools
+RUN apt-get install -y build-essential cmake git pkg-config
+RUN apt-get install -y pybind11-dev
+RUN apt-get install -y xz-utils
+RUN apt-get install -y g++
+
+# CGAL arithmetic dependencies (CGAL headers are downloaded by CMake FetchContent)
+RUN apt-get install -y libboost-all-dev
+RUN apt-get install -y libgmp-dev
+RUN apt-get install -y libmpfr-dev
+# System CGAL satisfies any residual cmake detection; FetchContent supplies v6.0.1 headers
+RUN apt-get install -y libcgal-dev
+
+# Geospatial system libraries
+RUN apt-get install -y libspatialindex-dev libgeos-dev libproj-dev
+
+# Display / Qt libraries (libgl1 replaces libgl1-mesa-glx on ubuntu:noble)
+RUN apt-get install -y libgl1 libglib2.0-0 libsm6 libxrender1 libxext6 libfontconfig1
+RUN apt-get install -y python3-pyqt5 python3-pyqt5.qtopengl
+
+RUN rm -rf /var/lib/apt/lists/*
+
+RUN mkdir -p /workspace
+
+# ubuntu:noble ships a default 'ubuntu' user at UID 1000 — remove it before
+# creating our own user so useradd does not fail on a duplicate UID.
+RUN userdel -r ubuntu 2>/dev/null || true
+RUN groupadd -g ${gid} ${group} || true
+RUN useradd -m -u ${uid} -g ${gid} -s /bin/bash ${user} || true
+
+RUN echo 'alias ll="ls -l --color -a"' >> /home/${user}/.bashrc || true
+
+RUN chown -R ${uid}:${gid} /workspace
+
+USER ${user}
+WORKDIR /workspace
+
+COPY --chown=${user}:${group} . /workspace/
+
+RUN pip3 install -r requirements.txt
+
+RUN mkdir -p build
+WORKDIR /workspace/build
+RUN cmake .. && make -j$(nproc)
+
+WORKDIR /workspace

geojac-0.2.2/Makefile

@@ -0,0 +1,79 @@
+.PHONY: build shell shell-user test example example-realtime example-simplification example-simplification-visual example-crime example-crime-osm example-simplification-osm example-minkowski-osm clean clean-all help
+
+.DEFAULT_GOAL := help
+
+help:
+	@echo "ACJ Library - Makefile Commands"
+	@echo "================================"
+	@echo ""
+	@echo "Main commands:"
+	@echo "  make build                             - Build Docker image with all dependencies"
+	@echo "  make test                              - Run ACJ library tests"
+	@echo ""
+	@echo "Examples with synthetic data:"
+	@echo "  make example                           - Basic ACJ example"
+	@echo "  make example-simplification-visual     - Graph simplification demo (synthetic)"
+	@echo "  make example-crime                     - Crime heatmap demo (synthetic)"
+	@echo ""
+	@echo "Examples with real OSM data (configurable city):"
+	@echo "  make example-realtime                  - Real-time crime heatmap"
+	@echo "  make example-simplification            - Graph simplification comparison"
+	@echo "  make example-minkowski-osm       		- Minkowski simplification (configurable location)"
+	@echo "  make example-crime-osm                 - Crime heatmap (configurable location)"
+	@echo "  make example-simplification-osm        - Simplification (configurable location)"
+	@echo ""
+	@echo "Cleanup commands:"
+	@echo "  make clean                             - Clean build artifacts"
+	@echo "  make clean-all                         - Clean everything including Docker cache"
+	@echo ""
+	@echo "Development commands:"
+	@echo "  make shell                             - Open Docker shell as root"
+	@echo "  make shell-user                        - Open Docker shell as user"
+
+# Build Docker image
+build:
+	docker build -f Dockerfile -t ubuntu-geojac:1 --build-arg uid="$(shell id -u)" --build-arg gid="$(shell id -g)" --build-arg user=dockeruser --build-arg group=dockergroup .
+
+# Interactive shells
+shell:
+	docker run -v $(shell pwd):/workspace -w /workspace -it ubuntu-geojac:1 /bin/bash
+
+shell-user:
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -w /workspace -it ubuntu-geojac:1 /bin/bash
+
+# ACJ Library commands (Actualizado para Arquitectura src/)
+test: ## Run ACJ library test suite
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 -m pytest tests/ -v"
+
+example: ## Run basic ACJ library example
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_acj.py"
+
+example-realtime: ## Run real-time interactive visualization with VisPy
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$$DISPLAY ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_realtime.py"
+
+example-simplification: ## Run graph simplification comparison
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$$DISPLAY ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_simplification.py"
+
+example-simplification-visual: ## Run visual graph simplification demo with interactive comparison
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$$DISPLAY ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_simplification_visual.py"
+
+example-crime: ## Run crime heatmap visualization demo with interactive comparison
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$$DISPLAY ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_crime_visualization.py"
+
+example-crime-osm: ## Run crime heatmap with real OSM data (configurable location)
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$$DISPLAY ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_crime_osm.py"
+
+example-simplification-osm: ## Run simplification comparison with real OSM data (configurable location)
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$$DISPLAY ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_simplification_osm.py"
+
+example-minkowski-osm: ## Run Minkowski simplification with real OSM data (configurable location)
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$$DISPLAY ubuntu-geojac:1 sh -c "cd /workspace && mkdir -p build && cd build && cmake .. && make -j\$$(nproc) && cd .. && PYTHONPATH=/workspace/build:/workspace/src python3 examples/example_minkowski_osm.py"
+
+
+# Cleanup
+clean: ## Clean build artifacts
+	rm -rf build/ cache/ output/
+
+clean-all: ## Clean everything including Docker cache
+	rm -rf build/ cache/ output/
+	docker rmi ubuntu-geojac:1 || true

geojac-0.2.2/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.2
+Name: geojac
+Version: 0.2.2
+Summary: Simplificacion de grafos urbanos y analisis de criminalidad
+Author-Email: ACJ Team <acj-team@utec.edu.pe>
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: networkx
+Requires-Dist: geopandas
+Requires-Dist: osmnx
+Provides-Extra: viz
+Requires-Dist: vispy; extra == "viz"
+Requires-Dist: PyQt5; extra == "viz"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Description-Content-Type: text/markdown
+
+# ACJ: Urban Graph Acceleration & Simplification Framework
+
+![Python](https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python&logoColor=white)
+![C++](https://img.shields.io/badge/C++-17-00599C.svg?logo=c%2B%2B&logoColor=white)
+![PyPI](https://img.shields.io/pypi/v/geojac.svg)
+![License](https://img.shields.io/badge/License-MIT-green.svg)
+
+**ACJ** is a high-performance hybrid C++/Python framework for the semantic and topological simplification of large-scale urban street networks. It safely decouples topology from semantic metadata (speed limits, road names, etc.) so that both survive massive graph reductions powered by a CGAL-accelerated C++ core.
+
+---
+
+## Installation
+
+ACJ is published on PyPI and ships with pre-compiled wheels for Linux, macOS (Apple Silicon & Intel), and Windows. No C++ compilation required.
+
+```bash
+pip install geojac
+```
+
+For GPU-accelerated real-time visualization, install the optional extras:
+
+```bash
+pip install "geojac[viz]"
+```
+
+> We recommend working inside a virtual environment: `python -m venv venv && source venv/bin/activate`
+
+---
+
+## Quick Start — End-to-End Pipeline
+
+```python
+import osmnx as ox
+from geojac import UrbanNetwork, ACJTopologicalEvaluator
+from geojac import CompressionRatioMetric, SemanticSpeedDistortionMetric
+
+# 1. Fetch a raw street network
+G = ox.graph_from_place("Barranco, Lima, Peru", network_type="drive")
+
+# 2. Parse into the ACJ registry
+network = UrbanNetwork.from_networkx(G)
+print(network)
+# <UrbanNetwork | Nodes: 312 (Meta: True) | Edges: 847 (Meta: True)>
+
+# 3. Configure metrics and run the evaluator
+metrics = [CompressionRatioMetric(), SemanticSpeedDistortionMetric()]
+evaluator = ACJTopologicalEvaluator(network, metrics)
+results = evaluator.evaluate()
+
+print(results)
+print(evaluator.simplified_network)
+```
+
+---
+
+## API Reference
+
+### `UrbanNetwork` — Core Data Container
+
+The central data structure. Stores topology in Pandas DataFrames and semantic attributes in dictionaries, keeping them decoupled for safe C++ operations.
+
+```python
+from geojac import UrbanNetwork
+
+# From an OSMnx / NetworkX graph
+network = UrbanNetwork.from_networkx(G)
+
+# From raw DataFrames
+# nodes_df must have columns: node_id, x, y  (+ any metadata columns)
+# edges_df must have columns: segment_id, node_start, node_end  (+ any metadata columns)
+network = UrbanNetwork.from_dataframe(nodes_df, edges_df)
+```
+
+**Key attributes:**
+
+| Attribute | Type | Description |
+|---|---|---|
+| `nodes_df` | `pd.DataFrame` | Node topology: `node_id`, `x`, `y` |
+| `edges_df` | `pd.DataFrame` | Edge topology: `segment_id`, `node_start`, `node_end` |
+| `node_metadata` | `dict` | Per-node semantic attributes keyed by `node_id` |
+| `edge_metadata` | `dict` | Per-edge semantic attributes keyed by `segment_id` |
+
+---
+
+### `MapIndex` — Spatial Queries
+
+CGAL-backed spatial index for fast nearest-neighbor point-to-graph assignment. Useful for correlating events (e.g., crime incidents) with street segments or intersections.
+
+```python
+from geojac import MapIndex, load_graph
+import pandas as pd
+
+graph_data = load_graph(nodes_df, edges_df)
+index = MapIndex(graph_data)
+
+# Assign point events to the nearest node
+points = pd.DataFrame({'point_id': [1, 2], 'x': [-77.02, -77.03], 'y': [-12.15, -12.14]})
+node_assignments = index.assign_to_endpoints(points)
+# Returns original DataFrame + 'assigned_node_id' and 'distance' columns
+
+# Assign point events to the nearest edge segment
+segment_assignments = index.assign_to_segments(points)
+# Returns original DataFrame + 'assigned_segment_id' and 'distance' columns
+```
+
+---
+
+### `ACJTopologicalEvaluator` — Simplification Lifecycle
+
+Automates the full pipeline: injects the network into the C++ core, receives the simplified topology with lineage maps, runs semantic resolution, and applies metrics.
+
+```python
+from geojac import ACJTopologicalEvaluator, CompressionRatioMetric, SemanticSpeedDistortionMetric
+
+evaluator = ACJTopologicalEvaluator(network, metrics=[
+    CompressionRatioMetric(),
+    SemanticSpeedDistortionMetric(),
+])
+results = evaluator.evaluate()
+
+simplified = evaluator.simplified_network  # UrbanNetwork
+```
+
+**Built-in metrics:**
+
+| Class | Measures |
+|---|---|
+| `CompressionRatioMetric` | Node/edge reduction ratio after simplification |
+| `SemanticSpeedDistortionMetric` | Speed-limit distribution distortion introduced by edge merging |
+
+---
+
+### Visualization (optional `viz` extra)
+
+GPU-accelerated interactive tools built on VisPy/OpenGL. Requires `pip install "geojac[viz]"`.
+
+```python
+from geojac import MapIndex, load_graph
+from geojac import render_graph, render_heatmap, render_comparison
+
+graph_data = load_graph(nodes_df, edges_df)
+index = MapIndex(graph_data)
+
+# Render the raw street network
+render_graph(index)
+
+# Render a heatmap of point assignments over the network
+render_heatmap(index, assignments=node_assignments)
+
+# Side-by-side comparison of two networks (e.g., original vs. simplified)
+render_comparison(
+    index_original, index_simplified,
+    title_left="Original", title_right="Simplified"
+)
+```
+
+**Interactive controls (all render functions):**
+
+| Key | Action |
+|---|---|
+| `N` | Toggle node layer |
+| `L` | Toggle segment layer |
+| `G` | Toggle grid |
+| `R` | Reset camera view |
+| `Q` / `Esc` | Close window |
+
+---
+
+### `load_graph` / `load_map` — Data IO
+
+```python
+from geojac import load_graph, load_map
+
+# Build a GraphData object from DataFrames (required input for MapIndex)
+graph_data = load_graph(nodes_df, edges_df)
+
+# Load from a file path (GeoJSON, Shapefile, etc.)
+graph_data = load_map("path/to/network.geojson")
+```
+
+---
+
+## Developer Installation (From Source)
+
+Required: CMake ≥ 3.15, C++17, CGAL, Boost, pybind11.
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install cmake libcgal-dev libboost-all-dev
+
+# Arch Linux
+sudo pacman -S cmake cgal boost pybind11
+```
+
+```bash
+git clone https://github.com/CdeCasurpie/CS5351-acj.git
+cd CS5351-acj
+python -m venv venv && source venv/bin/activate
+pip install -U pip setuptools wheel
+pip install -e .
+```
+
+---
+
+## Academic Team & Acknowledgements
+
+This framework was developed as part of a thesis research project at the Universidad de Ingeniería y Tecnología (UTEC).
+
+**Lead Researchers & Engineers:**
+* Alejandro Calizaya
+* Cesar Perales
+* Jerimy Sandoval
+
+**Thesis Advisors:**
+* **Eric Javier Biagioli** - Academic Director, Department of Computer and Data Science, UTEC ([ORCID: 0009-0000-2027-0647](https://orcid.org/0009-0000-2027-0647))
+* **Germain García Zanabria** - Researcher, Artificial Intelligence Research Group (GINIA), UTEC ([ORCID: 0000-0003-3266-9043](https://orcid.org/0000-0003-3266-9043))