109 lines
3.8 KiB
Markdown
109 lines
3.8 KiB
Markdown
# Visualizador Instanciados
|
||
|
||
This repo is a Docker Compose stack for visualizing large RDF/OWL graphs stored in **AnzoGraph**. It includes:
|
||
|
||
- A **Go backend** that queries AnzoGraph via SPARQL and serves a cached graph snapshot + selection queries.
|
||
- A **React/Vite frontend** that renders nodes/edges with WebGL2 and supports “selection query” + “graph query” modes.
|
||
- A **Python one-shot service** to combine `owl:imports` into a single Turtle file.
|
||
- An **AnzoGraph** container (SPARQL endpoint).
|
||
|
||
## Quick start (Docker Compose)
|
||
|
||
1) Put your TTL file(s) in `./data/` (this folder is volume-mounted into AnzoGraph as `/opt/shared-files`).
|
||
2) Optionally configure `.env` (see `.env.example`).
|
||
3) Start the stack:
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
Then open the frontend:
|
||
|
||
- `http://localhost:5173`
|
||
|
||
Stop everything:
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
## Services
|
||
|
||
Defined in `docker-compose.yml`:
|
||
|
||
- `anzograph` (image `cambridgesemantics/anzograph:latest`)
|
||
- Ports: `8080`, `8443`
|
||
- Shared files: `./data → /opt/shared-files`
|
||
- `backend` (`./backend_go`)
|
||
- Port: `8000` (API under `/api/*`)
|
||
- Talks to AnzoGraph at `SPARQL_HOST` / `SPARQL_ENDPOINT`
|
||
- `frontend` (`./frontend`)
|
||
- Port: `5173`
|
||
- Proxies `/api/*` to `VITE_BACKEND_URL`
|
||
- `owl_imports_combiner` (`./python_services/owl_imports_combiner`)
|
||
- One-shot: optionally produces a combined TTL by following `owl:imports`
|
||
|
||
Service READMEs:
|
||
|
||
- `backend_go/README.md`
|
||
- `frontend/README.md`
|
||
- `python_services/owl_imports_combiner/README.md`
|
||
- `anzograph/README.md`
|
||
|
||
## Repo layout
|
||
|
||
- `backend_go/` – Go API service (SPARQL → snapshot + selection queries)
|
||
- `frontend/` – React/Vite WebGL renderer
|
||
- `python_services/owl_imports_combiner/` – Python one-shot OWL imports combiner
|
||
- `data/` – local shared volume for TTL inputs/outputs (gitignored)
|
||
- `docker-compose.yml` – service wiring
|
||
- `flake.nix` – optional Nix dev shell
|
||
|
||
## Configuration
|
||
|
||
This repo expects a local `.env` file (not committed). Start from `.env.example`.
|
||
|
||
Common knobs:
|
||
|
||
- Backend snapshot size: `DEFAULT_NODE_LIMIT`, `DEFAULT_EDGE_LIMIT`, `MAX_NODE_LIMIT`, `MAX_EDGE_LIMIT`
|
||
- SPARQL connectivity: `SPARQL_HOST` or `SPARQL_ENDPOINT`, plus `SPARQL_USER` / `SPARQL_PASS`
|
||
- Load data on backend startup: `SPARQL_LOAD_ON_START=true` with `SPARQL_DATA_FILE=file:///opt/shared-files/<file>.ttl`
|
||
- Frontend → backend proxy: `VITE_BACKEND_URL`
|
||
|
||
## API (backend)
|
||
|
||
Base URL: `http://localhost:8000`
|
||
|
||
- `GET /api/health` – liveness
|
||
- `GET /api/stats` – snapshot stats (uses default limits)
|
||
- `GET /api/graph` – graph snapshot
|
||
- Query params: `node_limit`, `edge_limit`, `graph_query_id`
|
||
- `GET /api/graph_queries` – available graph snapshot modes (`graph_query_id` values)
|
||
- `GET /api/selection_queries` – available selection-highlight modes (`query_id` values)
|
||
- `POST /api/selection_query` – run a selection query for highlighted neighbors
|
||
- Body: `{"query_id":"neighbors","selected_ids":[...],"node_limit":...,"edge_limit":...,"graph_query_id":"default"}`
|
||
- `POST /api/sparql` – raw SPARQL passthrough (debug/advanced)
|
||
- `POST /api/neighbors` – legacy alias (same behavior as `query_id="neighbors"`)
|
||
|
||
## Frontend UI
|
||
|
||
- Mouse:
|
||
- Drag: pan
|
||
- Scroll: zoom
|
||
- Click: select nodes
|
||
- **Top-right buttons:** “selection query” mode (how neighbors/highlights are computed for the current selection)
|
||
- **Bottom-right buttons:** “graph query” mode (which SPARQL edge set is used to build the graph snapshot; switching reloads the graph)
|
||
|
||
## Notes on performance/limits
|
||
|
||
- The backend caches snapshots in memory; tune `DEFAULT_*_LIMIT` if memory is too high.
|
||
- The frontend renders a sampled subset when zoomed out, and only draws edges when fewer than ~20k nodes are visible.
|
||
|
||
## Nix dev shell (optional)
|
||
|
||
If you use Nix, `flake.nix` provides a minimal `devShell`:
|
||
|
||
```bash
|
||
nix develop
|
||
```
|