pnnl-building_id 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49ac47cb4cc46314480468bea4e7e9789f870c277573d46d2b95efc79b312dd4
+  data.tar.gz: 83ea482877932626e12356a88542d0de86918cf082be193683a2da643bbde54f
+SHA512:
+  metadata.gz: c9257253ed4f74811a6f83070999941f9be631104b60d11d0853c9ced6e14797f99eb13b490cafe3df255c42119ad1643fa7be191cda204e24f0250c785dda81
+  data.tar.gz: 34408cc0c29ba7feee402e662afe952481074e2cbde709679ff7fae32571c88473a78ff2b3e7f7d07d60edd83d01d21d6198d21187cbf423f9de331b0c7c3ea2

data/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) 2018, Battelle Memorial Institute
+All rights reserved.
+
+1. Battelle Memorial Institute (hereinafter Battelle) hereby grants permission
+   to any person or entity lawfully obtaining a copy of this software and
+   associated documentation files (hereinafter "the Software") to redistribute
+   and use the Software in source and binary forms, with or without
+   modification.  Such person or entity may use, copy, modify, merge, publish,
+   distribute, sublicense, and/or sell copies of the Software, and may permit
+   others to do so, subject to the following conditions:
+
+   * Redistributions of source code must retain the above copyright notice, this
+     list of conditions and the following disclaimers.
+   * Redistributions in binary form must reproduce the above copyright notice,
+     this list of conditions and the following disclaimer in the documentation
+     and/or other materials provided with the distribution.
+   * Other than as used herein, neither the name Battelle Memorial Institute or
+     Battelle may be used in any form whatsoever without the express written
+     consent of Battelle.
+
+2. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL BATTELLE OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,76 @@
+# Unique Building Identification (UBID)
+
+**Website:** https://buildingid.pnnl.gov/
+
+## Documentation
+
+### Install
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pnnl-building_id'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install pnnl-building_id
+```
+
+## Usage
+
+The `pnnl-building_id` package supports one usage:
+* Application programming interface (API)
+
+### The API
+
+UBID codecs are encapsulated in separate modules:
+* `PNNL::BuildingId::V3` (format: "C-n-e-s-w")
+
+Modules export the same API:
+* `decode(String) ~> PNNL::BuildingId::CodeArea`
+* `encode(Float, Float, Float, Float, Float, Float, Integer) ~> String`
+* `encode_code_area(PNNL::BuildingId::CodeArea) ~> String`
+* `valid?(String) ~> Boolean`
+
+In the following example, a UBID code is decoded and then re-encoded:
+
+```ruby
+# Use the "C-n-e-s-w" format for UBID codes.
+require 'pnnl/building_id'
+
+# Initialize UBID code.
+code = '849VQJH6+95J-51-58-42-50'
+$stdout.puts(code)
+
+# Decode the UBID code.
+code_area = PNNL::BuildingId::V3.decode(code)
+$stdout.puts(code_area)
+
+# Resize the resulting UBID code area.
+#
+# The effect of this operation is that the height and width of the UBID code
+# area are reduced by half an OLC code area.
+new_code_area = code_area.resize
+$stdout.puts(new_code_area)
+
+# Encode the new UBID code area.
+new_code = PNNL::BuildingId::V3.encode_code_area(new_code_area)
+$stdout.puts(new_code)
+
+# Test that the new UBID code matches the original.
+$stdout.puts(code == newCode)
+```
+
+## License
+
+The gem is available as open source under the terms of the [3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause).
+
+## Contributions
+
+Contributions are accepted on [GitHub](https://github.com/) via the fork and pull request workflow. See [here](https://help.github.com/articles/using-pull-requests/) for more information.

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PNNL::BuildingId'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/lib/pnnl/building_id/code_area.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PNNL
+  module BuildingId
+    # A UBID code area.
+    class CodeArea
+      attr_reader :centroid_code_area, :centroid_code_length, :north_latitude, :south_latitude, :east_longitude, :west_longitude
+
+      # Default constructor.
+      #
+      # @param centroid_code_area [PlusCodes::CodeArea]
+      # @param centroid_code_length [Integer]
+      # @param north_latitude [Float]
+      # @param south_latitude [Float]
+      # @param east_longitude [Float]
+      # @param west_longitude [Float]
+      def initialize(centroid_code_area, centroid_code_length, north_latitude, south_latitude, east_longitude, west_longitude)
+        @centroid_code_area = centroid_code_area
+        @centroid_code_length = centroid_code_length
+        @north_latitude = north_latitude
+        @south_latitude = south_latitude
+        @east_longitude = east_longitude
+        @west_longitude = west_longitude
+      end
+
+      # Returns a resized version of this UBID code area, where the latitude and
+      # longitude of the lower left and upper right corners of the OLC bounding
+      # box are moved inwards by dimensions that correspond to half of the height
+      # and width of the OLC grid reference cell for the centroid.
+      #
+      # The purpose of the resizing operation is to ensure that re-encoding a
+      # given UBID code area results in the same coordinates.
+      #
+      # @return [PNNL::BuildingId::CodeArea]
+      def resize
+        # Calculate the (half-)dimensions of OLC grid reference cell for the
+        # centroid.
+        half_height = Float(@centroid_code_area.north_latitude - @centroid_code_area.south_latitude) / 2.0
+        half_width = Float(@centroid_code_area.east_longitude - @centroid_code_area.west_longitude) / 2.0
+
+        # Construct and return the new UBID code area.
+        self.class.new(
+          @centroid_code_area,
+          @centroid_code_length,
+          @north_latitude - half_height,
+          @south_latitude + half_height,
+          @east_longitude - half_width,
+          @west_longitude + half_width
+        )
+      end
+    end
+  end
+end

data/lib/pnnl/building_id/v3.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "plus_codes"
+require "plus_codes/code_area"
+require "plus_codes/open_location_code"
+require "pnnl/building_id/code_area"
+
+module PNNL
+  module BuildingId
+    module V3
+      # The separator for OLC codes in a UBID code.
+      SEPARATOR_ = "-"
+
+      # Format string for UBID codes.
+      FORMAT_STRING_ = "%s-%.0f-%.0f-%.0f-%.0f"
+
+      # Regular expression for UBID codes.
+      RE_PATTERN_ = Regexp.new([
+        "^",
+        "([#{Regexp.quote(PlusCodes::CODE_ALPHABET)}]{4,8}#{Regexp.quote(PlusCodes::SEPARATOR)}[#{Regexp.quote(PlusCodes::CODE_ALPHABET)}]*)",
+        "#{Regexp.quote(SEPARATOR_)}",
+        "(0|[1-9][0-9]*)",
+        "#{Regexp.quote(SEPARATOR_)}",
+        "(0|[1-9][0-9]*)",
+        "#{Regexp.quote(SEPARATOR_)}",
+        "(0|[1-9][0-9]*)",
+        "#{Regexp.quote(SEPARATOR_)}",
+        "(0|[1-9][0-9]*)",
+        "$",
+      ].join)
+
+      # The first group of a UBID code is the OLC for the geometric center of mass
+      # (i.e., centroid) of the building footprint.
+      RE_GROUP_OPENLOCATIONCODE_ = 1
+
+      # The second group of the UBID code is the Chebyshev distance in OLC grid units
+      # from the OLC for the centroid of the building footprint to the northern extent
+      # of the OLC bounding box for the building footprint.
+      RE_GROUP_NORTH_ = 2
+
+      # The third group of the UBID code is the Chebyshev distance in OLC grid units
+      # from the OLC for the centroid of the building footprint to the eastern extent
+      # of the OLC bounding box for the building footprint.
+      RE_GROUP_EAST_ = 3
+
+      # The fourth group of the UBID code is the Chebyshev distance in OLC grid units
+      # from the OLC for the centroid of the building footprint to the southern extent
+      # of the OLC bounding box for the building footprint.
+      RE_GROUP_SOUTH_ = 4
+
+      # The fifth group of the UBID code is the Chebyshev distance in OLC grid units
+      # from the OLC for the centroid of the building footprint to the western extent
+      # of the OLC bounding box for the building footprint.
+      RE_GROUP_WEST_ = 5
+
+      # Returns the UBID code area for the given UBID code.
+      #
+      # @param code [String] the UBID code
+      # @return [PNNL::BuildingId::CodeArea] The UBID code area.
+      # @raise [ArgumentError] if the UBID code is invalid or if the OLC for the centroid of the building footprint is invalid
+      def self.decode(code)
+        if !(md = RE_PATTERN_.match(code)).nil?
+          # Extract the OLC for the centroid of the building footprint.
+          centroid_openlocationcode = md[RE_GROUP_OPENLOCATIONCODE_]
+
+          # Decode the OLC for the centroid of the building footprint.
+          centroid_openlocationcode_CodeArea = open_location_code.decode(centroid_openlocationcode)
+
+          # Calculate the size of the OLC for the centroid of the building footprint
+          # in decimal degree units.
+          height = centroid_openlocationcode_CodeArea.north_latitude - centroid_openlocationcode_CodeArea.south_latitude
+          width = centroid_openlocationcode_CodeArea.east_longitude - centroid_openlocationcode_CodeArea.west_longitude
+
+          # Calculate the size of the OLC bounding box for the building footprint,
+          # assuming that the datum are Chebyshev distances.
+          north_latitude = centroid_openlocationcode_CodeArea.north_latitude + (Float(md[RE_GROUP_NORTH_]) * height)
+          east_longitude = centroid_openlocationcode_CodeArea.east_longitude + (Float(md[RE_GROUP_EAST_]) * width)
+          south_latitude = centroid_openlocationcode_CodeArea.south_latitude - (Float(md[RE_GROUP_SOUTH_]) * height)
+          west_longitude = centroid_openlocationcode_CodeArea.west_longitude - (Float(md[RE_GROUP_WEST_]) * width)
+
+          # Construct and return the UBID code area.
+          return PNNL::BuildingId::CodeArea.new(
+            centroid_openlocationcode_CodeArea,
+            centroid_openlocationcode.length - PlusCodes::SEPARATOR.length,
+            north_latitude,
+            south_latitude,
+            east_longitude,
+            west_longitude
+          )
+        else
+          raise ArgumentError.new('Invalid UBID')
+        end
+      end
+
+      # Returns the UBID code for the given coordinates.
+      #
+      # @param latitude_lo [Float] the latitude in decimal degrees of the southwest corner of the minimal bounding box for the building footprint
+      # @param longitude_lo [Float] the longitude in decimal degrees of the southwest corner of the minimal bounding box for the building footprint
+      # @param latitude_hi [Float] the latitude in decimal degrees of the northeast corner of the minimal bounding box for the building footprint
+      # @param longitude_hi [Float] the longitude in decimal degrees of the northeast corner of the minimal bounding box for the building footprint
+      # @param latitudeCenter [Float] the latitude in decimal degrees of the centroid of the building footprint
+      # @param longitudeCenter [Float] the longitude in decimal degrees of the centroid of the building footprint
+      # @param options [Hash]
+      # @option options [Integer] :codeLength (`PlusCodes::PAIR_CODE_LENGTH`) the OLC code length (not including the separator)
+      # @return [String] The UBID code.
+      # @raise [ArgumentError] if the OLC for the centroid of the building footprint cannot be encoded (e.g., invalid code length)
+      def self.encode(latitude_lo, longitude_lo, latitude_hi, longitude_hi, latitudeCenter, longitudeCenter, options = {})
+        codeLength = options[:codeLength] || PlusCodes::PAIR_CODE_LENGTH
+
+        # Encode the OLCs for the northeast and southwest corners of the minimal
+        # bounding box for the building footprint.
+        northeast_openlocationcode = open_location_code.encode(latitude_hi, longitude_hi, codeLength)
+        southwest_openlocationcode = open_location_code.encode(latitude_lo, longitude_lo, codeLength)
+
+        # Encode the OLC for the centroid of the building footprint.
+        centroid_openlocationcode = open_location_code.encode(latitudeCenter, longitudeCenter, codeLength)
+
+        # Decode the OLCs for the northeast and southwest corners of the minimal
+        # bounding box for the building footprint.
+        northeast_openlocationcode_CodeArea = open_location_code.decode(northeast_openlocationcode)
+        southwest_openlocationcode_CodeArea = open_location_code.decode(southwest_openlocationcode)
+
+        # Decode the OLC for the centroid of the building footprint.
+        centroid_openlocationcode_CodeArea = open_location_code.decode(centroid_openlocationcode)
+
+        # Calculate the size of the OLC for the centroid of the building footprint
+        # in decimal degree units.
+        height = centroid_openlocationcode_CodeArea.north_latitude - centroid_openlocationcode_CodeArea.south_latitude
+        width = centroid_openlocationcode_CodeArea.east_longitude - centroid_openlocationcode_CodeArea.west_longitude
+
+        # Calculate the Chebyshev distances to the northern, eastern, southern and
+        # western of the OLC bounding box for the building footprint.
+        delta_north = (northeast_openlocationcode_CodeArea.north_latitude - centroid_openlocationcode_CodeArea.north_latitude) / height
+        delta_east = (northeast_openlocationcode_CodeArea.east_longitude - centroid_openlocationcode_CodeArea.east_longitude) / width
+        delta_south = (centroid_openlocationcode_CodeArea.south_latitude - southwest_openlocationcode_CodeArea.south_latitude) / height
+        delta_west = (centroid_openlocationcode_CodeArea.west_longitude - southwest_openlocationcode_CodeArea.west_longitude) / width
+
+        # Construct and return the UBID code.
+        Kernel.sprintf(FORMAT_STRING_, centroid_openlocationcode, delta_north, delta_east, delta_south, delta_west)
+      end
+
+      # Returns the UBID code for the given UBID code area.
+      #
+      # @param code_area [PNNL::BuildingId::CodeArea]
+      # @return [String] The UBID code.
+      # @raise [ArgumentError] if the OLC for the centroid of the building footprint cannot be encoded (e.g., invalid code length)
+      def self.encode_code_area(code_area)
+        raise ArgumentError.new('Invalid PNNL::BuildingId::CodeArea') if code_area.nil?
+
+        # Delegate.
+        encode(code_area.south_latitude, code_area.west_longitude, code_area.north_latitude, code_area.east_longitude, code_area.centroid_code_area.latitude_center, code_area.centroid_code_area.longitude_center, codeLength: code_area.centroid_code_length)
+      end
+
+      # Is the given UBID code valid?
+      #
+      # @param code [String] the UBID code
+      # @return [Boolean] `true` if the UBID code is valid. Otherwise, `false`.
+      def self.valid?(code)
+        # Undefined UBID codes are invalid.
+        return false if code.nil?
+
+        # Attempt to match the regular expression.
+        if !(md = RE_PATTERN_.match(code)).nil?
+          open_location_code.valid?(md[RE_GROUP_OPENLOCATIONCODE_])
+        else
+          # UBID codes that fail to match the regular expression are invalid.
+          false
+        end
+      end
+
+      private
+
+      # Singleton instance of OLC.
+      #
+      # @return [PlusCodes::OpenLocationCode]
+      def self.open_location_code
+        @@open_location_code ||= PlusCodes::OpenLocationCode.new
+      end
+    end
+  end
+end

data/lib/pnnl/building_id/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PNNL
+  module BuildingId
+    VERSION = '0.1.0'
+  end
+end

data/lib/pnnl/building_id.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PNNL
+  module BuildingId
+    autoload :CodeArea, 'pnnl/building_id/code_area'
+    autoload :V3, 'pnnl/building_id/v3'
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: pnnl-building_id
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mark Borkum
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-10-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: plus_codes
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+description: Unique Building Identification (UBID) for Ruby
+email:
+- mark.borkum@pnnl.gov
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/pnnl/building_id.rb
+- lib/pnnl/building_id/code_area.rb
+- lib/pnnl/building_id/v3.rb
+- lib/pnnl/building_id/version.rb
+homepage: https://buildingid.pnnl.gov/
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Unique Building Identification (UBID) for Ruby
+test_files: []