Merge pull request #133 from urbanopt/develop

Version 0.5.0

Author: kflemin

.github/pull_request_template.md

@@ -1,4 +1,4 @@
-### Addresses #[issue number here]
+### Resolves #[issue number here]
 
 ### Pull Request Description
 
@@ -9,5 +9,5 @@
 - [ ] Unit tests have been added or updated
 - [ ] Documentation has been modified appropriately
 - [ ] All ci tests pass (green)
-- [ ] An [ISSUE](https://github.com/urbanopt/urbanopt-geojson-gem/issues) has been created that this is addressing. Issues will get added to the Change Log when the change_log.rb script is run.
+- [ ] An [issue](https://github.com/urbanopt/urbanopt-geojson-gem/issues) has been created (which will be used for the changelog)
 - [ ] This branch is up-to-date with develop

CHANGELOG.md

@@ -1,7 +1,14 @@
 # URBANopt GeoJSON Gem
 
+## Version 0.5.0
+Date Range 09/26/20 - 12/02/20
+
+- Fixed [#124]( https://github.com/urbanopt/urbanopt-geojson-gem/issues/124 ), DOCUMENTATION: Add docs on scaling for building footprint using building area
+- Fixed [#126]( https://github.com/urbanopt/urbanopt-geojson-gem/issues/126 ), [BUG] setting timesteps_per_hour in a feature throws an error
+- Fixed [#131]( https://github.com/urbanopt/urbanopt-geojson-gem/issues/131 ), OpenStudio 3.1.0 support
+
 ## Version 0.4.0
-Date Rage 08/08/20 - 09/25/20
+Date Range 08/08/20 - 09/25/20
 
 Accepted Pull Requests: 11
 - Fixed [#92]( https://github.com/urbanopt/urbanopt-geojson-gem/pull/92 ), Adds scaling for building footprint using building area

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Version 1.0
 
-The URBANopt<sup>&trade;</sup> team welcomes your contribution to the project. You can contribute to the URBANopt project in several ways: by using the software, reporting issues, contributing documentation, or contributing code back to the project. The GitHub [Contributing to Open Source](https://opensource.guide/how-to-contribute/) guide provides a good overview. If you contribute code, you agree that your contribution may be incorporated into the URBANopt Software Development Kit (SDK) and made available under the URBANopt SDK license.
+The URBANopt&trade; team welcomes your contribution to the project. You can contribute to the URBANopt project in several ways: by using the software, reporting issues, contributing documentation, or contributing code back to the project. The GitHub [Contributing to Open Source](https://opensource.guide/how-to-contribute/) guide provides a good overview. If you contribute code, you agree that your contribution may be incorporated into the URBANopt Software Development Kit (SDK) and made available under the URBANopt SDK license.
 
 The contribution process for URBANopt is composed of three steps:
 

RDOC_MAIN.md

@@ -2,53 +2,57 @@
 
 ### [back to main docs](../)
 
-The URBANopt<sup>&trade;</sup> GeoJSON Gem has been developed by restructuring methods extracted from the
+The URBANopt&trade; GeoJSON Gem has been developed by restructuring methods extracted from the
 [urban_geometry_creation](https://github.com/NREL/openstudio-urban-measures/tree/develop/measures/urban_geometry_creation)
 and
 [urban_geometry_creation_zoning.](https://github.com/NREL/openstudio-urban-measures/tree/develop/measures/urban_geometry_creation_zoning)
 
-The +urban_geometry_creation+ measure can be used to create an OpenStudio Model for a
+The `urban_geometry_creation` measure can be used to create an OpenStudio Model for a
 building feature from the feature file and create the surrounding buildings that are shading the
 building feature as shading objects.
-The arguments used in the measure are the +GeoJSON File+, +Feature ID+ of the building and +Surrounding Buildings+. The
-Surrounding Buildings argument takes two possible choices - None or Shading Only. The None choice
+The arguments used in the measure are the `geojson_file`, `feature_id` of the building, `surrounding_buildings` and `scale_footprint_area_by_floor_area`. The
+`surrounding_buildings` argument takes two possible choices - None or Shading Only. The None choice
 would create no other buildings adjacent to the building feature while the Shading Only option
-determines what other buildings are shading the building feature and creates them as OpenStudio Shading Surfaces.
+determines what other buildings are shading the building feature and creates them as OpenStudio
+Shading Surfaces. The `scale_footprint_area_by_floor_area` is an optional argument that is set to
+false by default. When set to true, the building footprint area is calculated from the
+floor_area/number_of_stories for the building in the GeoJSON file and this footprint area is used to
+scale the building coordinates and create the building.
 
-The +urban_geometry_creation_zoning+ measure has the same capabilities as the
-+urban_geometry_creation+ measure, however it also creates core and perimeter zones for the spaces
-in the OpenStudio Model. It takes in the same arguments as the +urban_geometry_creation+ measure. 
+The `urban_geometry_creation_zoning` measure has the same capabilities as the
+`urban_geometry_creation` measure, however it also creates core and perimeter zones for the spaces
+in the OpenStudio Model. It takes in the `geojson_file`, `feature_id` of the building,
+`surrounding_buildings` as arguments.
 
 The main components of the gem are:
 
-- geojson.rb : Base gem file that imports all modules and classes. 
+- geojson.rb : Base gem file that imports all modules and classes.
 - extension.rb : The extension class inherits from OpenStudio::Extension::Extension, and
-  overrides the following methods as needed -
+  overrides the following methods as needed
     - _measures_dir_
     - _files_dir_
     - _doc_templates_dir_
-- Gemfile and .gemspec : Describe the extension dependencies on other gems. 
-- Classes and Modules within +lib/urbanopt/geojson+ -
-
+- Gemfile and .gemspec : Describe the extension dependencies on other gems.
+- Classes and Modules within `lib/urbanopt/geojson`
 
     *Modules that do not require instances for calling the methods:*
 
     - URBANopt::GeoJSON::Helper : Contains methods extracted from the two measures to
-      perform utility-like tasks like - +is_shaded+ and +is_shadowed+.
+      perform utility-like tasks like - `is_shaded` and `is_shadowed`.
     - URBANopt::GeoJSON::Zoning : Contains methods extracted from
-      +urban_geometry_creation_zoning+ .
+      `urban_geometry_creation_zoning`.
     - URBANopt::GeoJSON::Model : Contains methods that perform tasks on an instance of
-      +OpenStudio::Model::Model+. 
+      `OpenStudio::Model::Model`.
 
     *Classes and subclasses that contain instance-dependant methods and private methods
     that perform tasks on the given feature.*
 
-    - URBANopt::GeoJSON::GeoFile : Contains a +get_feature+ method that returns an
+    - URBANopt::GeoJSON::GeoFile : Contains a `get_feature` method that returns an
       instance of a Feature Subclass for the the feature type. Also contains methods to validate the GeoJSON
-      file against the GeoJSON schema. 
-    - URBANopt::GeoJSON::Feature : Contains methods to return +feature+ +id+ , +name+ ,
-      +multiple+ +polygons+ +coordinates+ which are inherited by classes for all feature types.
+      file against the GeoJSON schema.
+    - URBANopt::GeoJSON::Feature : Contains methods to return `feature id` , `name` ,
+      `multiple polygons coordinates` which are inherited by classes for all feature types.
     - URBANopt::GeoJSON::Building : A subclass of Feature, contains class methods that
-      are specific to handling features of the Building type. 
+      are specific to handling features of the Building type.
     - URBANopt::GeoJSON::DistrictSystem : A subclass of Feature, contains class methods
-      that are specific to handling features of District System type. *Note: This subclass does not contain any methods yet*. 
+      that are specific to handling features of District System type. *Note: This subclass does not contain any methods yet*.

README.md

@@ -1,6 +1,6 @@
 # URBANopt GeoJSON Gem
 
-Library and measures to translate URBANopt<sup>&trade;</sup> GeoJSON format to OpenStudio. See the [developer documentation](https://urbanopt.github.io/urbanopt-geojson-gem/) for more details.
+Library and measures to translate URBANopt&trade; GeoJSON format to OpenStudio. See the [developer documentation](https://urbanopt.github.io/urbanopt-geojson-gem/) for more details.
 
 ## Installation
 
@@ -12,7 +12,7 @@ gem 'urbanopt-geojson'
 
 And then execute:
 
-    $ bundle
+    $ bundle install
 
 Or install it yourself as:
 

docs/.vuepress/components/InnerJsonSchema.vue

@@ -13,7 +13,6 @@ import highlightJson from "../highlight";
 import { emptyPromise } from '../utils';
 
 const JSONSchemaViewP = emptyPromise();
-const $RefParserP = emptyPromise();
 
 export default {
   name: "InnerJsonSchema",
@@ -24,27 +23,24 @@ export default {
     };
   },
   created() {
+    // created only runs on the client, which is good because
+    // this module causes an error if we load it in a server context
     import("json-schema-view-js").then(JSONSchemaViewP.resolve);
-    import("json-schema-ref-parser/dist/ref-parser.js").then($RefParserP.resolve);
   },
   computed: {
     view() {
-      return Promise.all([$RefParserP, JSONSchemaViewP])
-        .then(([$RefParser]) => $RefParser.default.dereference(this.schema))
-        .then(
-          s =>
-            new window.JSONSchemaView(s, 2, {
-              theme: "dark"
-            })
-        );
+      return JSONSchemaViewP
+        .then( () => new window.JSONSchemaView(this.schema, 2, {
+          theme: "dark"
+        }));
     },
     schemaFormatted() {
       return highlightJson(JSON.stringify(this.schema, null, 2));
     }
   },
   methods: {
     async replaceRenderedSchema() {
-      const v = await this.view;
+      const v = await this.view; // this never resolves on the server
       this.$refs.schemaTarget.innerHtml = "";
       this.$refs.schemaTarget.appendChild(v.render());
     }

docs/.vuepress/config.js

@@ -1,3 +1,5 @@
+const path = require('path');
+
 module.exports = {
   base: '/urbanopt-geojson-gem/',
   themeConfig: {
@@ -18,5 +20,13 @@ module.exports = {
         ]
       }
     ]
-  }
+  },
+  chainWebpack: config => {
+    config.module
+      .rule('json')
+        .test(/\.json$/)
+        .use(path.join(__dirname, 'json-schema-deref-loader.js'))
+          .loader(path.join(__dirname, 'json-schema-deref-loader.js'))
+          .end()
+  },
 };

docs/.vuepress/highlight.js

@@ -1,4 +1,4 @@
-import hljs from "highlight.js/lib/highlight.js";
+import hljs from "highlight.js";
 import json from "highlight.js/lib/languages/json";
 
 hljs.registerLanguage("json", json);

docs/.vuepress/json-schema-deref-loader.js

@@ -0,0 +1,22 @@
+// thanks to https://gist.github.com/mgesmundo/07d6ea3958ed4c7d19d1161551fa46ca
+const $RefParser = require('@apidevtools/json-schema-ref-parser')
+
+module.exports = async function () {
+  const parser = new $RefParser()
+  const schema = await parser.dereference(this.resourcePath, {
+    dereference: {
+      circular: false
+    }
+  })
+  const resolve = await parser.resolve(this.resourcePath, {
+    dereference: {
+      circular: false
+    }
+  })
+
+  for (const dep in resolve._$refs) {
+    this.addDependency(dep)
+  }
+
+  return JSON.stringify(schema)
+}

docs/README.md

@@ -2,9 +2,9 @@
 
 ### <StaticLink href="rdoc/">Rdocs</StaticLink>
 
-The URBANopt<sup>&trade;</sup> GeoJSON Gem is an OpenStudio Extension Gem with functionality to translate
+The URBANopt&trade; GeoJSON Gem is an OpenStudio Extension Gem with functionality to translate
 information in a GeoJSON format to energy model inputs.  GeoJSON is a commonly used
-format for describing geospatial data related to the built environment. 
+format for describing geospatial data related to the built environment.
 
 A JSON schema for the GeoJSON format is available at [geojson
 schema](https://github.com/geojson/schema).
@@ -26,5 +26,4 @@ The current functionalities of the URBANopt GeoJSON gem include:
 - Translate Building Feature to an OpenStudio Model.
 - Translate Building Feature to OpenStudio Shading Objects.
 
-The <StaticLink href="rdoc/">Rdocs</StaticLink> contain more information about the URBANopt GeoJSON Gem architecture. 
-
+The <StaticLink href="rdoc/">Rdocs</StaticLink> contain more information about the URBANopt GeoJSON Gem architecture.

docs/package-lock.json

@@ -249,6 +249,13 @@ def create_windows(spaces)
         end
       end
 
+      ##
+      # Used to calculate the perimeter from the floor polygon of a Feature. Returns the perimeter
+      # value.
+      #
+      # [Parameters]
+      # * +feature+ - An instance of URBANopt::GeoJSON::Feature
+      #
       def calculate_perimeter(feature)
         model = OpenStudio::Model::Model.new
         runner = OpenStudio::Measure::OSRunner.new(OpenStudio::WorkflowJSON.new)
@@ -285,9 +292,8 @@ def calculate_perimeter(feature)
       end
 
       ##
-      # Convert to a Hash equivalent for JSON serialization
-      ##
-      # - Exclude attributes with nil values.
+      # Convert to a Hash equivalent for JSON serialization.
+      # Excludes attributes with nil value.
       ##
       def to_hash
         result = {}

lib/urbanopt/geojson/building.rb

@@ -98,6 +98,9 @@ def schema
         return @@feature_schema[feature_type]
       end
 
+      ##
+      # Used to calculate the aspect ratio for a given floor polygon.
+      #
       def calculate_aspect_ratio
         multi_polygons = get_multi_polygons(@feature_json)
         rad_per_deg = 0.017453293
@@ -170,6 +173,8 @@ def calculate_aspect_ratio
         end
       end
 
+      ##
+      # Used to calculate the perimeter multiplier given the aspect ratio, original perimeter and area.
       def get_perimeter_multiplier(area, aspect_ratio, perimeter_original)
         perimeter_new = 2 * (Math.sqrt(area * aspect_ratio) + Math.sqrt(area / aspect_ratio))
         perimeter_ratio = perimeter_original / perimeter_new

lib/urbanopt/geojson/feature.rb

@@ -199,7 +199,7 @@ def merge_site_properties(feature)
         add_props.each do |prop|
           if project.key?(prop[:site]) && project[prop[:site]]
             # property exists in site
-            if !feature[:properties].key?(prop[:feature]) || feature[:properties][prop[:feature]].nil? || feature[:properties][prop[:feature]].empty?
+            if !feature[:properties].key?(prop[:feature]) || feature[:properties][prop[:feature]].nil? || feature[:properties][prop[:feature]].to_s.empty?
               # property does not exist in feature or is nil: add site property (don't overwrite)
               feature[:properties][prop[:feature]] = project[prop[:site]]
             end

lib/urbanopt/geojson/geo_file.rb

@@ -229,7 +229,14 @@ def self.floor_print_from_polygon(polygon, elevation, origin_lat_lon, runner, zo
         return floor_print
       end
 
-      # scale footprint to desired area, keeping the shape
+      ##
+      # Used to scale footprint to desired area while keeping the original shape.
+      #
+      # [Parameters]
+      # * +vertices+ - _Type:Array_ - An array of vertices for the original floorprint 
+      # * +desired_area+ - _Type:String_ - Area to which you want to scale the vertices to
+      # * +runner+ - _Type:String_ - An instance of +Openstudio::Measure::OSRunner+ for the measure run.
+      # 
       def self.adjust_vertices_to_area(vertices, desired_area, runner, eps = 0.1)
         ar = ScaleArea.new(vertices, desired_area, runner, eps)
 

lib/urbanopt/geojson/helper.rb

@@ -62,7 +62,7 @@ def initialize(vertices, desired_area, runner, eps)
         @one  = BigDecimal('1.0')
         @two  = BigDecimal('2.0')
         @ten  = BigDecimal('10.0')
-        @eps  = eps # BigDecimal::new(eps)
+        @eps  = eps
       end
 
       attr_reader :zero
@@ -75,7 +75,10 @@ def initialize(vertices, desired_area, runner, eps)
 
       attr_reader :eps
 
-      # compute value
+      ##
+      # Used to determine new scaled vertices, by iteratively passing in the perimeter distance to
+      # minimise the difference of the new and scaled area. Returns the difference of the new area and desired area.
+      #
       def values(x)
         @new_vertices = URBANopt::GeoJSON::Zoning.divide_floor_print(@vertices, x[0].to_f, @runner, scale = true)
         new_area = OpenStudio.getArea(@new_vertices)

lib/urbanopt/geojson/scale_area.rb

@@ -30,6 +30,6 @@
 
 module URBANopt
   module GeoJSON
-    VERSION = '0.4.0'.freeze
+    VERSION = '0.5.0'.freeze
   end
 end

lib/urbanopt/geojson/version.rb

@@ -402,7 +402,8 @@
         "updated_at": "2017-09-01T21:17:07.518Z",
         "created_at": "2017-09-01T21:16:27.662Z",
         "height": 3,
-        "geometryType": "Polygon"
+        "geometryType": "Polygon",
+        "timesteps_per_hour": 2
       }
     },
     {
@@ -1157,7 +1158,8 @@
         "updated_at": "2017-09-01T21:17:07.484Z",
         "created_at": "2017-09-01T21:16:27.622Z",
         "height": 3,
-        "geometryType": "Polygon"
+        "geometryType": "Polygon", 
+        "timesteps_per_hour": 2
       }
     },
     {

spec/files/nrel_stm_footprints.geojson

@@ -43,6 +43,8 @@
     feature = geofile.get_feature_by_id('59a9ce2b42f7d007c059d306')
     expect(feature.feature_json[:type]).to eq('Feature')
     expect(feature.feature_json[:properties][:name]).to eq('Thermal Test Facility')
+    expect((feature.feature_json[:properties][:timesteps_per_hour]).to_s).to eq('2')
+    expect((feature.feature_json[:properties][:timesteps_per_hour]).to_s).not_to be_empty
   end
 
   it 'gets feature, given a feature_id geojson example' do

spec/urbanopt/geojson/geo_file_spec.rb

@@ -30,6 +30,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec', '~> 3.7'
 
   spec.add_runtime_dependency 'json-schema', '~> 2.8'
-  spec.add_runtime_dependency 'openstudio-extension', '~> 0.2.5'
-  spec.add_runtime_dependency 'urbanopt-core', '~> 0.4.0'
+  spec.add_runtime_dependency 'openstudio-extension', '~> 0.3.1'
+  spec.add_runtime_dependency 'urbanopt-core', '~> 0.5.0'
 end