acj 0.1.0__tar.gz

acj-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,53 @@
+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-
+
+      - 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="15.0"'
+          CIBW_BEFORE_ALL_WINDOWS: "vcpkg install boost:x64-windows gmp:x64-windows mpfr:x64-windows"
+          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

acj-0.1.0/.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/
+*.tar.xz
+
+# NixOs / direnv
+.direnv/
+.venv/
+.envrc

acj-0.1.0/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/acj/core)

acj-0.1.0/Dockerfile

@@ -0,0 +1,62 @@
+FROM ubuntu:jammy
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG uid
+ARG gid
+ARG user
+ARG group
+
+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
+
+RUN apt-get install -y python3 python3-pip python3-dev
+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++
+RUN apt-get install -y libboost-all-dev
+RUN apt-get install -y libgmp-dev
+RUN apt-get install -y libmpfr-dev
+
+RUN apt-get install -y libcgal-dev
+
+RUN mkdir -p /tmp/cgal
+COPY CGAL-6.0.1.tar.xz /tmp/cgal/
+RUN cd /tmp/cgal && tar -xf CGAL-6.0.1.tar.xz
+RUN cd /tmp/cgal/CGAL-6.0.1 && mkdir -p build
+RUN cd /tmp/cgal/CGAL-6.0.1/build && cmake ..
+RUN cd /tmp/cgal/CGAL-6.0.1/build && make install
+RUN rm -rf /tmp/cgal
+
+RUN apt-get install -y libspatialindex-dev libgeos-dev libproj-dev
+
+RUN apt-get install -y libgl1-mesa-glx 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
+
+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

acj-0.1.0/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-acj: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-acj:1 /bin/bash
+
+shell-user:
+	docker run --user $(shell id -u):$(shell id -g) -v $(shell pwd):/workspace -w /workspace -it ubuntu-acj: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-acj: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-acj: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-acj: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-acj: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-acj: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-acj: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-acj: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-acj: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-acj: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-acj:1 || true

acj-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.2
+Name: acj
+Version: 0.1.0
+Summary: Simplificacion de grafos urbanos y analisis de criminalidad
+Author-Email: Alejandro <alejandro.calizaya@utec.edu.pe>, Cesar <cesar.perales@utec.edu.pe>, Jerimy <jerimy.sandoval@utec.edu.pe>
+Requires-Python: >=3.10
+Requires-Dist: pybind11
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: osmnx
+Requires-Dist: vispy
+Requires-Dist: PyQt5
+Requires-Dist: pytest
+Requires-Dist: geopandas
+Requires-Dist: networkx
+

acj-0.1.0/README.md

@@ -0,0 +1,122 @@
+# 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)
+![CMake](https://img.shields.io/badge/CMake-3.15+-064F8C.svg?logo=cmake&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green.svg)
+
+**ACJ** is a high-performance hybrid framework (C++/Python) designed for the semantic and topological simplification of large-scale urban networks. It safely decouples complex geometric operations from semantic data attributes, ensuring that metadata (e.g., speed limits, road names) survives massive graph reductions.
+
+## System Architecture
+
+The core philosophy of ACJ relies on treating `UrbanNetwork` as an invariant Registry/Proxy. Heavy geometric simplifications are sent to a highly optimized C++ core using CGAL. The core returns the simplified topology alongside strict lineage maps, which Python then uses to reconstruct and resolve semantic collisions.
+
+```mermaid
+graph TD
+    subgraph Inputs ["Multimodal Inputs"]
+        A1[OSMnx]
+        A2[DataFrames]
+        A3[Shapefiles]
+    end
+
+    A1 -->|from_networkx| B
+    A2 -->|from_dataframe| B
+    A3 -->|Parsers| B
+
+    subgraph Python ["Python Layer"]
+        B[UrbanNetwork <br/> Registry/Proxy]
+        E[Semantic Resolution <br/> Metadata Fusion]
+        F[Metrics & Evaluator]
+    end
+
+    subgraph Cpp ["C++ Core (CGAL/pybind11)"]
+        C[Raw Topology <br/> V, E matrices]
+        D[Geometric & Topological <br/> Simplification Algorithms]
+    end
+
+    B -.->|Passes Topology| C
+    C --> D
+    D -.->|SimplificationResult <br/> Topology + Lineage Maps| E
+    B -.->|Passes Metadata| E
+
+    E -->|Resolved UrbanNetwork| F
+```
+
+## Installation Guide
+
+### Prerequisites
+You need a system with C++17 support, CMake, and the following libraries:
+- **CGAL** (Computational Geometry Algorithms Library)
+- **Boost**
+- **pybind11**
+
+On Ubuntu/Debian:
+```bash
+sudo apt-get update
+sudo apt-get install cmake libcgal-dev libboost-all-dev
+```
+On Arch Linux:
+```bash
+sudo pacman -S cmake cgal boost pybind11
+```
+
+### Building the Package
+We highly recommend setting up a virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -U pip setuptools wheel
+```
+
+Install the package in editable mode (which will trigger CMake build):
+
+```bash
+pip install -e .
+```
+
+## Quick Start (E2E Pipeline)
+
+This demonstrates the end-to-end pipeline: extracting raw data, parsing, executing a highly optimized topological simplification, and calculating compression metrics.
+
+```python
+import osmnx as ox
+from acj import UrbanNetwork, ACJTopologicalEvaluator
+from acj import CompressionRatioMetric, SemanticSpeedDistortionMetric
+
+# 1. Ingest Data (Raw Graph)
+G = ox.graph_from_place("Barranco, Lima, Peru", network_type="drive")
+
+# 2. Parse into Multimodal Registry
+network = UrbanNetwork.from_networkx(G)
+print("Initial:", network)
+
+# 3. Setup Metrics and Evaluator
+metrics = [CompressionRatioMetric(), SemanticSpeedDistortionMetric()]
+evaluator = ACJTopologicalEvaluator(network, metrics)
+
+# 4. Evaluate (C++ Topo Simplification + Semantic Resolution)
+results = evaluator.evaluate()
+
+print("Results:", results)
+print("Simplified:", evaluator.simplified_network)
+```
+
+## Module Structure (API Reference)
+
+### `acj.core` (The Heart of the Framework)
+This module acts as the central orchestrator for data decoupling.
+- **`UrbanNetwork`**: The fundamental data structure of the library. It stores raw network topologies in heavily optimized Pandas DataFrames alongside dictionaries of semantic metadata. Supports multimodal ingestion from `NetworkX`, `osmnx`, or arbitrary DataFrames.
+- **`resolve_semantics()`**: The pure Python metadata fusion engine. When a graph is collapsed by C++, this function takes the topological lineage map and automatically resolves semantic collisions (e.g., averaging max speeds or concatenating street names) to keep information loss at 0.
+
+### `acj.algorithms` (Python Wrappers & Indexing)
+- **`graph` / `minkowski`**: Wrappers for invoking our low-level C++ simplification procedures. Here you'll find interfaces for topological simplifications, geometric clustering, Minkowski-sum reductions, and more.
+- **`MapIndex`**: An advanced spatial querying interface wrapping CGAL spatial trees, enabling fast nearest-neighbor point-to-graph assignments (essential for crime mapping or event correlation on large networks).
+
+### `acj.data` (Data Binding & IO)
+- **`SimplificationResult`**: The critical struct generated and bound directly from pybind11. It holds the new `GraphData` topology alongside `.node_lineage` and `.edge_lineage` dictionaries linking new entities back to their original IDs.
+- **`GraphData`**: Internal lightweight wrapper handling node/edge validations before passing arrays down to C++.
+
+### `acj.evaluation` (Research & Metrics Engine)
+- **`BaseEvaluator` / `ACJTopologicalEvaluator`**: Automates the simplification lifecycle. These evaluators accept a raw `UrbanNetwork`, inject it into C++ for reduction, apply the semantic resolution layer, and systematically test the results against predefined metrics.
+- **`CompressionRatioMetric` / `SemanticSpeedDistortionMetric`**: Pluggable metrics allowing researchers to quantitatively evaluate exactly how much data is compressed and what percentage of the semantic truth (like speed distributions) is distorted during network abstraction.

acj-0.1.0/examples/example_acj.py

@@ -0,0 +1,108 @@
+"""
+Example usage of the ACJ library.
+
+This example demonstrates how to:
+1. Load graph data from pandas DataFrames
+2. Create a MapIndex for spatial queries
+3. Assign points to nearest graph endpoints (nodes)
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+import acj
+import pandas as pd
+import numpy as np
+
+
+def main():
+    print("=" * 70)
+    print("ACJ Library - Example Usage")
+    print("=" * 70)
+    print()
+    
+    # Step 1: Create sample graph data (simple street network)
+    print("[1/4] Creating sample graph data...")
+    print()
+    
+    nodes = pd.DataFrame({
+        'node_id': [0, 1, 2, 3, 4],
+        'x': [0.0, 100.0, 200.0, 300.0, 150.0],
+        'y': [0.0, 0.0, 100.0, 0.0, 100.0]
+    })
+    
+    segments = pd.DataFrame({
+        'segment_id': [0, 1, 2, 3],
+        'node_start': [0, 1, 2, 3],
+        'node_end': [1, 2, 4, 4],
+        'x1': [0.0, 100.0, 200.0, 300.0],
+        'y1': [0.0, 0.0, 100.0, 0.0],
+        'x2': [100.0, 200.0, 150.0, 150.0],
+        'y2': [0.0, 100.0, 100.0, 100.0]
+    })
+    
+    print(f"  Nodes: {len(nodes)}")
+    print(f"  Segments: {len(segments)}")
+    print()
+    
+    # Step 2: Load graph using ACJ
+    print("[2/4] Loading graph data...")
+    graph = acj.load_graph(nodes, segments)
+    print(f"  Graph loaded: {graph}")
+    print()
+    
+    # Step 3: Create MapIndex
+    print("[3/4] Building spatial index...")
+    map_index = acj.MapIndex(graph)
+    print(f"  MapIndex created: {map_index}")
+    print()
+    
+    # Step 4: Create sample points (e.g., crime locations)
+    print("[4/4] Assigning sample points to nearest nodes...")
+    print()
+    
+    points = pd.DataFrame({
+        'point_id': [0, 1, 2, 3, 4],
+        'x': [10.0, 105.0, 195.0, 290.0, 155.0],
+        'y': [5.0, 10.0, 95.0, 5.0, 90.0],
+        'crime_type': ['robbery', 'assault', 'theft', 'vandalism', 'burglary']
+    })
+    
+    print("Sample points to assign:")
+    print(points)
+    print()
+    
+    # Perform assignment
+    print("Performing endpoint assignment...")
+    assignments = map_index.assign_to_endpoints(points)
+    
+    print()
+    print("Assignment results:")
+    print(assignments[['point_id', 'crime_type', 'assigned_node_id', 'distance']])
+    print()
+    
+    # Summary statistics
+    print("=" * 70)
+    print("Summary Statistics")
+    print("=" * 70)
+    print(f"Total points assigned: {len(assignments)}")
+    print(f"Average distance: {assignments['distance'].mean():.2f} meters")
+    print(f"Max distance: {assignments['distance'].max():.2f} meters")
+    print(f"Min distance: {assignments['distance'].min():.2f} meters")
+    print()
+    
+    # Distribution by node
+    print("Points per node:")
+    node_counts = assignments['assigned_node_id'].value_counts().sort_index()
+    for node_id, count in node_counts.items():
+        print(f"  Node {node_id}: {count} points")
+    print()
+    
+    print("=" * 70)
+    print("Example completed successfully!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()