Use pnnl-buildingid package for UBID encoding

[markborkum]

The data pipeline implements the UBID "encode" function (c.f., https://github.com/opencitymodel/data-pipeline/blob/master/footprints/prep-msfp/grid-and-attrs/app.js#L85).

The pnnl-buildingid package is available via npm (GitHub repository: https://github.com/pnnl/buildingid-js).

To encode a UBID using the turf package to calculate the axis-aligned minimum bounding rectangle and center of mass for a GeoJSON primitive:

var UniqueBuildingIdentification = require('pnnl-buildingid');

var turf = require('turf');

function ubid(primitive, codeLength) {
  var bbox = turf.bbox(primitive);
  var centroid = turf.centroid(primitive);
  return UniqueBuildingIdentification.v3.encode(bbox[1], bbox[0], bbox[3], bbox[2], centroid.geometry.coordinates[1], centroid.geometry.coordinates[0], codeLength);
}

[agilliland]

Thanks for putting this together @markborkum , I'll update the code to use the official ubid npm package in the next few days or so.

[markborkum]

@agilliland, No problem!

FYI: Please consider using a GEOS-derived package for centroid calculation. In many cases, turf.js does not give the same result as GEOS. For example, the geometry for AT&T Park in San Francisco (L156407 of the Socrata open dataset https://dev.socrata.com/foundry/data.sfgov.org/2s2t-jwzp):

MULTIPOLYGON (((-122.38881976231 37.77923523529, -122.388804119691 37.779248288341, -122.388804089115 37.779249576693, -122.388736336901 37.779305686423, -122.388735345943 37.779305673294, -122.388703640352 37.779332128723, -122.387810661362 37.778614548526, -122.387814609477 37.778585892065, -122.387811140111 37.778585064958, -122.387805638074 37.778578430108, -122.387805614265 37.778578395859, -122.387816682916 37.77854710155, -122.387824621151 37.778543969508, -122.387829917765 37.778545142646, -122.387843084163 37.778523260839, -122.387896335497 37.778468172867, -122.387962000419 37.77843477294, -122.388048278897 37.778413723325, -122.388043887139 37.778360677165, -122.387972853509 37.778366564486, -122.387972011798 37.778359120335, -122.387968898485 37.778331585446, -122.387967645497 37.778320504815, -122.387967634233 37.778320400298, -122.387963916965 37.778287525117, -122.387963895553 37.778287339509, -122.387960863375 37.778260520923, -122.387954289726 37.778202371488, -122.387949281041 37.778166385522, -122.389835233078 37.77745188375, -122.38986971218 37.777471016061, -122.390045769351 37.777404202489, -122.390062963308 37.77741191262, -122.390063248196 37.777416158076, -122.390111512516 37.777443103221, -122.39010759583 37.777448050188, -122.390152249683 37.777471863556, -122.390158544926 37.777464862711, -122.390168691674 37.777463362365, -122.390201430179 37.777481801759, -122.390201450581 37.777481838709, -122.390202683332 37.77748884698, -122.390196947837 37.777495673325, -122.390247420396 37.777522166354, -122.39023235128 37.777538456127, -122.390224289065 37.77754780037, -122.39035498364 37.777624142545, -122.390567391687 37.777748214387, -122.390566999735 37.77774863854, -122.390567525042 37.777748947834, -122.390591503993 37.7777222051, -122.390775600375 37.777511131413, -122.391163247776 37.777816527598, -122.391163268176 37.777816568151, -122.390973596727 37.778020188724, -122.391006786462 37.778038443423, -122.391006820466 37.778038506507, -122.390993361707 37.778053904334, -122.390976857436 37.778045038757, -122.390835686813 37.778206376238, -122.390850458566 37.778214261624, -122.390850493704 37.778214324709, -122.390837583723 37.77823041653, -122.390813486805 37.77821709639, -122.390780069996 37.778257200123, -122.390785063234 37.77830858422, -122.390823399516 37.778336990838, -122.39085264379 37.778313813984, -122.390867077617 37.778314179809, -122.390956144591 37.77838670738, -122.390956191064 37.778386792093, -122.390956100561 37.778396396251, -122.390879915489 37.77845704472, -122.390881401454 37.77845834825, -122.390881435458 37.778458410433, -122.390487907156 37.778770264228, -122.389936204412 37.779207393523, -122.389933974451 37.779205292256, -122.389447210953 37.77959773692, -122.389404939621 37.779565835728, -122.389356546938 37.779604319533, -122.389385249504 37.779627102385, -122.38938530279 37.779627181697, -122.389385283306 37.779637140865, -122.389293394157 37.779709285436, -122.389280047221 37.779709292973, -122.389252372555 37.779687162918, -122.389203439037 37.779726076137, -122.389151650465 37.779682070992, -122.388793058965 37.779398370319, -122.388793015881 37.779398309032, -122.388792658821 37.779394941069, -122.38877692709 37.779382491581, -122.388776873802 37.779382415873, -122.388783272226 37.779377285544, -122.388759566159 37.779358014369, -122.388869280695 37.779274401268, -122.38881976231 37.77923523529), (-122.389625551223 37.778787753654, -122.390022584172 37.778474208924, -122.390046898675 37.7784935198, -122.390059946264 37.778481594162, -122.390088152711 37.778453568019, -122.390103437588 37.778424777596, -122.390111347401 37.778394833801, -122.390116110847 37.778363260377, -122.390114143257 37.778330031176, -122.390101669875 37.778301407733, -122.39008430577 37.77827219618, -122.390061702629 37.778247821001, -122.390031474075 37.778223121195, -122.389989871514 37.778201471636, -122.38994266161 37.778176904607, -122.389925657026 37.778195876403, -122.389420752733 37.777912640753, -122.389420055657 37.777912787251, -122.389250616934 37.777901612833, -122.389172610862 37.777849327882, -122.389141368803 37.777790396354, -122.389111008608 37.777802237266, -122.388743193 37.777931686253, -122.388722412831 37.777990487231, -122.388469735593 37.778085792145, -122.38846982455 37.778086657111, -122.388472019367 37.778085876226, -122.388497455754 37.778343820929, -122.388498808883 37.778343734243, -122.388521469209 37.778565731995, -122.388520293163 37.778565807963, -122.388530573085 37.778646332764, -122.388532309016 37.778645930041, -122.389048331131 37.779055009184, -122.38888666188 37.779184683975, -122.388944286357 37.779233343004, -122.389125460634 37.779074434049, -122.389125443332 37.779074769197, -122.389125470593 37.779074746687, -122.389164929554 37.779086193004, -122.389274409874 37.778979794197, -122.389366956551 37.778929832434, -122.389625551223 37.778787753654), (-122.388372451429 37.778574605156, -122.388355623774 37.77841410796, -122.388347867669 37.778355167791, -122.388250520718 37.77836134423, -122.388254674487 37.778407281707, -122.388234227605 37.778408689096, -122.388248431304 37.77854105345, -122.388264910509 37.778540216988, -122.388269666512 37.778581336459, -122.388328283828 37.778577498445, -122.388372451429 37.778574605156), (-122.388423918722 37.778350342391, -122.388445393576 37.778569826769, -122.388459002116 37.778568935623, -122.388518549129 37.77856503223, -122.388496168064 37.778345758216, -122.388423918722 37.778350342391)))

GEOS: POINT (-122.3896056846471 37.7784744216144) (UBID: 849VQJH6+95J-51-58-42-50)
turf.js: POINT (-122.38936139014925, 37.77844746786376) (UBID: 849VQJH6+97C-52-50-41-58)

[agilliland]

@markborkum your last comment definitely has me a bit more concerned given that a UBID doesn't work properly if we can't ensure everyone is calculating it the exact same way for a common polygon.

Does the UBID spec reference a specific algorithm for how the centroid and bounding box of the polygon need to be calculated? If not then I think that should be considered as it seems imperative to ensuring consistency.

Based on your reference to GEOS it looks like they have a few variants they support https://geos.osgeo.org/doxygen/classgeos_1_1algorithm_1_1Centroid.html
and this one appears to be the default http://www.faqs.org/faqs/graphics/algorithms-faq/ (subject 2.02)

If that is indeed the supported centroid algorithm for UBID then it should probably be referenced somewhere.

[markborkum]

@agilliland, The specification for the UBID encoding operation does not reference specific algorithms for the calculation of the latitude and longitude coordinates for the centroid (or for the calculation of the minimum bounding rectangle) because the UBID encoding operation receives these numbers as input.

It is important to distinguish between the UBID string itself and assertions that contain a UBID string. Since UBID strings are endurants, all syntactically valid UBID strings are consistent. For example, by design, any syntactically valid UBID string can be decoded. However, the same is not necessarily true of assertions that contain UBID strings. For example, the provenance of a UBID assertion "UBID X was computed from geometry Y using algorithm Z" may be refuted. Best practice is for the data provider to document the provenance of their datasets (see https://www.dataone.org/best-practices/provide-citation-and-document-provenance-your-dataset for details).

A relevant issue for the turf project is Turfjs/turf#334.

I have created a new issue to document the algorithms that are used by the UBID Python package (see https://github.com/pnnl/buildingid/issues/7 for details).