|
| HydrofabricVersion | detect_version (const std::set< std::string > &nexus_columns, const std::set< std::string > ÷s_columns={}) |
| | Identify which hydrofabric release a set of observed columns describes.
|
| |
| HydrofabricVersion | detect_version (const sqlite::database &nexus_db, const sqlite::database ÷s_db) |
| | Identify the release of a hydrofabric whose layers may live in two GeoPackages.
|
| |
| HydrofabricVersion | detect_version (const sqlite::database &db) |
| | Identify the release of a hydrofabric held entirely in one GeoPackage.
|
| |
| HydrofabricVersion | detect_hydrofabric (const sqlite::database &nexus_db, const sqlite::database ÷s_db) |
| | Test whether a GeoPackage is a hydrofabric, and identify it if so.
|
| |
| HydrofabricVersion | detect_hydrofabric (const sqlite::database &db) |
| | Test whether a single-file GeoPackage is a hydrofabric, and identify it if so.
|
| |
| std::string | get_layer_id_column (HydrofabricVersion version, const std::string &layer, const sqlite::database &db) |
| | Resolve the column name to use as the feature id when reading rows from a hydrofabric layer, centralizing the release/layer mapping so no caller needs to scatter version checks.
|
| |
| std::unordered_map< std::string, std::string > | build_divide_toid_lookup (HydrofabricVersion version, const std::string &layer, const sqlite::database &db) |
| | Precompute the divide_id -> flowpath_toid map used to synthesize "toid" on V4_0_BETA1 divides rows, which carry no native toid and instead reference their downstream nexus indirectly via flowpath_id -> flowpaths.flowpath_toid.
|
| |
| HydrofabricVersion | detect_hydrofabric (const std::string &catchment_path, const std::string &nexus_path) |
| | Identify the hydrofabric a pair of data paths names.
|
| |
| std::unique_ptr< HydrofabricReader > | make_hydrofabric_reader (const std::string &catchment_path, const std::string &nexus_path) |
| | Open a hydrofabric whose divides and nexuses may live in two files.
|
| |
| std::unique_ptr< HydrofabricReader > | make_hydrofabric_reader (const std::string &path) |
| | Open a hydrofabric held entirely in one file.
|
| |
| bool | is_v4 (const HydrofabricVersion version) |
| | Whether version belongs to the v4 family (either variant).
|
| |
| const char * | version_label (const HydrofabricVersion version) |
| | Human-readable label for version, as used in log output.
|
| |
|
| constexpr const char *const | DIVIDES_LAYER = "divides" |
| | GeoPackage hydrofabric layer (table) names, shared by the readers and the schema utilities.
|
| |
| constexpr const char *const | NEXUS_LAYER = "nexus" |
| |
| constexpr const char *const | FLOWPATHS_LAYER = "flowpaths" |
| |
| constexpr const char *const | ID_KEY = "id" |
| | Canonical feature property keys ngen consumes, which are also hydrofabric v2.2's own column names – the release the canonical vocabulary was taken from.
|
| |
| constexpr const char *const | TOID_KEY = "toid" |
| |
| constexpr const char *const | DIVIDE_ID_COLUMN = "divide_id" |
| | Version-specific column names, translated onto the canonical keys by the readers.
|
| |
| constexpr const char *const | NEXUS_ID_COLUMN = "nexus_id" |
| |
| constexpr const char *const | NEXUS_TOID_COLUMN = "nexus_toid" |
| |
| constexpr const char *const | FLOWPATH_ID_COLUMN = "flowpath_id" |
| |
| constexpr const char *const | FLOWPATH_TOID_COLUMN = "flowpath_toid" |
| |
The kinds of hydrofabric input the loader can identify and read.
Most of these name NOAA-OWP hydrofabric releases, told apart by what a nexus and a divide are called and by how a divide names its downstream nexus: v2.2 identifies nexus rows via id, while v4 renamed it to nexus_id (and toid to nexus_toid). The v4 family has two variants for how a divide reaches its downstream nexus: V4_0_BETA1 carries no flowpath_toid and synthesizes "toid" by joining divides to flowpaths on flowpath_id; V4_0 exposes flowpath_toid natively and never consults flowpaths. Use is_v4() for checks that apply to the whole family.
V1_GEOJSON is the odd one, and the "V1" in it is a designation of ours rather than a release the hydrofabric was ever published under: a GeoJSON hydrofabric carries no release marker to read, so there is nothing to identify beyond the format itself. It names the vocabulary ngen's GeoJSON path has always expected – id and toid as ordinary feature properties, needing no translation – which predates every numbered release the loader distinguishes.
UNRECOGNIZED is not a hydrofabric at all. It is the answer when the thing asked about turns out to be something else, such as a plain GeoPackage of arbitrary tables. It never names a hydrofabric whose release went unidentified: something that presents as a hydrofabric but matches no known release is rejected outright rather than carried as a value every caller downstream would have to remember to check.
| Enumerator |
|---|
| V1_GEOJSON | |
| V2_2 | |
| V4_0_BETA1 | |
| V4_0 | |
| UNRECOGNIZED | |
| std::unordered_map< std::string, std::string > ngen::hydrofabric::build_divide_toid_lookup |
( |
HydrofabricVersion | version, |
|
|
const std::string & | layer, |
|
|
const sqlite::database & | db ) |
Precompute the divide_id -> flowpath_toid map used to synthesize "toid" on V4_0_BETA1 divides rows, which carry no native toid and instead reference their downstream nexus indirectly via flowpath_id -> flowpaths.flowpath_toid.
Built once up front so the per-row loop can do a hashtable lookup instead of N queries.
Returns an empty map outside of (V4_0_BETA1, "divides") – V4_0 reads flowpath_toid directly and needs no synthesis – or when the GPKG has no flowpaths table (warns unless NGEN_QUIET). Rows with a NULL flowpath_toid are excluded from the join, so unlinked divides simply miss the lookup and leave "toid" unset.
- Parameters
-
| [in] | version | Identified hydrofabric release |
| [in] | layer | Layer name being read |
| [in] | db | Open GeoPackage database |
- Returns
- Map from divide_id to flowpath_toid; empty when synthesis is not applicable or not possible for this (version, layer)
References ngen::sqlite::database::contains(), DIVIDES_LAYER, FLOWPATHS_LAYER, ngen::sqlite::database::iterator::next(), ngen::sqlite::database::query(), V4_0_BETA1, and version_label().
Referenced by ngen::hydrofabric::V4_0Beta1GeoPackageHydrofabricReader::read_divides().
Test whether a GeoPackage is a hydrofabric, and identify it if so.
The nexus layer is what marks a GeoPackage as a hydrofabric. Absent, the file is something else entirely – a plain GeoPackage of arbitrary tables – and the result is UNRECOGNIZED; ngen::geopackage::GeoPackageReader still reads it perfectly well, it is simply not a hydrofabric. Present, the file is a hydrofabric and is identified, or else rejected: a nexus layer whose schema matches no known release is an error, not a release.
This differs from detect_version() only in what it does with a GeoPackage that is not a hydrofabric at all: detect_version() presumes it is one and throws, while this reports UNRECOGNIZED and leaves the judgment to the caller.
- Parameters
-
| [in] | nexus_db | Open database expected to hold the nexus layer |
| [in] | divides_db | Open database holding the divides layer; may be the same database |
- Returns
- HydrofabricVersion identified for the pair, or UNRECOGNIZED if
nexus_db has no nexus layer
- Exceptions
-
| std::runtime_error | if a nexus layer is present but matches no known release |
References ngen::sqlite::database::contains(), detect_version(), NEXUS_LAYER, and UNRECOGNIZED.
Referenced by detect_hydrofabric(), and ngen::hydrofabric::anonymous_namespace{HydrofabricReaderFactory.cpp}::identify().
| HydrofabricVersion ngen::hydrofabric::detect_hydrofabric |
( |
const std::string & | catchment_path, |
|
|
const std::string & | nexus_path ) |
Identify the hydrofabric a pair of data paths names.
Both paths must name the same format: a hydrofabric is one thing, and half of one in GeoJSON beside half in a GeoPackage is a mistake worth reporting rather than honoring.
Which format a file is in is read from the file itself, not from its name. A GeoPackage says so in its header; anything else is taken to be GeoJSON, which always yields V1_GEOJSON, since that format carries no release marker to read. A GeoPackage is opened further and its schema inspected, yielding the release it describes, or UNRECOGNIZED when it turns out not to be a hydrofabric at all.
- Parameters
-
| [in] | catchment_path | Path to the file holding the divides |
| [in] | nexus_path | Path to the file holding the nexuses; may be the same file |
- Returns
- HydrofabricVersion identified for the pair, or UNRECOGNIZED if the paths hold GeoPackages that are not a hydrofabric
- Exceptions
-
| std::runtime_error | if either file cannot be opened, if the two are in different formats, if a GeoPackage's schema matches no known release, or if they are GeoPackages and GeoPackage support was not built in |
References ngen::hydrofabric::anonymous_namespace{HydrofabricReaderFactory.cpp}::Identified::version.
Identify the release of a hydrofabric whose layers may live in two GeoPackages.
Each column list is read from the file that holds its layer. This matters for more than tidiness: v4.0 is only distinguishable from v4.0beta1 by divides.flowpath_toid, and an absent table reads as an empty column list, so identifying a split v4.0 hydrofabric against its nexus file alone would report V4_0_BETA1.
- Parameters
-
| [in] | nexus_db | Open database holding the nexus layer |
| [in] | divides_db | Open database holding the divides layer; may be the same database |
- Returns
- HydrofabricVersion identified for the pair
- Exceptions
-
| std::runtime_error | if the observed schema matches no known release |
References ngen::sqlite::database::columns(), detect_version(), DIVIDES_LAYER, and NEXUS_LAYER.
| HydrofabricVersion ngen::hydrofabric::detect_version |
( |
const std::set< std::string > & | nexus_columns, |
|
|
const std::set< std::string > & | divides_columns = {} ) |
Identify which hydrofabric release a set of observed columns describes.
nexus_id present means v4, id means v2.2; neither throws std::runtime_error listing the observed columns. For v4, divides is then checked for flowpath_toid to pick V4_0 vs. V4_0_BETA1.
- Parameters
-
| [in] | nexus_columns | Column names observed on the nexus table; empty is treated as "no
nexus table" and throws |
| [in] | divides_columns | Column names observed on the divides table; only consulted for v4 input, empty resolves to V4_0_BETA1 |
- Returns
- HydrofabricVersion identified from the column sets
- Exceptions
-
| std::runtime_error | if the column sets match no known release |
References FLOWPATH_TOID_COLUMN, ID_KEY, NEXUS_ID_COLUMN, V2_2, V4_0, and V4_0_BETA1.
Referenced by detect_hydrofabric(), detect_version(), and detect_version().
Resolve the column name to use as the feature id when reading rows from a hydrofabric layer, centralizing the release/layer mapping so no caller needs to scatter version checks.
- divides, v4: "divide_id".
- divides, v2.2: "divide_id" if present, else legacy "id" (warns unless NGEN_QUIET).
- nexus, v4: "nexus_id"; nexus, v2.2: "id".
- any other layer: "id".
- a layer absent from
db entirely: the sentinel "<unset>", which is deliberately not a legal column name – there is no id column to name, and a plausible-looking guess would only misdirect whoever reads it.
The resolved column is verified to exist in layer, so a schema surprise is reported here as the problem it is rather than as a confusing failure from the read that follows. An absent layer is not reported here, though: the subsequent read names the missing table with more context than a column check could.
- Parameters
-
| [in] | version | Hydrofabric release identified for this load |
| [in] | layer | Layer name being read (e.g., "divides", "nexus") |
| [in] | db | Open GeoPackage database holding layer |
- Returns
- Column name to use as the feature id
- Exceptions
-
| std::runtime_error | if layer exists but lacks the resolved column |
References ngen::sqlite::database::columns(), DIVIDE_ID_COLUMN, DIVIDES_LAYER, ID_KEY, is_v4(), NEXUS_ID_COLUMN, NEXUS_LAYER, V2_2, and version_label().
Referenced by ngen::hydrofabric::GeoPackageHydrofabricReader::read_divides(), and ngen::hydrofabric::GeoPackageHydrofabricReader::read_nexus().
| std::unique_ptr< HydrofabricReader > ngen::hydrofabric::make_hydrofabric_reader |
( |
const std::string & | catchment_path, |
|
|
const std::string & | nexus_path ) |
Open a hydrofabric whose divides and nexuses may live in two files.
The format is taken from the paths and the release, where the format has one, from the files themselves; the caller supplies paths and gets back something it can read both roles from.
- Parameters
-
| [in] | catchment_path | Path to the file holding the divides |
| [in] | nexus_path | Path to the file holding the nexuses; may be the same file, in which case it is opened once |
- Returns
- std::unique_ptr<HydrofabricReader> Reader for the hydrofabric
- Exceptions
-
| std::runtime_error | under the same conditions as detect_hydrofabric(), or if the paths name GeoPackages that are not a hydrofabric |
References UNRECOGNIZED, V1_GEOJSON, V2_2, V4_0, V4_0_BETA1, and version_label().
Referenced by make_hydrofabric_reader().