Repository navigation
Typology Representative Building
How the Typology View (/typology/view) picks the building that best stands for a typology, and how the synthetic archetype is derived from it. Introduced in DiGi.GIS.WebAPI.UI f58fa43.
- Solve a typology for an area and select any node in the Typology tree: a leaf or a branch.
- In the right panel, press Find representative on the Representative card.
- The card shows:
- the representative's reference (click it to select the building in the list and on the map);
- Mean distance and 90th percentile, which say how typical the building is (see below);
- one row per definition level: the representative's value, then the node's median (numeric level) or most common value (categorical level);
- Archetype: the median floor area × median storeys of the node;
- 3D Viewer (the real building) and Synthetic archetype links.
- The map marks the representative with a dashed gold ring and pans to it if it is outside the view.
Selecting another node clears the card and the ring, and cancels a request still in flight.
The representative is the medoid of the node: the real building whose total distance to every other building of the node is the smallest. Unlike a mean, a medoid is always an existing building, and an outlier can never be chosen.
Buildings are compared only on the parameters selected in the Typology definition, one per level, read from building_data for the node's buildings.
A level with the unique-value rule is categorical. Only buildings carrying the node's most common value of every categorical level can be chosen. Ties go to the first value in ordinal order.
- Within a leaf, every categorical level is constant, so this step filters nothing.
- At a branch, it stops a building of a minority category from being chosen just because its numbers are central.
A level with a range rule is numeric. Each one is centred and scaled within the node:
z = (value − median) / scale
| Scale used | When |
|---|---|
| interquartile range (Q3 − Q1) | normally |
| median absolute deviation | when the IQR is 0 |
| max − min | when that is 0 too |
| level dropped | when there is no spread at all |
Scaling makes parameters in different units comparable: m² of floor area against a storey count. Dropping a constant level keeps a parameter the node itself pins, such as a narrow range, from diluting the others. The statistics are taken over all buildings of the node.
A building missing any of the remaining numeric values cannot be chosen. It still counts as a neighbour of the others, over the values it carries. If no eligible building is complete, any complete building is a candidate.
The distance between two buildings is the mean absolute difference of their z values over the parameters both carry. It is an L1 distance averaged per parameter, so one extreme parameter cannot dominate the way it would in a squared (Euclidean) distance.
The representative is the candidate with the smallest sum of distances to every building of the node.
- Ties go to the ordinal-first reference, so the result is deterministic.
-
Large nodes: with more than 2 000 candidates, only the 200 candidates nearest the median profile (
z= 0) are evaluated exactly. The medoid lies near the median profile, so the result stays the same; on a 2 500-building test it equalled the exact evaluation. The cost is bounded at 200 × the building count.
| Building | Floor area | Function |
z of floor area |
|---|---|---|---|
| A | 100.5 | house | −1.0 |
| B | 110.5 | house | −0.5 |
| C | 120.5 | shop | 0.0 |
| D | 130.5 | house | 0.5 |
| E | 900.5 | house | 39.0 |
The median is 120.5 and the IQR is 130.5 − 110.5 = 20.
- C is the numeric centre, but its function is not the most common one (house), so it is not a candidate.
- Of the houses, B and D both have a distance sum of 41.5, against 43 for A. B wins on the ordinal tie-break.
- E (the outlier) has a sum of 157 and is never chosen.
Both figures are in IQRs per parameter: 1.0 means "one interquartile range apart, on an average parameter".
| Figure | Meaning |
|---|---|
| Mean distance | the average distance from the representative to the node's other buildings |
| 90th percentile | 90 % of the node's buildings are at most this far from the representative |
Low values describe a tight, homogeneous node, where the representative stands for it well. High values, or a 90th percentile far above the mean, describe a loose or multimodal node: consider splitting it with another level or narrower ranges.
The card adds a note when:
- no numeric parameter varies within the node: every building is equally typical, and the first reference stands for it;
- sampling was used (more than 2 000 candidates).
The archetype is a hybrid. It keeps the representative's real footprint shape, scaled about its centroid to the node's median floor area, and takes the node's median storeys (rounded, at least 1).
- The footprint is scaled by
√(median floor area / footprint area). This keeps its proportions and any courtyard. - Phase, functions and reference are copied from the representative; the identifier is new.
- Floor area and storeys are the only parameters a footprint can carry. Every other selected parameter is reported as a median on the card, not built into the archetype.
- It is extruded at elevation 0, with no terrain or surroundings, and opened in the 3D viewer. Its title starts with "Synthetic archetype", so the viewer offers no building details for it.
The archetype is rebuilt on every request from the query string: nothing is stored.
| Case | Answer |
|---|---|
| Node above 50 000 buildings | HTTP 413: select a narrower typology |
| No definition or no buildings in the request | HTTP 400 |
| Definition rejected by the live column catalog | HTTP 400 with the reasons |
| No building complete enough to be chosen | HTTP 404 |
| Column catalog or building data unreachable | HTTP 503 |
| Route | Purpose |
|---|---|
POST /typology/representative |
Body { definition, buildings: [{ reference, id, countyId }] }. Reads building_data by reference, grouped by county part in batches of 10 000 (the upstream cap), and answers the representative and the archetype's size. |
GET /typology/representative/glb?id=&countyid=&floorarea=&storeys= |
The synthetic archetype as binary glTF. |
GET /typology/representative/view?id=&countyid=&floorarea=&storeys= |
The 3D viewer page for the archetype. |
| Piece | File |
|---|---|
| Selection |
Query/Representative.cs, Query/Quantile.cs
|
| View model | Create/TypologyRepresentativeViewModel.cs |
| Archetype | Create/Building2D.cs |
| Fetch | Query/BuildingDataTableByReferencesAsync.cs |
| Routes | Controllers/TypologyController.cs |
| UI |
wwwroot/js/typology-inspector.js, wwwroot/js/typology-map.js
|
| Facts |
DiGi.Test/DiGi.GIS.WebAPI.UI.xUnit/Facts/Query_Representative.cs, Create_Building2D_Representative.cs, Create_TypologyRepresentativeViewModel.cs
|