NGen
Loading...
Searching...
No Matches
ngen::hydrofabric Namespace Reference

Namespaces

namespace  anonymous_namespace{GeoPackageHydrofabricReader.cpp}
 
namespace  anonymous_namespace{GeoPackageHydrofabricSchema.cpp}
 
namespace  anonymous_namespace{HydrofabricReaderFactory.cpp}
 

Classes

class  AbstractV4GeoPackageHydrofabricReader
 Common behavior of the hydrofabric v4 readers. More...
 
class  GeoJSONHydrofabricReader
 Reads a hydrofabric stored as a pair of GeoJSON files. More...
 
class  GeoPackageHydrofabricReader
 Reads a hydrofabric stored as one or two GeoPackages. More...
 
class  HydrofabricReader
 Reads the catchment and nexus features of a hydrofabric, whatever format it is stored in. More...
 
class  V2_2GeoPackageHydrofabricReader
 Reads a hydrofabric v2.2 GeoPackage. More...
 
class  V4_0Beta1GeoPackageHydrofabricReader
 Reads a hydrofabric v4.0beta1 GeoPackage. More...
 
class  V4_0GeoPackageHydrofabricReader
 Reads a hydrofabric v4.0 GeoPackage. More...
 

Enumerations

enum class  HydrofabricVersion {
  V1_GEOJSON ,
  V2_2 ,
  V4_0_BETA1 ,
  V4_0 ,
  UNRECOGNIZED
}
 The kinds of hydrofabric input the loader can identify and read. More...
 

Functions

HydrofabricVersion 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.
 
HydrofabricVersion detect_version (const sqlite::database &nexus_db, const sqlite::database &divides_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 &divides_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.
 

Variables

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"
 

Enumeration Type Documentation

◆ HydrofabricVersion

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 

Function Documentation

◆ build_divide_toid_lookup()

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]versionIdentified hydrofabric release
[in]layerLayer name being read
[in]dbOpen 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().

◆ detect_hydrofabric() [1/3]

HydrofabricVersion ngen::hydrofabric::detect_hydrofabric ( const sqlite::database & db)

Test whether a single-file GeoPackage is a hydrofabric, and identify it if so.

Parameters
[in]dbOpen GeoPackage database holding both layers
Returns
HydrofabricVersion identified, or UNRECOGNIZED if db has no nexus layer
Exceptions
std::runtime_errorif a nexus layer is present but matches no known release

References detect_hydrofabric().

◆ detect_hydrofabric() [2/3]

HydrofabricVersion ngen::hydrofabric::detect_hydrofabric ( const sqlite::database & nexus_db,
const sqlite::database & divides_db )

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_dbOpen database expected to hold the nexus layer
[in]divides_dbOpen 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_errorif 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().

◆ detect_hydrofabric() [3/3]

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_pathPath to the file holding the divides
[in]nexus_pathPath 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_errorif 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.

◆ detect_version() [1/3]

HydrofabricVersion ngen::hydrofabric::detect_version ( const sqlite::database & db)

Identify the release of a hydrofabric held entirely in one GeoPackage.

Parameters
[in]dbOpen GeoPackage database holding both layers
Returns
HydrofabricVersion identified for the database
Exceptions
std::runtime_errorif the observed schema matches no known release

References detect_version().

◆ detect_version() [2/3]

HydrofabricVersion ngen::hydrofabric::detect_version ( const sqlite::database & nexus_db,
const sqlite::database & divides_db )

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_dbOpen database holding the nexus layer
[in]divides_dbOpen database holding the divides layer; may be the same database
Returns
HydrofabricVersion identified for the pair
Exceptions
std::runtime_errorif the observed schema matches no known release

References ngen::sqlite::database::columns(), detect_version(), DIVIDES_LAYER, and NEXUS_LAYER.

◆ detect_version() [3/3]

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_columnsColumn names observed on the nexus table; empty is treated as "no nexus table" and throws
[in]divides_columnsColumn 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_errorif 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().

◆ get_layer_id_column()

std::string ngen::hydrofabric::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.

  • 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]versionHydrofabric release identified for this load
[in]layerLayer name being read (e.g., "divides", "nexus")
[in]dbOpen GeoPackage database holding layer
Returns
Column name to use as the feature id
Exceptions
std::runtime_errorif 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().

◆ is_v4()

bool ngen::hydrofabric::is_v4 ( const HydrofabricVersion version)
inline

Whether version belongs to the v4 family (either variant).

Parameters
[in]versionIdentified hydrofabric version
Returns
true for V4_0_BETA1 and V4_0, false for anything else

References V4_0, and V4_0_BETA1.

Referenced by get_layer_id_column().

◆ make_hydrofabric_reader() [1/2]

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_pathPath to the file holding the divides
[in]nexus_pathPath 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_errorunder 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().

◆ make_hydrofabric_reader() [2/2]

std::unique_ptr< HydrofabricReader > ngen::hydrofabric::make_hydrofabric_reader ( const std::string & path)

Open a hydrofabric held entirely in one file.

Parameters
[in]pathPath to the file holding both the divides and the nexuses
Returns
std::unique_ptr<HydrofabricReader> Reader for the hydrofabric
Exceptions
std::runtime_errorunder the same conditions as the two-path form

References make_hydrofabric_reader().

◆ version_label()

Variable Documentation

◆ DIVIDE_ID_COLUMN

const char* const ngen::hydrofabric::DIVIDE_ID_COLUMN = "divide_id"
constexpr

Version-specific column names, translated onto the canonical keys by the readers.

Referenced by get_layer_id_column(), and ngen::hydrofabric::AbstractV4GeoPackageHydrofabricReader::normalize_divides().

◆ DIVIDES_LAYER

◆ FLOWPATH_ID_COLUMN

const char* const ngen::hydrofabric::FLOWPATH_ID_COLUMN = "flowpath_id"
constexpr

◆ FLOWPATH_TOID_COLUMN

◆ FLOWPATHS_LAYER

const char* const ngen::hydrofabric::FLOWPATHS_LAYER = "flowpaths"
constexpr

◆ ID_KEY

const char* const ngen::hydrofabric::ID_KEY = "id"
constexpr

Canonical feature property keys ngen consumes, which are also hydrofabric v2.2's own column names – the release the canonical vocabulary was taken from.

Referenced by detect_version(), get_layer_id_column(), and ngen::hydrofabric::AbstractV4GeoPackageHydrofabricReader::normalize_nexus().

◆ NEXUS_ID_COLUMN

◆ NEXUS_LAYER

◆ NEXUS_TOID_COLUMN

◆ TOID_KEY