Function navtk::utils::open_data_file

Function Documentation

std::shared_ptr<std::ifstream> navtk::utils::open_data_file(ErrorMode error_mode, const std::string &label, const std::string &basename, std::ios_base::openmode mode = std::ios_base::in)

Search well-known locations for a data file and open it if possible.

This function will check for an environment variable named like "NAVTK_" + label + "_PATH", with an upper-cased, identifier-safe version of the label parameter. In other words, if label is "elevation map", the environment variable will be NAVTK_ELEVATION_MAP_PATH. If this variable is set, it will be used as the only possible location of the file (causing an error message if the file is not readable). Otherwise, the following locations will be searched in order, looking for a file with the given basename:

  • The value of NAVTK_DATA_DIR, if set.

  • On debug builds, the subprojects/navtk-data subfolder of the clone that was passed to meson

  • A navtk subfolder of your user data folder:

    • On Linux, this defaults to ~/.local/share/, but can be overridden by $XDG_DATA_HOME

    • On Mac, this is ~/Library/Application Support/

    • On Windows, it’s the location pointed to by your %APPDATA% environment variable.

  • A navtk subfolder of your system data folder(s):

    • On Linux, /usr/local/share and /usr/share (or colon-separated $XDG_DATA_DIRS)

    • On Windows, %PROGRAMDATA%

  • The -Ddatadir= subfolder of the -Dprefix= passed to meson. Defaults to $prefix/share

  • The current working directory

Parameters

  • error_mode – Whether to throw an exception, emit a log, or silently return nullptr when the file could not be found. This is an optional parameter, which defaults to the current global error mode.

  • label – A human-readable description of the desired file. This will be incorporated in the generated error message in the context cannot open {} file. It will also be used to generate the file-specific environment variable.

  • basename – The expected name of the file to check for in each search path.

  • mode – C++: Mode used to open the file, defaulting to std::ios_base::in. Python: A string file mode that will be passed into io.open(...), defaulting to "r"

Returns

C++: an ifstream open to the data file if found, otherwise nullptr. Python: An open Python file object (from io.open(...)) if found, otherwise None.