From 99dd1333d84ba35129ef4bee6294952b92a23e14 Mon Sep 17 00:00:00 2001 From: giswqs Date: Sun, 15 Nov 2026 11:38:56 -0500 Subject: [PATCH] docs: reconcile release quality notes with current behavior --- ROADMAP.md | 4 +- .../rustgis-python/python/rustgis/__init__.py | 6 ++- docs/user-guide/analysis.md | 16 ++++---- docs/user-guide/data-formats.md | 6 +-- docs/user-guide/data.md | 41 ++++++++++++------- docs/user-guide/editing.md | 2 +- docs/user-guide/index.md | 4 +- docs/user-guide/maps.md | 8 +++- docs/user-guide/sharing.md | 2 +- 9 files changed, 54 insertions(+), 35 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 5df0619a3f..17d68da6f2 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -285,9 +285,7 @@ attributes kept. - A scene with a free camera and each layer's elevation mode (on the ground, relative, absolute), Phase 2 of [#726](https://github.com/opengeos/RustGIS/issues/726), after the Z design above. - LiDAR point layers (LAS/LAZ/COPC, read today as points) drawn at their heights in the scene. -- Terrain from several layers ([#1310](https://github.com/opengeos/RustGIS/issues/1310)), and - finer terrain once a tilted view settles - ([#1523](https://github.com/opengeos/RustGIS/issues/1523)). +- Terrain from several layers ([#1310](https://github.com/opengeos/RustGIS/issues/1310)). - 3D objects and 3D Tiles follow. ## Exploratory diff --git a/apps/rustgis-python/python/rustgis/__init__.py b/apps/rustgis-python/python/rustgis/__init__.py index ecf98724a0..913820aa87 100644 --- a/apps/rustgis-python/python/rustgis/__init__.py +++ b/apps/rustgis-python/python/rustgis/__init__.py @@ -369,7 +369,8 @@ def _outputs(self, result: Any) -> Any: A file of several layers (the tables of a GeoPackage, a GDAL file split by geometry type) reports the first as ``"layer"`` and every one as ``"layers"``, so ``"layers"`` - decides. Standalone tables added with the layers are in :meth:`info`, not returned. + decides. Any standalone tables that were actually added are in :meth:`info`, not + returned. GeoPackage attribute-only tables are not imported when adding a whole file. Args: result: The command's result. @@ -561,7 +562,8 @@ def add_data(self, path: PathLike, name: Optional[str] = None, **params: Any) -> path: The file: GeoJSON, CSV, Shapefile (or a zip of them), GeoPackage, GeoParquet, FlatGeobuf, KML/KMZ, GPX, GeoTIFF, ASCII grid, and the formats GDAL or DuckDB read when they are installed. - name: The layer's name (the file's name when left out). + name: The layer's name (the file's name when left out). For a file adding several + layers, this names only the first layer added. **params: More ``layer.addData`` parameters, e.g. ``layer=`` for one table of a GeoPackage, ``x=`` and ``y=`` for a CSV's coordinate columns. diff --git a/docs/user-guide/analysis.md b/docs/user-guide/analysis.md index 1db2b4b912..8441b969ca 100644 --- a/docs/user-guide/analysis.md +++ b/docs/user-guide/analysis.md @@ -686,8 +686,9 @@ layers**: the prediction, named by `output`, and `_variance`. the count of output polygon features whose total area is less than one millionth (`1e-6`) of their input feature's area, measured in the overlay plane. These may be slivers along the clip boundary; they are kept unchanged. Check these features before using the result as a map series -index, where a tiny sliver can make an apparently empty page. Ordinary clipped pieces give no -sliver notice, and empty intersections are still left out. +index, where a tiny sliver can make an apparently empty page. A genuine small piece of a very +large input can also trigger this notice. Pieces at or above the ratio give no sliver notice, +and empty intersections are still left out. **Erase** (`erase`) removes from `input` features (points, lines or polygons) their parts inside the `erase` polygons. An erase polygon's edge counts as inside it, as for Clip, so a point on the @@ -948,9 +949,9 @@ digits, so `06/23/2021` converts but `6/23/2021` doesn't). A date such as `2026-03-05` becomes `2026-03`, keeping different years separate. 2. Run **Summary Statistics** on the permits, with **Case Fields** = `issue_month` and a **COUNT** statistic on `issue_date` (use **Add statistic**). -3. Read `FREQUENCY` as the number of permits per month. Records without a date form a separate - group with an empty key. The output - contains months present in the data; it does not fill in missing months with zero. +3. Read `FREQUENCY` as the number of permits per month. A null date and an empty-text date form + separate groups with null and empty-text keys; if both forms occur, there are two groups. The + output contains months present in the data; it does not fill in missing months with zero. **Minimum Bounding Geometry** (`convexHull`) encloses each feature in its convex hull (Group Option `None`), or all of them in one (`All`, with `count`, the features it enclosed). It passes @@ -1742,8 +1743,9 @@ The Imagery tab's groups open their tools in the Workflows pane. The tab belongs `nearest` and `mode`; other methods remove them with a notice naming the affected bands. Palette images use `nearest` for sampling and `mode` for aggregation, keeping their classes. - Cells off the raster are its no-data value. A raster without one keeps its bands as they are, - with NaN there in a floating-point type and 0 in a whole-number one, as GDAL leaves them; a - colour image gains an alpha band instead, so they are see-through. + with NaN there in a floating-point type and 0 in an unlabelled whole-number one. If any band + has class names, every band uses NaN outside, keeping class zero distinct from missing + coverage. A colour image gains an alpha band instead, so outside cells are see-through. - Datums are shifted as everywhere in RustGIS, through each system's transformation to WGS 84 (a Helmert step for SAD69 or Córrego Alegre, a few metres from the IBGE's grid shifts). - The result has to fit in memory (120 million values, cells times bands, or more on a computer diff --git a/docs/user-guide/data-formats.md b/docs/user-guide/data-formats.md index 016008ae9f..b63372dc0b 100644 --- a/docs/user-guide/data-formats.md +++ b/docs/user-guide/data-formats.md @@ -20,7 +20,7 @@ export names its feature. | --- | --- | --- | --- | | GeoJSON | `.geojson`, `.json` | Home › Add › Add Data, or drop the file | Features with typed attributes; a single-member `GeometryCollection` is unwrapped (including nested single-member collections). Empty or multi-member collections are unsupported: the whole feature, including its attributes, is skipped and counted in an unreadable-geometry notice. A FeatureCollection's legacy `crs` member (`{"type": "name", "properties": {"name": "urn:ogc:def:crs:EPSG::28992"}}`) is honoured for EPSG codes (`EPSG:28992`, `urn:ogc:def:crs:EPSG::28992`, `urn:ogc:def:crs:EPSG:6.6:28992`) and for `CRS84`: a projected or other non-WGS 84 system converts the coordinates to longitude/latitude and the layer keeps it as its coordinate system (Layer properties, export in it, Define Projection); `CRS84` and `EPSG:4326` are longitude/latitude already, so the coordinates stay as they are and the layer has no other coordinate system. Coordinates are x/y (easting/northing, or longitude/latitude) whatever the EPSG axis order. A `crs` that isn't understood (a `link`, WKT or PROJ text, any other name, an unknown code) is named in a notice and the coordinates are read as longitude/latitude. A feature whose coordinates can't be converted, or convert to beyond ±180.5° longitude or ±90.5° latitude (the declared system doesn't fit the numbers), is left out and counted in a notice, and Define Projection then asks for the file to be added again. A feature read as longitude/latitude (no `crs`, `CRS84` or `EPSG:4326`, or a `crs` that isn't understood) with a position whose longitude is within ±180.5° but whose latitude is past ±90.5° is kept, and one notice counts them: longitude and latitude may be swapped. A `crs` on a feature, a geometry or a lone Feature is ignored. GeoJSON is always written in WGS 84 without a `crs`. Desktop FeatureCollections larger than 32 MiB use an in-place reader (which honours `crs` too, reading the file once more to check the features convert); layers with more than 100,000 features stream a view at a time. Other GeoJSON files load whole, up to 256 MiB. | | Delimited text | `.csv`, `.tsv`, `.txt`, recognised `.dat`; UTF-8 `.csv.gz`, `.tsv.gz`, `.txt.gz`, `.dat.gz` | Add Data, or Home › Add › Add Data › Delimited Text… to choose the columns from the file's header | Comma, semicolon, tab or pipe separated (found from the header, or `"delimiter"`); `info.fileColumns` lists the columns and the ones found. Points from x/y columns (named like longitude/latitude, GTFS `stop_lon`/`stop_lat` or easting/northing, or chosen with `"x"` and `"y"`), or any geometry from a WKT/EWKT column (named like `wkt` or `geometry`, or `"wkt"`). When an inferred pair exceeds degree ranges, a recognised longitude/latitude pair is preferred only if its in-range, non-0,0 points cover at least as many rows as the first pair can place, unless a projected `"crs"` is given (see [Delimited Text](data.md) for aliases and sampling). Coordinates in another system are converted from `"crs"` (`EPSG:2263`, or WKT) or an EWKT `SRID=`; rows still read outside longitude/latitude are counted in a notice. Points placed at exactly 0,0 are kept and counted in a notice, as they may represent missing coordinates. Uncompressed text is UTF-8, or UTF-16 with its byte-order mark; other uncompressed files are read as Windows-1252 (Latin-1, as many public sources still publish CSV), with a notice saying so. Gzip input is UTF-8 only, streamed within 256 MiB of expanded text; decompress other encodings and add as `.txt`. Retained CSV rows and cells have a separate estimated memory budget (256 MiB in the browser; a quarter of physical memory between 256 MiB and 4 GiB on desktop). A file without coordinates opens as a standalone table. | -| Shapefile | `.shp` with `.dbf` (and `.shx`), or zipped (`.zip`) | Add Data or drop the file; in the web app, pick or drop the `.shp` and `.dbf` together, with the `.shx` and `.prj` if there are (they open as one layer), or the zip | A zip may hold several Shapefiles, in folders, and other vector files (GeoJSON, CSV, GeoParquet, FlatGeobuf); each becomes a layer, at most 32 for the whole archive (Shapefiles first, so other files are left out when Shapefiles fill it). A `.dbf` table without a `.shp` of the same name in its folder (such as a flood map's `L_` tables) isn't read, and a notice names it. Delimited `.txt` members (including GTFS tables) are read; unrecognised text members and single-column `README.txt` documentation are skipped with a notice and macOS `__MACOSX` entries are passed over, and a member that can't be read is skipped and named in a notice. Converted to longitude/latitude from the coordinate system in its `.prj` (EPSG, Esri or OGC WKT, or WKT2 as PROJ and QGIS write it; Web Mercator, UTM, State Plane and other common projections); without a `.prj` it must be in longitude/latitude. On the desktop, one with more than 100,000 shapes (counted from its `.shx`) is read in place, a view at a time. Numeric (`N`) and floating point (`F`) fields are read at full double precision. Date (`D`) fields are read as dates; a blank or zero date is empty, and one that isn't a date (`20260230`) is empty and counted in a notice. | +| Shapefile | `.shp` with `.dbf` (and `.shx`), or zipped (`.zip`) | Add Data or drop the file; in the web app, pick or drop the `.shp` and `.dbf` together, with the `.shx` and `.prj` if there are (they open as one layer), or the zip | A zip may hold several Shapefiles, in folders, and other vector files (GeoJSON, CSV, GeoParquet, FlatGeobuf); each becomes a layer, at most 32 for the whole archive (Shapefiles first, so other files are left out when Shapefiles fill it). A `.dbf` table without a `.shp` of the same name in its folder (such as a flood map's `L_` tables) isn't read, and a notice names it. Delimited `.txt` members (including GTFS tables) are read; unrecognised text members and single-column `README.txt` documentation are skipped with a notice and macOS `__MACOSX` entries are passed over, and a member that can't be read is skipped and named in a notice. Converted to longitude/latitude from the coordinate system in its `.prj` (EPSG, Esri or OGC WKT, or WKT2 as PROJ and QGIS write it; Web Mercator, UTM, State Plane and other common projections); without a `.prj` it must be in longitude/latitude. On the desktop, one with more than 100,000 shapes (counted from its `.shx`) is read in place, a view at a time. Numeric (`N`) and floating point (`F`) fields are read at full double precision; on whole-file reads, `nan` or `inf` becomes empty and is counted in a notice. Date (`D`) fields are read as dates; a blank or zero date is empty, and one that isn't a date (`20260230`) is empty and counted in a notice. | | KML / KMZ | `.kml`, `.kmz` | Add Data, drop the file, or upload it in the web app | A layer for each kind of geometry (points, lines, polygons), with each placemark's name, description, folder path and extended data (a key named like the `name`, `description`, `folder` or `style` column, ignoring case, gets a column of its own, such as `NAME_1`, unless it only repeats that column). Styles are kept: the layer is drawn by unique values of its `style` field, with each KML style's line and fill colours, widths and icon colours (up to 64 styles). Multi-geometries and `gx:Track`s are read. Ground overlays (pictures on a `LatLonBox`, turned by its `rotation`) are raster layers kept in the project: the picture inside a KMZ, or a file beside a KML (not a web address, nor outside its folder); a `gx:LatLonQuad` isn't drawn. | | GPX | `.gpx` | Add Data, drop the file, or upload it in the web app | Waypoints, routes, tracks (one line per track, its segments as parts) and track points (with elevation and time) as separate layers. | | Spreadsheets | `.xlsx`, `.xlsm`, `.xlsb`, `.xls`, `.ods` | Add Data (or Delimited Text… to choose the columns), drop the file, or upload it in the web app | One sheet at a time, read like delimited text: the first non-empty row names the columns, and x/y or WKT columns (found, or given with `"x"`, `"y"`, `"wkt"` and `"crs"`) make the geometry; a sheet without them is a table. The first sheet is added and the others named in a notice; `"layer"` picks one, and `info.fileLayers` lists them. Dates read as ISO 8601. | @@ -33,7 +33,7 @@ export names its feature. | ArcGIS feature-service answers (protocol buffer) | `.pbf` holding an answer to an ArcGIS query with `f=pbf`, or the query's address | Add Data, drop the file, upload, or From URL… with the query's address (`…/FeatureServer/0/query?…&f=pbf`) | One page of the layer: the fields and values the same query gives as GeoJSON, with the fields' aliases as their display names (dates as milliseconds since 1970, date-only and time values as text), points, lines or polygons converted to longitude/latitude from the answer's coordinate system. Z and M values, geometry, blob and raster fields are left out, with a notice. A page that stopped at the service's record limit keeps its features, with a notice that the rest aren't in it. A query the service refuses (an empty answer), a count, ids or an extent, curves, multipatches and envelopes give an error. Told from OpenStreetMap data by its content. | | TopoJSON | `.topojson`, or `.json` | Add Data, drop the file, or upload | Shared arcs (quantized or not) are rebuilt into geometries. A `.topojson` adds a layer per object, up to 64; a topology named `.json` adds its first object and names the others in a notice. Use `.topojson` to add them all. | | CityJSON | `.city.json`, or `.json` | Add Data, drop the file, upload, or From URL… | CityJSON 1.1 and 2.0, read in 2D: a layer per City Object type and geometry family (a name two layers would share, such as two long types cut to their first 64 characters, or two that differ only in ASCII case, gets ` (2)`, ` (3)`… on the later ones: the first number no other layer's name uses). Surfaces and solids become footprints (LoD 0, else the `GroundSurface` surfaces, else the union of the faces of the highest LoD, each tried when the one before gives no area, else the outline of the points; lines and points come from their highest level of detail that draws; a level passed over because its X or Y isn't a finite number, or is too large, is named in a notice; a geometry of more than 200,000 faces is the outline of its points (of its ground's, for a footprint from the ground), with a notice, unless its footprint is its ground and all of its ground faces are within the cap), with `z_min`, `z_max` and `height` fields, from every level of detail and the children's heights included, so Style › Extrusion stands them up, and `base_height`, how far an object's lowest point is above the lowest point of the topmost object it is part of (0 for a building; for a balcony part, its lowest point's height above the building's; a building's lowest point is its basement's when it has one, and a group's members aren't parts of the group). Also `id`, `type`, `parent`, `lod` and the object's attributes; one named as one of these fields, or as another attribute of its layer but for case, takes a number (`height_1`), the same in every row, and a notice lists them. A `.city.json`, or a model from an address, adds every layer, up to 64; a file named `.json` adds its first layer with something to draw and names the others in a notice. A file that names no coordinate system and isn't longitude/latitude is refused: for now the way to add it is the `"crs"` parameter of `layer.addData`, from the command line, Python or the AI Assistant. Geometry instances are their template placed by their matrix at their reference point, with its heights, and rings the matrix flattens are left out and said for each instance; one whose template is missing, can't be read or draws nothing, or whose matrix is missing or isn't 16 numbers ending in `0 0 0 1`, is drawn as a point at its reference point, with no height, as are those past what placing may cost (as many points, all instances together, as the file could write out), and a notice says how many. `TINRelief` objects aren't drawn; a notice says so, as it does for addresses. Appearance (materials and textures) isn't read, and a notice says how much is left out. Heights are kept in the file's unit: in a coordinate system that doesn't measure in metres, a notice says so, as Style › Extrusion reads metres. A compound URN (`urn:ogc:def:crs,crs:EPSG::25832,crs:EPSG::5783`) is read by its horizontal part, and its vertical part gives the heights' unit, said as in CityGML when it isn't a height in metres. In a zip, a `"crs"` applies only to a model that names no coordinate system RustGIS knows. In the browser a footprint that needs a union is the outline of the object's points; a notice says so. An extrusion raises each part when it is given a base, such as `base_height` as its base field, or a constant (see [Layer effects](cartography.md#layer-effects)); with no base, parts stand on the ground. | -| CityGML | `.gml`, or `.xml` | Add Data, drop the file, upload, or From URL… | CityGML 1.0, 2.0 and 3.0, read in 2D as CityJSON is (the same layers, fields, footprints, heights and notices). 3.0 is read by the names it keeps and by its own where they change (thematic surfaces in `boundary`, openings in `fillingSurface`, generic attributes named by `gen:name`, a group's member inside its `Role`), read only in 3.0's namespaces, so an extension of a 1.0 or 2.0 model that uses one of those names keeps its own meaning; its spaces (a `BuildingRoom`, a `Storey`) are objects like any other. The objects are the features of the model's members and those nested in them with a `gml:id` or a geometry (a `BuildingPart`, a `Room`), each with its parent's id in `parent`; thematic surfaces and their openings are their object's faces, and a `GroundSurface` its ground. A geometry's level of detail is the one its property names (`lod2Solid` is 2); one in another property (a group's) has none. Converted from the `srsName`, by its horizontal part for a compound system (the URN and URL forms of geographic systems are latitude first, CRS84 longitude first; heights are kept as they come, and a vertical part that isn't a height in metres, such as one in feet, a depth, or one RustGIS doesn't know, is said; when a vertical part is named, its unit is the heights', not the horizontal system's), or from the coordinate system given (`crs`), which takes the place of the one the file names; a file naming different systems (on its geometries or envelopes) is refused unless a system is given, which reads them all and says how many named another, and one system with its axes in different orders is refused either way. Picked by name (`layer`), a layer keeps the notices the file as a whole gives; zipped, a model keeps the system it names, and the one given applies only when it names none RustGIS knows. Generic attributes are typed by their element, `measuredHeight`, the storey counts, years and any property with a unit in metres are numbers (a measure in another unit than the metre is text with its unit), other simple properties are text (the code list a code names, `codeSpace`, a value's other attributes, such as its language, `xml:lang`, and a generic attribute set's members with no name and its own code list aren't kept, and notices say how many, generic attributes included), a property given twice is a list and a structured one its JSON. Each member of the model is parsed on its own, with the objects nested in it (each object of a `featureMembers` on its own), so no tree of the whole model is built; the file's text and the rows read stay in memory. On the desktop, Add Data reads a file added by its path in the background, with its progress counted a member at a time and Cancel (in a zip, from text, or listed, it is read as the command runs). A member nested too deep or too large to parse is left out whole, with a notice. A geometry given by a link (`xlink:href`) to one written in the file, in the same member or another, as a solid's faces are to its walls' and roof's polygons, is read where the link stands, once its object's own geometries are read, a ground surface's links first: one its object holds already at that level of detail isn't read again (a ground face stays its ground, and a face read as a wall that a ground surface links to is read as the ground too), through links each is read at most once per object and level, so links in a cycle end, and what a member's links read is bounded by the member's size, and what links copy and read from other members by four times the file's, past which the links left are said; a solid whose exterior is a link that is followed and reads something keeps its cavities; a link to a `gml:id` that several elements have reads the one in its member, else the first in the file, and a notice says how many geometries repeat one; a geometry whose coordinates can't be read is said once, whichever object or link reads it first. An implicit geometry is its prototype (`relativeGMLGeometry`, `relativeGeometry` in 3.0, written in place or given by a link, in its member or another) placed by its matrix at its reference point, in the file's axis order (latitude first where the system is), with its heights: the prototype is read once and placed for each instance, and rings its matrix flattens are left out and said for each instance; one whose prototype is in another file (`libraryObject`), can't be read or holds nothing to place, or whose matrix isn't 16 numbers ending in `0 0 0 1`, is drawn as a point at its reference point, with no height, as are those past what placing may cost (as many points, all instances together, as the file could write out), and a notice says how many. A part, a group's member or a group's parent given by a link (`consistsOfBuildingPart`, `buildingPart`, `bridgePart` and `tunnelPart` in 3.0, `groupMember`, a `CityObjectGroup`'s `parent`) makes the object it names a child of the other, as if written in it, so its heights go to it, wherever it is in the file (an object written in a group's `parent` is the group's parent too, not its child); the link stays an attribute too, a link naming no other object of the file is said, and a member's role in its group isn't kept, and is said. Not read, and said in a notice: geometries given by a link to another file, nothing or a member that can't be parsed, to what isn't a geometry, or to one where nothing is drawn (an appearance's, a terrain intersection's), a prototype's geometry linked from outside its implicit geometry, and links inside a prototype; thematic surfaces and openings given only by a link; rings given by one (a hole so given is left out, its face kept), lines and rings with a point or curve given by one, and an oriented curve whose base curve is, terrain intersection curves, appearances, addresses, and the properties of thematic surfaces and openings (a name, generic attributes: their faces are kept as their object's); arcs and splines are read as straight lines through their points (a curve given backwards, `orientation="-"`, in its direction, and one held in a ring counted like a standalone one); an arc given by its centre (`ArcByCenterPoint`, `CircleByCenterPoint`) isn't read as the curve's points, its centre is never a vertex, and an arc that is its curve's only segment leaves the geometry with nothing to read; a `gml:Point` written with more than one position keeps the first one, and is said; a solid with no exterior shell is left out, as is a solid whose exterior has nothing read (a link that isn't followed, an empty shell, or a shell whose surfaces are all links that lead nowhere), its cavities with it (read alone they would be drawn as a footprint), and one whose cavity can't be read is left out whole; a file cut short, even inside a tag, keeps the objects before the cut; `TINRelief` objects aren't drawn; 3.0's relations between objects (`CityObjectRelation`) and the model's versions (`versionMember`, `versionTransitionMember`) aren't read. | +| CityGML | `.gml`, or `.xml` | Add Data, drop the file, upload, or From URL… | CityGML 1.0, 2.0 and 3.0, read in 2D as CityJSON is (the same layers, fields, footprints, heights and notices). 3.0 is read by the names it keeps and by its own where they change (thematic surfaces in `boundary`, openings in `fillingSurface`, generic attributes named by `gen:name`, a group's member inside its `Role`), read only in 3.0's namespaces, so an extension of a 1.0 or 2.0 model that uses one of those names keeps its own meaning; its spaces (a `BuildingRoom`, a `Storey`) are objects like any other. The objects are the features of the model's members and those nested in them with a `gml:id` or a geometry (a `BuildingPart`, a `Room`), each with its parent's id in `parent`; thematic surfaces and their openings are their object's faces, and a `GroundSurface` its ground. A geometry's level of detail is the one its property names (`lod2Solid` is 2); one in another property (a group's) has none. Converted from the `srsName`, by its horizontal part for a compound system (the URN and URL forms of geographic systems are latitude first, CRS84 longitude first; heights are kept as they come, and a vertical part that isn't a height in metres, such as one in feet, a depth, or one RustGIS doesn't know, is said; when a vertical part is named, its unit is the heights', not the horizontal system's), or from the coordinate system given (`crs`), which takes the place of the one the file names; a file naming different systems (on its geometries or envelopes) is refused unless a system is given, which reads them all and says how many named another, and one system with its axes in different orders is refused either way. Picked by name (`layer`), a layer keeps the notices the file as a whole gives; zipped, a model keeps the system it names, and the one given applies only when it names none RustGIS knows. Generic attributes are typed by their element, `measuredHeight`, the storey counts, years and any property with a unit in metres are numbers (a measure in another unit than the metre is text with its unit), other simple properties are text (the code list a code names, `codeSpace`, a value's other attributes, such as its language, `xml:lang`, and a generic attribute set's members with no name and its own code list aren't kept, and notices say how many, generic attributes included), a property given twice is a list and a structured one its JSON. Each member of the model is parsed on its own, with the objects nested in it (each object of a `featureMembers` on its own), so no tree of the whole model is built; the file's text and the rows read stay in memory. On the desktop, Add Data reads a file added by its path in the background, with its progress counted a member at a time and Cancel (in a zip, from text, or listed, it is read as the command runs). A member nested too deep or too large to parse is left out whole, with a notice. A geometry given by a link (`xlink:href`) to one written in the file, in the same member or another, as a solid's faces are to its walls' and roof's polygons, is read where the link stands, once its object's own geometries are read, a ground surface's links first: one its object holds already at that level of detail isn't read again (a ground face stays its ground, and a face read as a wall that a ground surface links to is read as the ground too), through links each is read at most once per object and level, so links in a cycle end, and what a member's links read is bounded by the member's size, and what links copy and read from other members by four times the file's, past which the links left are said; a solid whose exterior is a link that is followed and reads something keeps its cavities; a link to a `gml:id` that several elements have reads the one in its member, else the first in the file, and a notice says how many geometries repeat one; a geometry whose coordinates can't be read is said once, whichever object or link reads it first. An implicit geometry is its prototype (`relativeGMLGeometry`, `relativeGeometry` in 3.0, written in place or given by a link, in its member or another) placed by its matrix at its reference point, in the file's axis order (latitude first where the system is), with its heights: the prototype is read once and placed for each instance, and rings its matrix flattens are left out and said for each instance; one whose prototype is in another file (`libraryObject`), can't be read or holds nothing to place, or whose matrix isn't 16 numbers ending in `0 0 0 1`, is drawn as a point at its reference point, with no height, as are those past what placing may cost (as many points, all instances together, as the file could write out), and a notice says how many. A part, a group's member or a group's parent given by a link (`consistsOfBuildingPart`, `buildingPart`, `bridgePart` and `tunnelPart` in 3.0, `groupMember`, a `CityObjectGroup`'s `parent`) makes the object it names a child of the other, as if written in it, so its heights go to it, wherever it is in the file (an object written in a group's `parent` is the group's parent too, not its child); the link stays an attribute too, a link naming no other object of the file is said, and a member's role in its group isn't kept, and is said. Not read, and said in a notice: geometries given by a link to another file, nothing or a member that can't be parsed, to what isn't a geometry, or to one where nothing is drawn (an appearance's, a terrain intersection's), a prototype's geometry linked from outside its implicit geometry, and links inside a prototype; thematic surfaces and openings given only by a link; rings given by one (a hole so given is left out, its face kept), lines and rings with a point or curve given by one, and an oriented curve whose base curve is, terrain intersection curves, appearances, addresses, and the properties of thematic surfaces and openings (a name, generic attributes: their faces are kept as their object's); arcs and splines are read as straight lines through their points (a curve given backwards, `orientation="-"`, in its direction, and one held in a ring counted like a standalone one); an arc given by its centre (`ArcByCenterPoint`, `CircleByCenterPoint`) isn't read as the curve's points, its centre is never a vertex, and an arc that is its curve's only segment leaves the geometry with nothing to read; a `gml:Point` written with more than one position keeps the first one, and is said; a solid with no exterior shell is left out, as is a solid whose exterior has nothing read (a link that isn't followed, an empty shell, or a shell whose surfaces are all links that lead nowhere), its cavities with it (read alone they would be drawn as a footprint), and one whose cavity can't be read is left out whole; a file cut short, even inside a tag, keeps completed members and completed direct children of the truncated member; a part nested inside an unfinished object is lost with that object; `TINRelief` objects aren't drawn; 3.0's relations between objects (`CityObjectRelation`) and the model's versions (`versionMember`, `versionTransitionMember`) aren't read. | | AutoCAD DXF | `.dxf` (ASCII) | Add Data › DXF…, drop the file, or upload | Points, lines and polygons layers from the drawing's entities: POINT, LINE, LWPOLYLINE and POLYLINE (bulges drawn as arcs; closed ones stay lines; polyface meshes become polygons), CIRCLE, ARC, ELLIPSE, SPLINE, HELIX, LEADER, MLINE (its centre line), TEXT, MTEXT, ATTRIB and constant ATTDEF (points with their text, at the alignment point of justified text), HATCH boundaries (holes found by nesting), SOLID, TRACE and 3DFACE (polygons). Blocks (named in any case) are drawn where INSERTs place them (scaled, rotated, in arrays, nested up to 8 deep), and so are DIMENSIONs' blocks (a linear dimension without one draws its lines and measured text); `"blocks": false` leaves them out, with a notice of how many. Entities in an object's own coordinate system are turned into the drawing's. Fields: `layer`, `entity`, `color` (ACI, BYLAYER and BYBLOCK resolved), `linetype`, `text`, `height`, `rotation`, `block`, `elevation` and `paperspace`. The drawing's layouts (paper space: title blocks, viewport frames) are left out, with a notice, unless `"paperSpace": true`. A drawing never says its coordinate system: give `"crs"` (such as `EPSG:2263`) — the import dialog offers the map's — or its coordinates are kept as they are, with a notice. `"layer"` picks one of the drawing's own layers, and `info.fileLayers` lists them. Text is read as UTF-8, and otherwise in the drawing's `$DWGCODEPAGE` (GBK, Big5, Shift_JIS, Windows-1252…), so Chinese layer names and labels come through; an unknown or missing code page is read as Latin-1, with a notice. Up to 2 million features (500,000 in the web app). Not read: binary DXF, MULTILEADER, WIPEOUT, IMAGE and ACIS solids (3DSOLID, REGION), named in a notice. | | Geotagged photos | `.jpg`, `.jpeg` | Add Data (several at once in the web app), drop them, upload, or `layer.addPhotos` with `"paths"` or a `"folder"` | JPEGs with a GPS position in their EXIF become points in the **Photos** layer (photos added one at a time join it): each with its `name`, `file`, `time` (when it was taken), `altitude`, `direction` (where the camera faced), `camera` and a `thumbnail` of at most 160 pixels, kept with the feature so the project needs no other file. Identify shows the thumbnail. Photos without a position are named in a notice and left out; a layer holds up to 2,000 photos. A JPEG is always read as a photo unless `layer.addData` or `layer.addDataBytes` is given `"as": "scan"` (a phone photo of a paper map, say: see [Scans with no coordinates](#rasters)). | | LiDAR point clouds | `.las`, `.laz` (COPC too) | Add Data, drop the file, upload, or From URL… | LAS 1.0–1.4 (point formats 0–10) and LAZ, on desktop and web: points with `z`, `intensity`, `classification`, `return` and colour (`red`, `green`, `blue`), coloured by ASPRS class or elevation. An evenly spread sample is read once, at most 2 million points (500,000 in the web app); views use that sample, not the COPC spatial index. LAZ decompression reads at most the first 400 million points (40 million on the web), with a notice when capped. Converted from the file's WKT or GeoTIFF-key record; without one, coordinates are kept with a notice. A local project keeps the path; uploads keep the file bytes. Remote files download whole. | @@ -90,7 +90,7 @@ place, is left out, and a notice names it. The parts are looked up beside the ad (S3's `X-Amz-*`) signs one file, so its Shapefile's parts can't be fetched with it: add that Shapefile zipped. Downloads are limited to 512 MiB on desktop and 256 MiB on the web; individual readers may have -lower limits (the whole-file vector readers use 256 MiB). In the web app the server must allow +lower limits (the whole-file vector readers, including CityGML, use 256 MiB). In the web app the server must allow requests from web pages (CORS). On the desktop, with [GDAL](https://gdal.org) installed, a JPEG 2000 file (`.jp2`, `.j2k`: Sentinel-2's imagery on S3) is downloaded too, converted to a GeoTIFF that the project keeps, and added. Desktop byte uploads diff --git a/docs/user-guide/data.md b/docs/user-guide/data.md index 6ccd8b95ca..c0000186e3 100644 --- a/docs/user-guide/data.md +++ b/docs/user-guide/data.md @@ -54,10 +54,17 @@ first and its points last, so its points are drawn on top, and a KML's ground ov them. A name given goes to the first map layer added, the bottom one (a standalone table only gets it when the file has no map layer). A GeoPackage adds its tables in name order, and a file read through GDAL keeps its layers in the file's order and orders only the types within each layer. -GeoPackage attribute-only tables are not supported. Adding a whole file reports their count in -one notice. Tile and other unsupported GeoPackage contents are also counted by type. The omission counts cover catalog entries without a registered geometry column; unknown content types are combined into one counted "other" group. Only contents registered in `gpkg_contents` are considered; arbitrary unregistered SQLite tables are ignored. Desktop uploads add their first feature table, with the existing note naming how many feature tables the file contains. Browser uploads with virtual generated `table_name` or `data_type` catalog columns cannot be evaluated and are refused with an explanation; materialize these columns or select a feature table explicitly. A file -containing only attribute tables is refused with the count. Selecting a -feature table explicitly adds only that table. +GeoPackage attribute-only tables are not supported. Adding a whole file reports their count in one +notice. Tile and other unsupported GeoPackage contents are also counted by type. The omission counts +cover catalog entries without a registered geometry column; unknown content types are combined into +one counted "other" group. Only contents registered in `gpkg_contents` are considered; arbitrary +unregistered SQLite tables are ignored. Desktop uploads add their first feature table, with the +existing note naming how many feature tables the file contains. Browser uploads with virtual +generated `table_name` or `data_type` catalog columns cannot be evaluated and are refused with an +explanation; materialize these columns or select a feature table explicitly. A file containing only +attribute or tile tables is refused with the count. Selecting a feature table explicitly adds only +that table. + On the desktop, **Home › Add › Add Data › Add Folder…** connects a folder to the Browser; the web app does not offer folder connections. On the desktop, a file Add Data reads whole (a GeoTIFF or another raster, one GDAL converts, a @@ -100,9 +107,10 @@ if the first pair contains coordinates outside ±180° longitude or ±90° latit specific longitude/latitude pair gives in-range, non-0,0 positions on at least as many rows as the first pair gives finite positions, that pair is used for the whole file. The published aliases `Longitude Decimal Degrees`/`Latitude Decimal Degrees` and -`Longitutde`/`Lattitude` are recognised too. The dialog checks its first 1,000 rows to pick -defaults, and recomputes unchanged defaults when you leave the coordinate-system box or press -Enter; columns you picked stay picked. A projected system keeps the columns found by name. +`Longitutde`/`Lattitude` are recognised too. The dialog checks the first 1,000 rows of delimited +text, or every row of a spreadsheet, to pick defaults. It recomputes unchanged defaults when you +leave the coordinate-system box or press Enter; columns you picked stay picked. With a projected system, defaults prefer X/Y or easting/northing +columns over longitude/latitude names when both exist; explicit column picks still take precedence. Add Data checks all rows. Coordinates still outside degree ranges are counted in a notice. Points placed at exactly 0,0 are also counted in a notice: these often mean missing coordinates, but the points are kept. A CSV without coordinate columns, or a layer without geometry, opens as a @@ -114,13 +122,15 @@ the table's name beside it (`input_name`). The **XY Table To Point** tool ([Geoprocessing](analysis.md), and a table's right-click menu) makes points of a table already in the project, from two fields of coordinates and their coordinate system. In a text field a single comma is the decimal separator (`1,234` is 1.234); thousands separators are not read. -Excel `.xls` records, formula operands and sheet bounds are checked before opening, including -sheets that were not selected. The workbook shares a memory budget across its sheets and retained -metadata. Value and formula grids are counted separately, with conservative estimates for -formula strings, defined names and sheet state. Formula-heavy workbooks can reach this budget -before their value-grid limit. A file with damaged records or excessive allocations is refused with the reason. Normal -cached formula values are read. A formula's direct cell reference to row 65,536 is currently -refused because the XLS reader cannot handle that reference safely. + +Excel `.xls` records, formula operands and sheet bounds are checked before opening, including sheets +that were not selected. The workbook shares a memory budget across its sheets and retained metadata. +Value and formula grids are counted separately, with allocation estimates for formula strings, +defined names and sheet state. Formula-heavy workbooks can reach this budget before their value-grid +limit. A file with damaged records or excessive allocations is refused with the reason. Normal +cached formula values are read. A formula's direct cell reference to row 65,536 is currently refused +because the XLS reader cannot handle that reference safely. + **Home › Add › Add Data › Graphics Layer** adds a layer for [drawn graphics](cartography.md#graphics), and **Data › Layer Templates** adds empty layers with ready-made schemas to draw into. @@ -656,7 +666,8 @@ plus `geocoded`, what the geocoder called the place, and a text field `match_sta Rows that weren't found stay in its table without a point, and a notice counts them; filter `match_status = 'unmatched'` to review them. A field of the same name in the input is kept, and -the new one gets an underscore appended (`match_status_`; filter that one then). `matched` means the geocoder returned a point, not that +the generated field gets underscores appended until its name is unique (`match_status_`, +`match_status__`, and so on); filter the generated field. `matched` means the geocoder returned a point, not that it is the exact address: it may be placed along the street or at a broader place. The geocoders don't give a match score, so there is none in the output. diff --git a/docs/user-guide/editing.md b/docs/user-guide/editing.md index 1f510b90ec..f60d05918c 100644 --- a/docs/user-guide/editing.md +++ b/docs/user-guide/editing.md @@ -370,7 +370,7 @@ opens. A picture from any other server isn't: the pop-up shows **Show Picture** name, and fetches nothing until you click it, because the request tells that server that someone opened the data (see [Privacy](../privacy.md)). A spinner shows while a picture is fetched. PNG, JPEG, WebP and GIF pictures of up to 4 MB and 2048 × 2048 pixels are shown (on every platform; any other -format, such as BMP or TIFF, is "not supported"); the last 16 addresses' pictures are kept for the +format, such as BMP or TIFF, shows "Picture unavailable: … pictures aren't supported"); the last 16 addresses' pictures are kept for the session, so opening the pop-up again shows the picture without asking again; they are forgotten with the web layers' cached tiles (signing out of ArcGIS, a login that ends, **Reload Web Layers**). When one can't be shown, the pop-up says why ("Picture unavailable: …": the server's answer, a network diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 6655be8ead..5e49eaa30c 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -118,7 +118,7 @@ end, by double-clicking a tab, or with ++ctrl+f1++ (++cmd+f1++ on macOS, where F key). Click a tab to peek at its commands while collapsed. When the window is narrower than the ribbon, arrows at its ends scroll it. -### Diagnostics +### Messages Open **View › Windows › Messages**, click the status-bar notice or **Messages** button, or search for **Messages** in Command Search (`ui.pane.diagnosticLog`). This troubleshooting @@ -273,7 +273,7 @@ in Command Search. Reload rereads the same local source, table or raster subdata adding other tables from its container. It retains the layer's name, identity, drawing order, group, visibility, opacity, styling, labels, filters and map camera. Local PMTiles and MBTiles tile archives have their own **Reload Data** on their Layers row; see -[Maps › Reloading a local tile archive](maps.md). +[Maps › Reloading a local tile archive](maps.md#reloading-a-local-tile-archive-desktop). Supported targets are linked vectors, rasters (including time-following Zarr variables), GDAL/DuckDB file-backed layers and editable local GeoPackage tables. GDAL-linked File diff --git a/docs/user-guide/maps.md b/docs/user-guide/maps.md index 28c2fdfe73..2584022586 100644 --- a/docs/user-guide/maps.md +++ b/docs/user-guide/maps.md @@ -446,7 +446,9 @@ selectable or editable; a tile not yet loaded may need another click once it arr **Reload** in the Basemap gallery (`map.reloadWebLayers`) clears cached tiles and styles and fetches them again. -**Reloading a local tile archive (desktop).** After changing a PMTiles or MBTiles file on disk, +### Reloading a local tile archive (desktop) + +After changing a PMTiles or MBTiles file on disk, right-click its row in Layers and choose **Reload Data** (**Reload Tile Archive** in Command Search). CLI, Python, MCP and the Assistant use `map.reloadTiles={"index":0}`; `"name"` or catalog `"id"` can select the archive instead. @@ -494,6 +496,10 @@ every tile payload. It allows at most **64 MiB stored and 64 MiB decoded index b index entries**, **4,096 unique directories** (including the root), and **four leaf levels**; each stored directory read is limited to **16 MiB**. An invalid index or an exceeded validation budget is an explicit error without eviction, even if an unusually large index is otherwise valid. +Validation also refuses a stored tile range over **16 MiB**, or one outside the header's declared +tile-data section (including a zero-length section with nonempty tile entries). Ordinary loading +can still draw other tiles from such an archive; reload and repair require the replacement's +entire index to pass these checks before changing the source or dropping cached data. Neither action is available for local archives in the web app, or for remote tile services. On Windows, an open MBTiles file may not be replaceable while RustGIS holds it open: reload diff --git a/docs/user-guide/sharing.md b/docs/user-guide/sharing.md index c17adcbf59..99fa4d5c45 100644 --- a/docs/user-guide/sharing.md +++ b/docs/user-guide/sharing.md @@ -52,7 +52,7 @@ vectors as a layout's PDF is (see Layouts), in the system viewer on desktop; **C Clipboard** copies a map image. **Export To 3D** writes a layer as a Wavefront OBJ or binary STL model with polygons extruded by a field (`share.export3d` writes STL when `path` ends in `.stl`). STL holds closed solids only: lines and zero-height features are left out, zero-area triangles are -skipped, and a cap that can't be triangulated is fanned over its outer ring, filling any holes; one +skipped, and a cap that can't be triangulated is fanned over its outer ring, filling any holes; a cap that the triangulator can only finish as a fan (a hole touching the outer ring along an edge, for example) is fanned over what is left of it. Either fan may spill outside the polygon; the notices say how many. OBJ