User guide

The 3DOnt Explorer, online

Everything you need to use the online demo: what each project shows, how to segment, plot, query and inspect a 3DGraph, and where the demo stops.

Getting started

Open the Explorer in a recent desktop browser (Chrome, Edge, Firefox, Safari). The first project loads by itself; the selector at the top switches project. A project weighs 20–50 MB and loads in a few seconds on a normal connection; after that, everything happens in your browser: the RDF graph of the objects, the queries, the segmentations.

Tutorial (10 minutes)

1. Open YTU3D. In the Explorer choose YTU3D — Urban campus. The Project tab tells you what this graph is good for. The cloud opens coloured by the Dynamic Semantic Segmentation at full detail: windows, pipelines, facades, roofs, cars, trees.
2. Climb the mereology. Go to Explore and drag Mereological level to the right. Windows, ventilations and pipelines disappear into facades and roofs; at the end, whole buildings. Nothing was recomputed: each point already knew all the objects it constitutes.
3. Climb the taxonomy. Bring Mr back to the left and move Taxonomical level: Car and Van become Four-Wheeled Vehicle, then Vehicle, then Movable Object. The two sliders are the two axes of S(M_r, T_r).
4. Ask a structural question. Open Query, pick the example Windows of buildings taller than 20 m and press Run query. The answer lights up in red; the table lists the windows; “Query actually run” shows what was executed on the object graph.
5. Inspect. Click a point on a window. The Inspect tab shows its coordinates and the chain of objects it constitutes, from the window to the building, each with its class path. Click an object of the chain to see all its properties and highlight its points; click a linked object to move to it.
6. Switch to Ferrara. Choose Ferrara. In the Project tab click The material of every point, then Points made of materials that are practically impermeable: the permeability is a property of the material (expert knowledge in the T-box), and reaches the points through Is_a_point_made_of.
7. Look at a rule. Click Heating propension index. The hint under the property explains the rule that produced it: low heat capacity of the material and a dark colour make a point heat up more.
8. Switch to the Temple of Neptune. Move Mr one step at a time: abacus and echinus become the capital, capital and shaft the column, columns, floor and entablature the temple. Then run Columns whose shaft is lower than 7 m.
9. Write your own query. Edit any example: change a class (base:Tree, base:Capital), a property, a threshold. The cheat-sheet lists the names. Ctrl/⌘ + Enter runs the query.

Which project for what

Coming later: the Casa degli Epigrammi Greci in Pompeii (inference to the best explanation) and a synthetic forest stand (forestry extension, what-if scenarios).

The interface

• Project — the card of the project: summary, what it is good for, “what this project can show” (one click sets up each demonstration), what it is not for, source.
• Explore — how the cloud is coloured, point size, and how many points are drawn.
• Query — natural-language box, suggested questions, SPARQL editor with tested examples, results.
• Inspect — what you clicked: point, chain of objects, properties.
• On the view: legend (bottom left), status (bottom right: points, objects, triples loaded, time), view buttons (top right).

Explore: colourings

Points drawn lowers the number of points rendered. Points are stored in random order, so 30% of the points is a uniform 30% sample: use it on slow devices. Queries and segmentations always work on all points.

Dynamic Semantic Segmentation S(M_r, T_r)

In a 3DGraph a point Constitutes every object it belongs to, and every object is typed with its class and all the ancestors of its class. A segmentation is therefore a choice of two resolutions:

• M_r — mereological level. Leftmost: every point is classified by the finest object it constitutes. Each step to the right moves one level up the part–whole tree; rightmost: whole objects. Levels are counted from the whole downwards, so that all the objects shown at one level sit at the same depth of their own tree (on the temple: columns, floor and entablature together; then shafts and capitals; then abacus and echinus). Objects that have no parts stay as they are at every level.
• T_r — taxonomical level. Leftmost: the most specific class. Each step to the right moves one level up the class hierarchy, down to the children of Macro_Entity (Object, Topological_Area …).

The legend lists the classes visible at the current levels, with the number of points of each.

Plotting properties

• Point properties (Verticality, Day_Temperature, Heating_Propension_Index …) are drawn directly.
• Object properties (Z_Length, Surface_Value, Max_Z …) belong to objects: each point takes the value of the object that constitutes it at the chosen object level (the same M_r logic). Height of windows or height of buildings: move the slider.
• Properties of linked nodes (Specific_Heat_Capacity, Permeability_To_Water of the material) reach the points through the link: this is expert knowledge applied to the cloud.

Grey means “no value”.

Natural-language questions (NL-2-SPARQL)

Write the question in English and press Translate & run. The question is first parsed by a language model that runs in your browser; the parse goes to the NL-2-SPARQL service, which maps it on the ontology of the project and returns a SPARQL query; the query appears in the SPARQL box and runs in your browser. The words of your question that were mapped on the ontology are shown above the result, so you can see how the question was understood.

Choosing the model

The menu above the question box (tab Query) offers two sizes of the same parser, fine-tuned on the NL-2-SPARQL dataset:

• Small — 2 billion parameters, about 1.1 GB to download: the fastest, for laptops with integrated graphics;
• Medium — 4 billion parameters, about 2.3 GB (the default);

The model is downloaded the first time you press Translate & run (the progress is shown next to the button) and is then kept in the browser cache: the following visits start in a few seconds. Your choice is remembered. The model needs WebGPU: recent Chrome or Edge on Windows, macOS and ChromeOS, Safari 26 or later; Firefox only on some systems. Without WebGPU, or if the GPU does not support 16-bit shaders, the box says so and the SPARQL editor keeps working. If Medium cannot start on your device (not enough GPU memory), the message suggests Small.

How NL-2-SPARQL works: a fine-tuned language model only parses the question (the words, their relations, operators, filters, what to return); the words are then mapped on the ontology vocabulary; a graph-exploration step finds how the mapped terms are connected in the ontology and writes the query. The model never sees the data.

How to write a question

• Use the words of the domain, close to the class and property names: buildings, windows, roofs, trees, columns, capitals, shafts, height, surface, material, temperature. The cheat-sheet lists them per project.
• Numbers without units of measure: “buildings with a height greater than 20”, not “taller than 20 metres”. The values in the graph have no unit attached, and a unit in the question is a word the parser tries to map.
• Avoid “only”: say the same thing explicitly. “Doors made of wood and of no other material”, not “doors made only of wood”.
• Write string values between double quotes: points made of “travertine”, elements with tag “tagged”. Without quotes the value may be taken for a class or a property.
• Name the relation instead of leaving it implicit: “windows that are part of a building” works better than “building windows” or “the building’s windows”. The same holds for counts: “buildings that contain more than 3 windows”.
• One request per question. If you need two results, or a result computed on another result, ask two questions.
• Conjunctions, disjunctions and negations of conditions work, also nested one or two levels: “columns that contain an echinus with a surface of 10 or a height of 12”, “benches with a seating capacity greater than 2 or placed under a tree”.
• Counts, sums and averages, also per group: “how many trees”, “the average height of the columns for each temple”.
• Properties of the same thing described through an intermediate node (for example an acquisition with its temperature and its tag): when you ask for two of its values, name that thing in the question. “The temperature and the tag of the acquisitions of the points…”, not “the temperature and the tag of the points…”.

What NL-2-SPARQL does not do (yet)

Each limit below is a structure that the parser or the query builder does not produce today. When you need one of them, write the query in the SPARQL editor: the examples of each project are a good starting point.

• No automatic second attempt. Every word is read once as a class, a property, a relation or a value. If a word is read wrongly, the query is wrong: the mapping line shows it, and rephrasing with the vocabulary names usually fixes it.
• No sub-queries, so not:
  • averages, sums or counts of relations (“the average number of windows per building”);
  • a condition on a relation combined with an average or sum of a value (“buildings whose windows have an average surface greater than 2”);
  • an aggregate of an aggregate (“the average, per temple, of the total height of the columns”);
  • averages, sums or counts inside a negation or inside an “or” between different conditions.
• No sums or averages over a family of properties: “the sum of the risk indices” is not computed over all the risk-index properties. Name each property.
• Limited arithmetic in conditions. An operation between two values works on simple conditions (“windows whose height times width is greater than 2”). Not supported: averages, sums or counts inside a composite condition, and maximum / minimum inside an expression (“points where the pH times the larger of solubility and porosity exceeds 3”).
• No “or” on a count: “buildings with 2 or 3 doors”. Ask with a range instead (“more than 1 and fewer than 4 doors”) or write two questions.
• No conditional expressions (“if … then …”).
• No distance or radius: “trees within ten metres of a bench” is not understood. More generally, spatial relations that are not properties of the graph (“near the church”, “north of”) are not understood: 3DOnt stores part–whole relations and dimensions, not arbitrary spatial relations.
• No questions about the ontology itself: classes, subclasses, types, labels (“which classes are parts of a temple?”). Use the class tree in the explorer or the SPARQL editor.
• One vocabulary per project: only the terms of the project’s ontology are mapped, not terms of other vocabularies.
• String values match exactly what is written between quotes: no “contains”, “starts with” or similarity.
• Some generated queries combine point values and object values in one filter, which the online engine does not run (see below): rephrase or edit the SPARQL.

SPARQL in the browser

The editor accepts SPARQL 1.1 SELECT / ASK queries. Prefixes base: (http://3DOntCore#), rdf:, rdfs:, owl:, xsd: are added if missing. FROM clauses are ignored (everything is in one graph).

The graph in your browser contains the ontology and the objects; the points are typed arrays. A query that talks about points is rewritten before it runs: point triples are removed, the rest runs on the graph, and the points are recovered from the links. You can see the rewritten query under every result.

Not supported online (they work in the desktop application): a FILTER mixing point values and object values (FILTER(?z > ?h) with ?z a point coordinate and ?h an object height); aggregates of point values grouped by objects; property paths through points; updates.

Inspecting points and objects

Click a point (without dragging). The Inspect tab shows the point (individual, coordinates, colour, point properties), the chain of objects it constitutes from the finest to the whole — each with its class path — and, on Ferrara, its material. Clicking an object shows all its properties and highlights its points; clicking a linked object (parts, wholes, materials) moves to it. Clicking an object name in a query result does the same.

Vocabulary cheat-sheet

Core (3DOntCore)

Classes by project

Limits of the online demo

• It is an explorer: the desktop functions that change the graph (import of rasters and sensors, manual annotation, geometry updates, rule execution, what-if simulation, IBE reasoning) are not online. Their results are: Ferrara's indices were produced by the rules of the desktop pipeline.
• The graphs were standardised to 3DOntCore for the demo (singular class names, common property names); details in the project repository (docs/STANDARDISATION.md).
• Large projects need memory: on phones, lower the number of points drawn.

Troubleshooting