ttl3d

Turn any Turtle / RDF graph into a single self-contained HTML page with a 3D view (shaded spheres) and a 2D view (a flat canvas), permanent labels, predicate labels on the edges, a clickable legend, label search, and a detail card for every node. The page embeds all of its JavaScript, so it opens from a file, works offline, and never sends your data anywhere.

Try it in your browser: the Solar System demo, FOAF, SKOS, PROV-O and the Pizza ontology, each a page ttl3d generated.

Why

Ontology editors show class trees. SPARQL browsers show one neighbourhood at a time. Sometimes you want the whole graph on screen at once: to see which modules actually connect, which file asserted which edge, or which node everything hangs from. ttl3d was written for exactly that while building a multi-file ontology, then generalized to any RDF input.

Install

Python 3.10 or newer.

pip install ttl3d

For the development version, pip install git+https://github.com/soheilabadifard/TTL_to_3D, or clone the repository and run pip install -e .. The dependencies are rdflib, networkx, numpy and scipy, all available on conda-forge as well.

Quick start

ttl3d examples/solar-system.ttl examples/solar-system-missions.ttl -o solar.html

Open solar.html in any browser. Pass several files and they merge into one graph; the default colouring then shows which file declared each node and which file asserted each edge.

Without installing, run the module from a clone: python -m ttl3d ....

Options

Input formats are guessed from the extension (.ttl, .nt, .n3, .rdf, .owl, .jsonld, ...) through rdflib.

What becomes a node, what becomes a link

• A node is every IRI that is the subject of some triple or the object of a link, except IRIs of the RDF, RDFS, OWL and XSD vocabularies and ontology headers (owl:Ontology). Blank nodes are skipped.
• A link is an IRI-to-IRI triple whose predicate is a relation. rdf:type, owl:imports, owl:versionIRI, owl:priorVersion, rdfs:isDefinedBy, prov:wasDerivedFrom and dcterms:source describe the node instead and go to its card. Parallel edges collapse into one link listing every predicate.
• Label: rdfs:label, else skos:prefLabel, else the local name. Definition: skos:definition, else rdfs:comment, else dcterms:description. Every other literal lands in the card's property table.
• Each node remembers the file that first declares it; each link remembers the files asserting it. A file that only adds edges between other files' nodes still owns something visible.
• An edge asserted in both directions (:Luna :orbits :Earth and :Earth :hasMoon :Luna) is one link labelled orbits ⇄ hasMoon, without an arrowhead.
• Labels follow --lang: the requested language first, then untagged literals, then anything else; every other label value becomes a synonym on the card, and a rdfs:comment that loses to a skos:definition still appears in the property table.

In the page

• Legend rows filter inclusively: a selected group keeps its own nodes, their direct neighbours, and the endpoints of every edge it asserts.
• The 3D | 2D switch rebuilds the picture in the other view. Legend filters, the search text and the open card carry over, and in pinned mode each view has its own precomputed stress layout. A browser without WebGL opens in 2D and says so.
• Search dims everything whose label does not match.
• Click a node for its card: types, file, namespace, definition, synonyms, properties, incoming and outgoing relations (clickable), and sources.
• The label toggles rebuild the scene, so a big graph can start without sprites and switch them on later.
• "Free-float physics" releases pinned nodes into the live force layout and pins them back where they were.
• No fog: white fog made distant nodes vanish on zoom-out.
• Past twelve groups only the eleven largest keep a colour; the rest share one grey "other" row that filters them together.

Scale

The stress layout is quadratic in the number of nodes and label sprites are scene objects, so the automatic modes degrade instead of freezing:

The stress layout is computed twice, once per view, so a pinned page takes about twice the layout time of 0.1.0.

Force the behaviour you want with --layout and --labels.

Limitations

• Blank nodes are skipped, so OWL restrictions and RDF lists do not appear.
• No reasoning: only asserted triples are drawn.
• One page holds one graph; there is no incremental loading.
• The stress layout is quadratic: --layout stress on graphs far beyond 1000 nodes can take minutes, and the CLI says so on stderr.

Development

pip install -e .[test]
python -m pytest -q

The tests cover the loader, the node and link rules, the layout, the generated page, the vendored bundle's pins and licence notices, and the command line. The viewer's CSS and JavaScript live in ttl3d/viewer.css, ttl3d/viewer.js (shared by both views), ttl3d/viewer-3d.js and ttl3d/viewer-2d.js (one renderer per view) and are inlined into every page; when node is installed the suite syntax-checks the JavaScript. pip install -e .[browser] && playwright install chromium enables the headless browser tests that load the demo pages, switch views and assert zero console errors (TTL3D_BROWSER=firefox or webkit picks another engine). CI runs the suite on Linux, Windows and macOS, the browser tests on Chromium, Firefox and WebKit, and checks that the demo pages built on the three systems are identical apart from the pinned layout's last digits. The vendored JavaScript in ttl3d/vendor/ bundles 3d-force-graph, force-graph, three-spritetext and one shared three.js; VENDOR.md there has the rebuild recipe and LICENSES.md the upstream notices.

Citing

If ttl3d helped your work, cite it: CITATION.cff holds the reference and GitHub's "Cite this repository" button renders it as BibTeX or APA.

License

MIT. The vendored JavaScript is under permissive licences (MIT, ISC and others); ttl3d/vendor/LICENSES.md lists every bundled package with its licence and copyright line.