buildingid-nrel 2.2.0

The API

• buildingid.code

  • Code

  • CodeArea

    • area() -> float

    • encode() -> Code

    • intersection(CodeArea) -> typing.Optional[typing.Tuple[float, float, float, float]]

    • jaccard(CodeArea) -> typing.Optional[float]

    • resize() -> CodeArea

  • decode(Code) -> CodeArea

  • encode(float, float, float, float, float, float, **kwargs) -> Code

  • isValid(Code) -> bool

Note: The Optional and Tuple type hints are provided by the typing module.

In the following example, a UBID code is decoded and then re-encoded:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import buildingid.code

if __name__ == '__main__':
  # Initialize UBID code.
  orig_code = '849VQJH6+95J-51-58-42-50'
  print(orig_code)

  # Decode UBID code.
  orig_code_area = buildingid.code.decode(orig_code)
  print(orig_code_area)

  # Resize resulting UBID code area.
  #
  # The effect of this operation is that the length and width of the UBID code
  # area are reduced by half an OLC code area.
  new_code_area = orig_code_area.resize()
  print(new_code_area)

  # Encode new UBID code area.
  new_code = new_code_area.encode()
  print(new_code)

  # Test that new UBID code and UBID code area match the originals.
  assert (orig_code == new_code)
  assert (orig_code_area == new_code_area)

The CLI

View the documentation for the buildingid command using the --help command-line option:

buildingid --help
#=> Usage: buildingid [OPTIONS] COMMAND [ARGS]...
#=> <<more lines of output>>

View the documentation for a sub-command of the buildingid command using the --help command-line option. For example, to view the documentation for the “append2csv” sub-command:

buildingid append2csv --help
#=> Usage: buildingid append2csv [OPTIONS] [latlng|wkb|wkt]
#=> <<more lines of output>>

Prerequisites

1. buildingid command is installed.

   • Verify installation:

     • buildingid --version

       • Expected output: “buildingid, version 2.0.0” (or higher version)

Step-by-step instructions

1. Locate input CSV file, e.g., path/to/in.csv.

2. Locate output CSV file (generated), e.g., path/to/out.csv.

3. Locate errors CSV file (generated), e.g., path/to/err.csv.

4. Identify number of digits in Open Location Code (OLC) part of UBID code string, e.g., 11.

5. Identify column of output CSV file that contains UBID code strings, e.g., “UBID”.

6. If input CSV file contains latitude and longitude coordinates for a centroid only:

   1. Identify columns of input CSV file that contain latitude and longitude coordinates, e.g., “Latitude” and “Longitude”.

   2. Assign UBIDs:

      • buildingid append2csv latlng --code-length=11 --fieldname-code="UBID" --fieldname-center-latitude="Latitude" --fieldname-center-longitude="Longitude" < path/to/in.csv > path/to/out.csv 2> path/to/err.csv

7. If input CSV file contains latitude and longitude coordinates for (i) a centroid and (ii) the northeast and southwest corners of a bounding box:

   1. Identify columns of input CSV file that contain latitude and longitude coordinates, e.g., “Latitude_C”, “Longitude_C”, “Latitude_N”, “Longitude_E”, “Latitude_S”, and “Longitude_W”.

   2. Assign UBIDs:

      • buildingid append2csv latlng --code-length=11 --fieldname-code="UBID" --fieldname-center-latitude="Latitude_C" --fieldname-center-longitude="Longitude_C" --fieldname-north-latitude="Latitude_N" --fieldname-east-longitude="Longitude_E" --fieldname-south-latitude="Latitude_S" --fieldname-west-longitude="Longitude_W" < path/to/in.csv > path/to/out.csv 2> path/to/err.csv

8. If input CSV file contains hex-encoded well-known binary (WKB) strings:

   1. Identify column of input CSV file that contains hex-encoded WKB strings, e.g., “WKB”.

   2. Assign UBIDs:

      • buildingid append2csv wkb --code-length=11 --fieldname-code="UBID" --fieldname-wkbstr="WKB" < path/to/in.csv > path/to/out.csv 2> path/to/err.csv

9. If input CSV file contains well-known text (WKT) strings:

   1. Identify column of input CSV file that contains WKT strings, e.g., “WKT”.

   2. Assign UBIDs:

      • buildingid append2csv wkt --code-length=11 --fieldname-code="UBID" --fieldname-wktstr="WKT" < path/to/in.csv > path/to/out.csv 2> path/to/err.csv

Notes

See buildingid append2csv --help for full help.

Prerequisites

1. buildingid command is installed.

   • Verify installation:

     • buildingid --version

       • Expected output: “buildingid, version 2.0.0” (or higher version)

Step-by-step instructions

1. Locate left input CSV file, e.g., path/to/left.csv.

2. Locate right input CSV file, e.g., path/to/right.csv.

3. Locate output CSV file (generated), e.g., path/to/out.csv.

4. Identify column of left input CSV file that contains UBID code strings, e.g., “UBID”.

5. Identify column of right input CSV file that contains UBID code strings, e.g., “UBID”.

6. Cross-reference UBIDs:

   • buildingid crossref path/to/left.csv path/to/right.csv path/to/out.csv --left-fieldname-code="UBID" --right-fieldname-code="UBID"

Notes

See buildingid crossref --help for full help.

Default behavior is for output CSV file to be many-to-many (i.e., many records in left input CSV file are cross-referenced with many records in right input CSV file). Use --left-group-by-jaccard and --right-group-by-jaccard options for one-to-many and many-to-one, respectively.

Default behavior is for output CSV file to include only columns that contain UBID code strings. Use --include-left-field and --include-right-field options to include other columns.

Prerequisites

1. Geospatial Data Abstraction Library (GDAL) is installed.

   • Verify installation:

     • ogr2ogr --version

       • Expected output: “GDAL 2.3.1, released 2018/06/22” (version and release date may vary)

Step-by-step instructions

1. Locate input Esri shapefile, e.g., path/to/in.shp.

2. Locate input PRJ file, e.g., path/to/in.prj.

3. Locate output CSV file (generated), e.g., path/to/out.csv.

4. Convert input Esri shapefile into output CSV file:

   • ogr2ogr -s_srs "$(cat path/to/in.prj)" -t_srs "EPSG:4326" -f CSV path/to/out.csv path/to/in.shp -lco GEOMETRY=AS_WKT

Notes

See ogr2ogr --long-usage for full help.

Output CSV file has added “WKT” column whose elements are well-known text (WKT) strings; enabled by -lco GEOMETRY=AS_WKT option.

Projection system for geographic coordinates in output CSV file is WGS84; enabled by -t_srs "EPSG:4326" option.

Records in input Esri shapefile are converted into rows in output CSV file, where fields in input Esri shapefile are converted into columns in output CSV file.

Shapes in input Esri shapefile are converted into elements of “WKT” column of output CSV file.