osut 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04db3007d81904287c0c36c677270a1e1bc5e45375d3b37bbac9068d51c43754
-  data.tar.gz: aafa2bb60bdfaf5b5df03e99aca0cb3181f6270468a761652d2b6d0438037daa
+  metadata.gz: bec97227aeda04a933080c621650e72003d97816d01d2a4716f146e6501b7571
+  data.tar.gz: 82c0d1c211238120894a1bfaffed802b09461f22713957ed5c4a6b9bcb0ef757
 SHA512:
-  metadata.gz: ca60fd088aa106b52bfe15fe4fd352c55a2c79083f95212d7e9e37250f1832b3b94f0dc415e664f5289e837600aad2ab936eff304e9d5cdba0c3a977a56cd7d0
-  data.tar.gz: 8aa96937a55520f99a9c122d0fe98f69ec97d45cbe0cac1e0db7626b48cacee5d65f801eb4a9791e3a6953d64473555b981b3bd9646d7948b6b5c26b2d02e041
+  metadata.gz: e3897a390ef6f90524503ce63ff70a3e5275b1d3abf6148ac7752eb82ec64d5bfa2eedbf56898accdd87c7f394adf435e20b30dec457d3ebe4b3fc92e9130be5
+  data.tar.gz: 51529559490ab5f48e16a696ce657b867fe538ade32d07237b9fffc28e48b6da98905998c7819e019cdf8232fc2e16d8bc9cdb673280c2cc64861289f24370a5

data/.github/workflows/pull_request.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   test_300x:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-22.04
     steps:
     - name: Check out repository
       uses: actions/checkout@v2
@@ -23,7 +23,7 @@ jobs:
         docker exec -t test bundle exec rake
         docker kill test
   test_321x:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-22.04
     steps:
     - name: Check out repository
       uses: actions/checkout@v2
@@ -39,7 +39,7 @@ jobs:
         docker exec -t test bundle exec rake
         docker kill test
   test_330x:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
     - name: Check out repository
       uses: actions/checkout@v2
@@ -55,7 +55,7 @@ jobs:
         docker exec -t test bundle exec rake
         docker kill test
   test_340x:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
     - name: Check out repository
       uses: actions/checkout@v2
@@ -70,3 +70,19 @@ jobs:
         docker exec -t test bundle update
         docker exec -t test bundle exec rake
         docker kill test
+  test_351x:
+    runs-on: ubuntu-22.04
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v2
+    - name: Run Tests
+      run: |
+        echo $(pwd)
+        echo $(ls)
+        docker pull nrel/openstudio:3.5.1
+        docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.5.1
+        docker exec -t test pwd
+        docker exec -t test ls
+        docker exec -t test bundle update
+        docker exec -t test bundle exec rake
+        docker kill test

data/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2022, Denis Bourgeois
+Copyright (c) 2022-2023, Denis Bourgeois
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/lib/osut/utils.rb

@@ -1,6 +1,6 @@
 # BSD 3-Clause License
 #
-# Copyright (c) 2022, Denis Bourgeois
+# Copyright (c) 2022-2023, Denis Bourgeois
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -59,7 +59,7 @@ module OSut
   #       cooling system of sufficient size to maintain temperatures suitable
   #       for HUMAN COMFORT:
   #         - COOLED: cooled by a system >= 10 W/m2
-  #         - HEATED: heated by a system e.g., >= 50 W/m2 in Climate Zone CZ-7
+  #         - HEATED: heated by a system, e.g. >= 50 W/m2 in Climate Zone CZ-7
   #         - INDIRECTLY: heated or cooled via adjacent space(s) provided:
   #             - UA of adjacent surfaces > UA of other surfaces
   #                 or
@@ -89,7 +89,7 @@ module OSut
   # response to the exterior ambient temperature by the provision, either
   # DIRECTLY or INDIRECTLY, of heating or cooling [...]". Although criteria
   # differ (e.g., not sizing-based), the general idea is sufficiently similar
-  # to ASHRAE 90.1 (e.g., heating and/or cooling based, no distinction for
+  # to ASHRAE 90.1 (e.g. heating and/or cooling based, no distinction for
   # INDIRECTLY conditioned spaces like plenums).
   #
   # SEMI-HEATED spaces are also a defined NECB term, but again the distinction
@@ -109,16 +109,16 @@ module OSut
   # processes. As discussed in greater detail elswhere, methods are developed to
   # rely on zoning info and/or "intended" temperature setpoints.
   #
-  # For an OpenStudio model (OSM) in an incomplete or preliminary state, e.g.
-  # holding fully-formed ENCLOSED spaces without thermal zoning information or
-  # setpoint temperatures (early design stage assessments of form, porosity or
-  # envelope), all OSM spaces will be considered CONDITIONED, presuming
-  # setpoints of ~21°C (heating) and ~24°C (cooling).
+  # For an OpenStudio model in an incomplete or preliminary state, e.g. holding
+  # fully-formed ENCLOSED spaces without thermal zoning information or setpoint
+  # temperatures (early design stage assessments of form, porosity or envelope),
+  # all OpenStudio spaces will be considered CONDITIONED, presuming setpoints of
+  # ~21°C (heating) and ~24°C (cooling).
   #
-  # If ANY valid space/zone-specific temperature setpoints are found in the OSM,
-  # spaces/zones WITHOUT valid heating or cooling setpoints are considered as
-  # UNCONDITIONED or UNENCLOSED spaces (like attics), or INDIRECTLY CONDITIONED
-  # spaces (like plenums), see "plenum?" method.
+  # If ANY valid space/zone-specific temperature setpoints are found in the
+  # OpenStudio model, spaces/zones WITHOUT valid heating or cooling setpoints
+  # are considered as UNCONDITIONED or UNENCLOSED spaces (like attics), or
+  # INDIRECTLY CONDITIONED spaces (like plenums), see "plenum?" method.
 
   ##
   # Return min & max values of a schedule (ruleset).
@@ -139,6 +139,7 @@ module OSut
     res = { min: nil, max: nil }
 
     return invalid("sched", mth, 1, DBG, res)     unless sched.respond_to?(NS)
+
     id = sched.nameString
     return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)
 
@@ -186,6 +187,7 @@ module OSut
     res = { min: nil, max: nil }
 
     return invalid("sched", mth, 1, DBG, res)     unless sched.respond_to?(NS)
+
     id = sched.nameString
     return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)
 
@@ -218,6 +220,7 @@ module OSut
     res      = { min: nil, max: nil }
 
     return invalid("sched", mth, 1, DBG, res)     unless sched.respond_to?(NS)
+
     id = sched.nameString
     return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)
 
@@ -231,9 +234,11 @@ module OSut
     end
 
     return empty("'#{id}' values", mth, ERR, res) if vals.empty?
+
     ok = vals.min.is_a?(Numeric) && vals.max.is_a?(Numeric)
     log(ERR, "Non-numeric values in '#{id}' (#{mth})")                 unless ok
     return res                                                         unless ok
+
     res[:min] = vals.min
     res[:max] = vals.max
 
@@ -248,19 +253,21 @@ module OSut
   # @return [Hash] min: (Float), max: (Float)
   # @return [Hash] min: nil, max: nil (if invalid input)
   def scheduleIntervalMinMax(sched = nil)
-    mth      = "OSut::#{__callee__}"
-    cl       = OpenStudio::Model::ScheduleInterval
-    vals     = []
-    prev_str = ""
-    res      = { min: nil, max: nil }
+    mth  = "OSut::#{__callee__}"
+    cl   = OpenStudio::Model::ScheduleInterval
+    vals = []
+    res  = { min: nil, max: nil }
 
     return invalid("sched", mth, 1, DBG, res)     unless sched.respond_to?(NS)
+
     id = sched.nameString
     return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)
+
     vals = sched.timeSeries.values
-    ok = vals.min.is_a?(Numeric) && vals.max.is_a?(Numeric)
+    ok   = vals.min.is_a?(Numeric) && vals.max.is_a?(Numeric)
     log(ERR, "Non-numeric values in '#{id}' (#{mth})")                 unless ok
     return res                                                         unless ok
+
     res[:min] = vals.min
     res[:max] = vals.max
 
@@ -289,6 +296,7 @@ module OSut
     res = { spt: nil, dual: false }
 
     return invalid("zone", mth, 1, DBG, res)     unless zone.respond_to?(NS)
+
     id = zone.nameString
     return mismatch(id, zone, cl, mth, DBG, res) unless zone.is_a?(cl)
 
@@ -369,6 +377,7 @@ module OSut
     end
 
     return res if zone.thermostat.empty?
+
     tstat       = zone.thermostat.get
     res[:spt]   = nil
 
@@ -427,6 +436,7 @@ module OSut
 
           sched.getScheduleWeeks.each do |week|
             next if week.winterDesignDaySchedule.empty?
+
             dd = week.winterDesignDaySchedule.get
             next unless dd.values.empty?
 
@@ -479,6 +489,7 @@ module OSut
     res = { spt: nil, dual: false }
 
     return invalid("zone", mth, 1, DBG, res)     unless zone.respond_to?(NS)
+
     id = zone.nameString
     return mismatch(id, zone, cl, mth, DBG, res) unless zone.is_a?(cl)
 
@@ -546,6 +557,7 @@ module OSut
     end
 
     return res if zone.thermostat.empty?
+
     tstat       = zone.thermostat.get
     res[:spt]   = nil
 
@@ -604,6 +616,7 @@ module OSut
 
           sched.getScheduleWeeks.each do |week|
             next if week.summerDesignDaySchedule.empty?
+
             dd = week.summerDesignDaySchedule.get
             next unless dd.values.empty?
 
@@ -628,7 +641,7 @@ module OSut
     mth = "OSut::#{__callee__}"
     cl  = OpenStudio::Model::Model
 
-    return mismatch("model", model, cl, mth, DBG, false) unless model.is_a?(cl)
+    return mismatch("model", model, cl, mth, DBG, false)  unless model.is_a?(cl)
 
     model.getThermalZones.each do |zone|
       return true if minCoolScheduledSetpoint(zone)[:spt]
@@ -648,12 +661,12 @@ module OSut
     mth = "OSut::#{__callee__}"
     cl  = OpenStudio::Model::Model
 
-    return mismatch("model", model, cl, mth, DBG, false) unless model.is_a?(cl)
+    return mismatch("model", model, cl, mth, DBG, false)  unless model.is_a?(cl)
 
     model.getThermalZones.each do |zone|
-      next if zone.canBePlenum
-      return true unless zone.airLoopHVACs.empty?
-      return true if zone.isPlenum
+      next                                           if zone.canBePlenum
+      return true                                unless zone.airLoopHVACs.empty?
+      return true                                    if zone.isPlenum
     end
 
     false
@@ -678,7 +691,7 @@ module OSut
     # A space may be tagged as a plenum if:
     #
     # CASE A: its zone's "isPlenum" == true (SDK method) for a fully-developed
-    #         OpenStudio model (complete with HVAC air loops);
+    #         OpenStudio model (complete with HVAC air loops); OR
     #
     # CASE B: (IN ABSENCE OF HVAC AIRLOOPS) if it's excluded from a building's
     #         total floor area yet linked to a zone holding an 'inactive'
@@ -691,10 +704,13 @@ module OSut
     cl  = OpenStudio::Model::Space
 
     return invalid("space", mth, 1, DBG, false)     unless space.respond_to?(NS)
+
     id = space.nameString
     return mismatch(id, space, cl, mth, DBG, false) unless space.is_a?(cl)
+
     valid = loops == true || loops == false
     return invalid("loops", mth, 2, DBG, false)     unless valid
+
     valid = setpoints == true || setpoints == false
     return invalid("setpoints", mth, 3, DBG, false) unless valid
 
@@ -714,11 +730,11 @@ module OSut
     unless space.spaceType.empty?
       type = space.spaceType.get
       return type.nameString.downcase == "plenum"                            # C
+    end
 
-      unless type.standardsSpaceType.empty?
-        type = type.standardsSpaceType.get
-        return type.downcase == "plenum"                                     # C
-      end
+    unless type.standardsSpaceType.empty?
+      type = type.standardsSpaceType.get
+      return type.downcase == "plenum"                                       # C
     end
 
     false
@@ -737,8 +753,8 @@ module OSut
     cl     = OpenStudio::Model::Model
     limits = nil
 
-    return mismatch("model", model, cl, mth)    unless model.is_a?(cl)
-    return invalid("availability", avl, 2, mth) unless avl.respond_to?(:to_s)
+    return mismatch("model", model, cl, mth)       unless model.is_a?(cl)
+    return invalid("availability", avl, 2, mth)    unless avl.respond_to?(:to_s)
 
     # Either fetch availability ScheduleTypeLimits object, or create one.
     model.getScheduleTypeLimitss.each do |l|
@@ -751,6 +767,7 @@ module OSut
       next unless l.numericType.get.downcase == "discrete"
       next unless l.unitType.downcase == "availability"
       next unless l.nameString.downcase == "hvac operation scheduletypelimits"
+
       limits = l
     end
 
@@ -769,9 +786,10 @@ module OSut
     off  = OpenStudio::Model::ScheduleDay.new(model, 0)
 
     # Seasonal availability start/end dates.
-    year = model.yearDescription
-    return empty("yearDescription", mth, ERR) if year.empty?
-    year = year.get
+    year  = model.yearDescription
+    return  empty("yearDescription", mth, ERR) if year.empty?
+
+    year  = year.get
     may01 = year.makeDate(OpenStudio::MonthOfYear.new("May"),  1)
     oct31 = year.makeDate(OpenStudio::MonthOfYear.new("Oct"), 31)
 
@@ -850,9 +868,11 @@ module OSut
     ok = schedule.setScheduleTypeLimits(limits)
     log(ERR, "'#{nom}': Can't set schedule type limits (#{mth})")      unless ok
     return nil                                                         unless ok
+
     ok = schedule.defaultDaySchedule.addValue(time, val)
     log(ERR, "'#{nom}': Can't set default day schedule (#{mth})")      unless ok
     return nil                                                         unless ok
+
     schedule.defaultDaySchedule.setName(dft)
 
     unless tag.empty?
@@ -861,12 +881,15 @@ module OSut
       ok = rule.setStartDate(may01)
       log(ERR, "'#{tag}': Can't set start date (#{mth})")              unless ok
       return nil                                                       unless ok
+
       ok = rule.setEndDate(oct31)
       log(ERR, "'#{tag}': Can't set end date (#{mth})")                unless ok
       return nil                                                       unless ok
+
       ok = rule.setApplyAllDays(true)
       log(ERR, "'#{tag}': Can't apply to all days (#{mth})")           unless ok
       return nil                                                       unless ok
+
       rule.daySchedule.setName(day)
     end
 
@@ -874,7 +897,7 @@ module OSut
   end
 
   ##
-  # Validate if default construction set holds a base ground construction.
+  # Validate if default construction set holds a base construction.
   #
   # @param set [OpenStudio::Model::DefaultConstructionSet] a default set
   # @param bse [OpensStudio::Model::ConstructionBase] a construction base
@@ -890,17 +913,23 @@ module OSut
     cl2 = OpenStudio::Model::ConstructionBase
 
     return invalid("set", mth, 1, DBG, false)         unless set.respond_to?(NS)
+
     id = set.nameString
     return mismatch(id, set, cl1, mth, DBG, false)    unless set.is_a?(cl1)
     return invalid("base", mth, 2, DBG, false)        unless bse.respond_to?(NS)
+
     id = bse.nameString
     return mismatch(id, bse, cl2, mth, DBG, false)    unless bse.is_a?(cl2)
+
     valid = gr == true || gr == false
     return invalid("ground", mth, 3, DBG, false)      unless valid
+
     valid = ex == true || ex == false
     return invalid("exterior", mth, 4, DBG, false)    unless valid
+
     valid = typ.respond_to?(:to_s)
     return invalid("surface typ", mth, 4, DBG, false) unless valid
+
     type = typ.to_s.downcase
     valid = type == "floor" || type == "wall" || type == "roofceiling"
     return invalid("surface type", mth, 5, DBG, false) unless valid
@@ -957,17 +986,20 @@ module OSut
     cl1 = OpenStudio::Model::Model
     cl2 = OpenStudio::Model::Surface
 
-    return mismatch("model", model, cl1, mth) unless model.is_a?(cl1)
-    return invalid("s", mth, 2)               unless s.respond_to?(NS)
-    id = s.nameString
-    return mismatch(id, s, cl2, mth)          unless s.is_a?(cl2)
+    return mismatch("model", model, cl1, mth)           unless model.is_a?(cl1)
+    return invalid("s", mth, 2)                         unless s.respond_to?(NS)
+
+    id   = s.nameString
+    return mismatch(id, s, cl2, mth)                    unless s.is_a?(cl2)
 
     ok = s.isConstructionDefaulted
     log(ERR, "'#{id}' construction not defaulted (#{mth})")            unless ok
     return nil                                                         unless ok
-    return empty("'#{id}' construction", mth, ERR) if s.construction.empty?
+    return empty("'#{id}' construction", mth, ERR)      if s.construction.empty?
+
     base = s.construction.get
-    return empty("'#{id}' space", mth, ERR) if s.space.empty?
+    return empty("'#{id}' space", mth, ERR)             if s.space.empty?
+
     space = s.space.get
     type = s.surfaceType
     ground = false
@@ -981,7 +1013,7 @@ module OSut
 
     unless space.defaultConstructionSet.empty?
       set = space.defaultConstructionSet.get
-      return set if holdsConstruction?(set, base, ground, exterior, type)
+      return set        if holdsConstruction?(set, base, ground, exterior, type)
     end
 
     unless space.spaceType.empty?
@@ -989,7 +1021,7 @@ module OSut
 
       unless spacetype.defaultConstructionSet.empty?
         set = spacetype.defaultConstructionSet.get
-        return set if holdsConstruction?(set, base, ground, exterior, type)
+        return set      if holdsConstruction?(set, base, ground, exterior, type)
       end
     end
 
@@ -998,7 +1030,7 @@ module OSut
 
       unless story.defaultConstructionSet.empty?
         set = story.defaultConstructionSet.get
-        return set if holdsConstruction?(set, base, ground, exterior, type)
+        return set      if holdsConstruction?(set, base, ground, exterior, type)
       end
     end
 
@@ -1006,7 +1038,7 @@ module OSut
 
     unless building.defaultConstructionSet.empty?
       set = building.defaultConstructionSet.get
-      return set if holdsConstruction?(set, base, ground, exterior, type)
+      return set        if holdsConstruction?(set, base, ground, exterior, type)
     end
 
     nil
@@ -1036,19 +1068,21 @@ module OSut
   #
   # @param lc [OpenStudio::LayeredConstruction] a layered construction
   #
-  # @return [Double] total layered construction thickness
-  # @return [Double] 0 if invalid input
+  # @return [Float] total layered construction thickness
+  # @return [Float] 0 if invalid input
   def thickness(lc = nil)
     mth = "OSut::#{__callee__}"
     cl  = OpenStudio::Model::LayeredConstruction
 
-    return invalid("lc", mth, 1, DBG, 0.0)     unless lc.respond_to?(NS)
+    return invalid("lc", mth, 1, DBG, 0.0)             unless lc.respond_to?(NS)
+
     id = lc.nameString
-    return mismatch(id, lc, cl, mth, DBG, 0.0) unless lc.is_a?(cl)
+    return mismatch(id, lc, cl, mth, DBG, 0.0)         unless lc.is_a?(cl)
 
     ok = standardOpaqueLayers?(lc)
     log(ERR, "'#{id}' holds non-StandardOpaqueMaterial(s) (#{mth})")   unless ok
     return 0.0                                                         unless ok
+
     thickness = 0.0
     lc.layers.each { |m| thickness += m.thickness }
 
@@ -1113,11 +1147,14 @@ module OSut
     cl2 = Numeric
 
     return invalid("lc", mth, 1, DBG, 0.0)             unless lc.respond_to?(NS)
+
     id = lc.nameString
+
     return mismatch(id, lc, cl1, mth, DBG, 0.0)        unless lc.is_a?(cl1)
     return mismatch("film", film, cl2, mth, DBG, 0.0)  unless film.is_a?(cl2)
     return mismatch("temp K", t, cl2, mth, DBG, 0.0)   unless t.is_a?(cl2)
-    t += 273.0                                                         # °C to K
+
+    t += 273.0                                             # °C to K
     return negative("temp K", mth, DBG, 0.0)               if t < 0
     return negative("film", mth, DBG, 0.0)                 if film < 0
 
@@ -1127,6 +1164,7 @@ module OSut
       # Fenestration materials first (ignoring shades, screens, etc.)
       empty = m.to_SimpleGlazing.empty?
       return 1 / m.to_SimpleGlazing.get.uFactor                     unless empty
+
       empty = m.to_StandardGlazing.empty?
       rsi += m.to_StandardGlazing.get.thermalResistance             unless empty
       empty = m.to_RefractionExtinctionGlazing.empty?
@@ -1166,9 +1204,10 @@ module OSut
     res = { index: nil, type: nil, r: 0.0 }
     i   = 0                                                           # iterator
 
-    return invalid("lc", mth, 1, DBG, res)      unless lc.respond_to?(NS)
-    id = lc.nameString
-    return mismatch(id, lc, cl1, mth, DBG, res) unless lc.is_a?(cl)
+    return invalid("lc", mth, 1, DBG, res)             unless lc.respond_to?(NS)
+
+    id   = lc.nameString
+    return mismatch(id, lc, cl1, mth, DBG, res)        unless lc.is_a?(cl)
 
     lc.layers.each do |m|
       unless m.to_MasslessOpaqueMaterial.empty?
@@ -1178,9 +1217,9 @@ module OSut
           i += 1
           next
         else
-          res[:r]     = m.thermalResistance
+          res[:r    ] = m.thermalResistance
           res[:index] = i
-          res[:type]  = :massless
+          res[:type ] = :massless
         end
       end
 
@@ -1193,9 +1232,9 @@ module OSut
           i += 1
           next
         else
-          res[:r]     = d / k
+          res[:r    ] = d / k
           res[:index] = i
-          res[:type]  = :standard
+          res[:type ] = :standard
         end
       end
 
@@ -1221,6 +1260,7 @@ module OSut
 
     return mismatch("model", model, cl1, mth, DBG, res) unless model.is_a?(cl1)
     return invalid("group", mth, 2, DBG, res) unless group.respond_to?(NS)
+
     id = group.nameString
     return mismatch(id, group, cl2, mth, DBG, res) unless group.is_a?(cl2)
 
@@ -1230,6 +1270,28 @@ module OSut
     res
   end
 
+  ##
+  # Return a scalar product of an OpenStudio Vector3d.
+  #
+  # @param v [OpenStudio::Vector3d] a vector
+  # @param m [Float] a scalar
+  #
+  # @return [OpenStudio::Vector3d] modified vector
+  # @return [OpenStudio::Vector3d] provided (or empty) vector if invalid input
+  def scalar(v = OpenStudio::Vector3d.new(0,0,0), m = 0)
+    mth = "OSut::#{__callee__}"
+    cl1 = OpenStudio::Vector3d
+    cl2 = Numeric
+
+    return mismatch("vector", v, cl1, mth, DBG, v) unless v.is_a?(cl1)
+    return mismatch("x",    v.x, cl2, mth, DBG, v) unless v.x.respond_to?(:to_f)
+    return mismatch("y",    v.y, cl2, mth, DBG, v) unless v.y.respond_to?(:to_f)
+    return mismatch("z",    v.z, cl2, mth, DBG, v) unless v.z.respond_to?(:to_f)
+    return mismatch("m",      m, cl2, mth, DBG, v) unless m.respond_to?(:to_f)
+
+    OpenStudio::Vector3d.new(m * v.x, m * v.y, m * v.z)
+  end
+
   ##
   # Flatten OpenStudio 3D points vs Z-axis (Z=0).
   #
@@ -1243,8 +1305,9 @@ module OSut
     v   = OpenStudio::Point3dVector.new
 
     valid = pts.is_a?(cl1) || pts.is_a?(Array)
-    return mismatch("points", pts, cl1, mth, DBG, v)     unless valid
-    pts.each { |pt| mismatch("pt", pt, cl2, mth, ERR, v) unless pt.is_a?(cl2) }
+    return mismatch("points", pts, cl1, mth, DBG, v)      unless valid
+
+    pts.each { |pt| mismatch("pt", pt, cl2, mth, ERR, v)  unless pt.is_a?(cl2) }
     pts.each { |pt| v << OpenStudio::Point3d.new(pt.x, pt.y, 0) }
 
     v
@@ -1268,40 +1331,53 @@ module OSut
 
     return invalid("id1", mth, 3, DBG, a) unless id1.respond_to?(:to_s)
     return invalid("id2", mth, 4, DBG, a) unless id2.respond_to?(:to_s)
+
     i1  = id1.to_s
     i2  = id2.to_s
     i1  = "poly1" if i1.empty?
     i2  = "poly2" if i2.empty?
+
     valid1 = p1.is_a?(cl1) || p1.is_a?(Array)
     valid2 = p2.is_a?(cl1) || p2.is_a?(Array)
+
     return mismatch(i1, p1, cl1, mth, DBG, a) unless valid1
     return mismatch(i2, p2, cl1, mth, DBG, a) unless valid2
-    return empty(i1, mth, ERR, a) if p1.empty?
-    return empty(i2, mth, ERR, a) if p2.empty?
+    return empty(i1, mth, ERR, a)                 if p1.empty?
+    return empty(i2, mth, ERR, a)                 if p2.empty?
+
     p1.each { |v| return mismatch(i1, v, cl2, mth, ERR, a) unless v.is_a?(cl2) }
     p2.each { |v| return mismatch(i2, v, cl2, mth, ERR, a) unless v.is_a?(cl2) }
 
-    ft = OpenStudio::Transformation::alignFace(p1).inverse
-    ft_p1 = flatZ( (ft * p1).reverse )
-    return false if ft_p1.empty?
-    area1 = OpenStudio::getArea(ft_p1)
-    return empty("#{i1} area", mth, ERR, a) if area1.empty?
+    # XY-plane transformation matrix ... needs to be clockwise for boost.
+    ft    = OpenStudio::Transformation.alignFace(p1)
+    ft_p1 = flatZ( (ft.inverse * p1)         )
+    return  false                                                if ft_p1.empty?
+
+    cw    = OpenStudio.pointInPolygon(ft_p1.first, ft_p1, TOL)
+    ft_p1 = flatZ( (ft.inverse * p1).reverse )               unless cw
+    ft_p2 = flatZ( (ft.inverse * p2).reverse )               unless cw
+    ft_p2 = flatZ( (ft.inverse * p2)         )                   if cw
+    return  false                                                if ft_p2.empty?
+
+    area1 = OpenStudio.getArea(ft_p1)
+    area2 = OpenStudio.getArea(ft_p2)
+    return  empty("#{i1} area", mth, ERR, a)                     if area1.empty?
+    return  empty("#{i2} area", mth, ERR, a)                     if area2.empty?
+
     area1 = area1.get
-    ft_p2 = flatZ( (ft * p2).reverse )
-    return false if ft_p2.empty?
-    area2 = OpenStudio::getArea(ft_p2)
-    return empty("#{i2} area", mth, ERR, a) if area2.empty?
     area2 = area2.get
-    union = OpenStudio::join(ft_p1, ft_p2, TOL2)
-    return false if union.empty?
+    union = OpenStudio.join(ft_p1, ft_p2, TOL2)
+    return  false                                                if union.empty?
+
     union = union.get
-    area = OpenStudio::getArea(union)
-    return empty("#{i1}:#{i2} union area", mth, ERR, a) if area.empty?
+    area  = OpenStudio.getArea(union)
+    return  empty("#{i1}:#{i2} union area", mth, ERR, a)         if area.empty?
+
     area = area.get
 
-    return false if area < TOL
-    return true if (area - area2).abs < TOL
-    return false if (area - area2).abs > TOL
+    return false                                     if area < TOL
+    return true                                      if (area - area2).abs < TOL
+    return false                                     if (area - area2).abs > TOL
 
     true
   end
@@ -1324,42 +1400,290 @@ module OSut
 
     return invalid("id1", mth, 3, DBG, a) unless id1.respond_to?(:to_s)
     return invalid("id2", mth, 4, DBG, a) unless id2.respond_to?(:to_s)
+
     i1 = id1.to_s
     i2 = id2.to_s
     i1 = "poly1" if i1.empty?
     i2 = "poly2" if i2.empty?
+
     valid1 = p1.is_a?(cl1) || p1.is_a?(Array)
     valid2 = p2.is_a?(cl1) || p2.is_a?(Array)
+
     return mismatch(i1, p1, cl1, mth, DBG, a) unless valid1
     return mismatch(i2, p2, cl1, mth, DBG, a) unless valid2
-    return empty(i1, mth, ERR, a) if p1.empty?
-    return empty(i2, mth, ERR, a) if p2.empty?
+    return empty(i1, mth, ERR, a)                 if p1.empty?
+    return empty(i2, mth, ERR, a)                 if p2.empty?
+
     p1.each { |v| return mismatch(i1, v, cl2, mth, ERR, a) unless v.is_a?(cl2) }
     p2.each { |v| return mismatch(i2, v, cl2, mth, ERR, a) unless v.is_a?(cl2) }
 
-    ft = OpenStudio::Transformation::alignFace(p1).inverse
-    ft_p1 = flatZ( (ft * p1).reverse )
-    return false if ft_p1.empty?
-    area1 = OpenStudio::getArea(ft_p1)
-    return empty("#{i1} area", mth, ERR, a) if area1.empty?
+    # XY-plane transformation matrix ... needs to be clockwise for boost.
+    ft    = OpenStudio::Transformation.alignFace(p1)
+    ft_p1 = flatZ( (ft.inverse * p1)         )
+    ft_p2 = flatZ( (ft.inverse * p2)         )
+    return  false                                                if ft_p1.empty?
+    return  false                                                if ft_p2.empty?
+
+    cw    = OpenStudio.pointInPolygon(ft_p1.first, ft_p1, TOL)
+    ft_p1 = flatZ( (ft.inverse * p1).reverse )               unless cw
+    ft_p2 = flatZ( (ft.inverse * p2).reverse )               unless cw
+    return  false                                                if ft_p1.empty?
+    return  false                                                if ft_p2.empty?
+
+    area1 = OpenStudio.getArea(ft_p1)
+    area2 = OpenStudio.getArea(ft_p2)
+    return  empty("#{i1} area", mth, ERR, a)                     if area1.empty?
+    return  empty("#{i2} area", mth, ERR, a)                     if area2.empty?
+
     area1 = area1.get
-    ft_p2 = flatZ( (ft * p2).reverse )
-    return false if ft_p2.empty?
-    area2 = OpenStudio::getArea(ft_p2)
-    return empty("#{i2} area", mth, ERR, a) if area2.empty?
     area2 = area2.get
-    union = OpenStudio::join(ft_p1, ft_p2, TOL2)
-    return false if union.empty?
+    union = OpenStudio.join(ft_p1, ft_p2, TOL2)
+    return  false                                                if union.empty?
+
     union = union.get
-    area = OpenStudio::getArea(union)
-    return empty("#{i1}:#{i2} union area", mth, ERR, a) if area.empty?
-    area = area.get
+    area  = OpenStudio.getArea(union)
+    return empty("#{i1}:#{i2} union area", mth, ERR, a)          if area.empty?
 
-    return false if area < TOL
+    area = area.get
+    return false                                                 if area < TOL
 
     true
   end
 
+  ##
+  # Generate offset vertices (by width) for a 3- or 4-sided, convex polygon.
+  #
+  # @param p1 [OpenStudio::Point3dVector] OpenStudio Point3D vector/array
+  # @param w [Float] offset width (min: 0.0254m)
+  # @param v [Integer] OpenStudio SDK version, eg '321' for 'v3.2.1' (optional)
+  #
+  # @return [OpenStudio::Point3dVector] offset points if successful
+  # @return [OpenStudio::Point3dVector] original points if invalid input
+  def offset(p1 = [], w = 0, v = 0)
+    mth   = "TBD::#{__callee__}"
+    cl    = OpenStudio::Point3d
+    vrsn  = OpenStudio.openStudioVersion.split(".").map(&:to_i).join.to_i
+
+    valid = p1.is_a?(OpenStudio::Point3dVector) || p1.is_a?(Array)
+    return  mismatch("pts", p1, cl1, mth, DBG, p1)  unless valid
+    return  empty("pts", mth, ERR, p1)                  if p1.empty?
+
+    valid = p1.size == 3 || p1.size == 4
+    iv    = true if p1.size == 4
+    return  invalid("pts", mth, 1, DBG, p1)         unless valid
+    return  invalid("width", mth, 2, DBG, p1)       unless w.respond_to?(:to_f)
+
+    w     = w.to_f
+    return  p1                                          if w < 0.0254
+
+    v     = v.to_i                                      if v.respond_to?(:to_i)
+    v     = 0                                       unless v.respond_to?(:to_i)
+    v     = vrsn                                        if v.zero?
+
+    p1.each { |x| return mismatch("p", x, cl, mth, ERR, p1) unless x.is_a?(cl) }
+
+    unless v < 340
+      # XY-plane transformation matrix ... needs to be clockwise for boost.
+      ft     = OpenStudio::Transformation::alignFace(p1)
+      ft_pts = flatZ( (ft.inverse * p1) )
+      return   p1                                       if ft_pts.empty?
+
+      cw     = OpenStudio::pointInPolygon(ft_pts.first, ft_pts, TOL)
+      ft_pts = flatZ( (ft.inverse * p1).reverse )   unless cw
+      offset = OpenStudio.buffer(ft_pts, w, TOL)
+      return   p1                                       if offset.empty?
+
+      offset = offset.get
+      offset =  ft * offset                             if cw
+      offset = (ft * offset).reverse                unless cw
+
+      pz = OpenStudio::Point3dVector.new
+      offset.each { |o| pz << OpenStudio::Point3d.new(o.x, o.y, o.z ) }
+      
+      return pz
+    else                                                  # brute force approach
+      pz     = {}
+      pz[:A] = {}
+      pz[:B] = {}
+      pz[:C] = {}
+      pz[:D] = {}                                                          if iv
+
+      pz[:A][:p] = OpenStudio::Point3d.new(p1[0].x, p1[0].y, p1[0].z)
+      pz[:B][:p] = OpenStudio::Point3d.new(p1[1].x, p1[1].y, p1[1].z)
+      pz[:C][:p] = OpenStudio::Point3d.new(p1[2].x, p1[2].y, p1[2].z)
+      pz[:D][:p] = OpenStudio::Point3d.new(p1[3].x, p1[3].y, p1[3].z)      if iv
+
+      pzAp = pz[:A][:p]
+      pzBp = pz[:B][:p]
+      pzCp = pz[:C][:p]
+      pzDp = pz[:D][:p]                                                    if iv
+
+      # Generate vector pairs, from next point & from previous point.
+      # :f_n : "from next"
+      # :f_p : "from previous"
+      #
+      #
+      #
+      #
+      #
+      #
+      #             A <---------- B
+      #              ^
+      #               \
+      #                \
+      #                 C (or D)
+      #
+      pz[:A][:f_n] = pzAp - pzBp
+      pz[:A][:f_p] = pzAp - pzCp                                       unless iv
+      pz[:A][:f_p] = pzAp - pzDp                                           if iv
+
+      pz[:B][:f_n] = pzBp - pzCp
+      pz[:B][:f_p] = pzBp - pzAp
+
+      pz[:C][:f_n] = pzCp - pzAp                                       unless iv
+      pz[:C][:f_n] = pzCp - pzDp                                           if iv
+      pz[:C][:f_p] = pzCp - pzBp
+
+      pz[:D][:f_n] = pzDp - pzAp                                           if iv
+      pz[:D][:f_p] = pzDp - pzCp                                           if iv
+
+      # Generate 3D plane from vectors.
+      #
+      #
+      #             |  <<< 3D plane ... from point A, with normal B>A
+      #             |
+      #             |
+      #             |
+      # <---------- A <---------- B
+      #             |\
+      #             | \
+      #             |  \
+      #             |   C (or D)
+      #
+      pz[:A][:pl_f_n] = OpenStudio::Plane.new(pzAp, pz[:A][:f_n])
+      pz[:A][:pl_f_p] = OpenStudio::Plane.new(pzAp, pz[:A][:f_p])
+
+      pz[:B][:pl_f_n] = OpenStudio::Plane.new(pzBp, pz[:B][:f_n])
+      pz[:B][:pl_f_p] = OpenStudio::Plane.new(pzBp, pz[:B][:f_p])
+
+      pz[:C][:pl_f_n] = OpenStudio::Plane.new(pzCp, pz[:C][:f_n])
+      pz[:C][:pl_f_p] = OpenStudio::Plane.new(pzCp, pz[:C][:f_p])
+
+      pz[:D][:pl_f_n] = OpenStudio::Plane.new(pzDp, pz[:D][:f_n])          if iv
+      pz[:D][:pl_f_p] = OpenStudio::Plane.new(pzDp, pz[:D][:f_p])          if iv
+
+      # Project an extended point (pC) unto 3D plane.
+      #
+      #             pC   <<< projected unto extended B>A 3D plane
+      #        eC   |
+      #          \  |
+      #           \ |
+      #            \|
+      # <---------- A <---------- B
+      #             |\
+      #             | \
+      #             |  \
+      #             |   C (or D)
+      #
+      pz[:A][:p_n_pl] = pz[:A][:pl_f_n].project(pz[:A][:p] + pz[:A][:f_p])
+      pz[:A][:n_p_pl] = pz[:A][:pl_f_p].project(pz[:A][:p] + pz[:A][:f_n])
+
+      pz[:B][:p_n_pl] = pz[:B][:pl_f_n].project(pz[:B][:p] + pz[:B][:f_p])
+      pz[:B][:n_p_pl] = pz[:B][:pl_f_p].project(pz[:B][:p] + pz[:B][:f_n])
+
+      pz[:C][:p_n_pl] = pz[:C][:pl_f_n].project(pz[:C][:p] + pz[:C][:f_p])
+      pz[:C][:n_p_pl] = pz[:C][:pl_f_p].project(pz[:C][:p] + pz[:C][:f_n])
+
+      pz[:D][:p_n_pl] = pz[:D][:pl_f_n].project(pz[:D][:p] + pz[:D][:f_p]) if iv
+      pz[:D][:n_p_pl] = pz[:D][:pl_f_p].project(pz[:D][:p] + pz[:D][:f_n]) if iv
+
+      # Generate vector from point (e.g. A) to projected extended point (pC).
+      #
+      #             pC
+      #        eC   ^
+      #          \  |
+      #           \ |
+      #            \|
+      # <---------- A <---------- B
+      #             |\
+      #             | \
+      #             |  \
+      #             |   C (or D)
+      #
+      pz[:A][:n_p_n_pl] = pz[:A][:p_n_pl] - pzAp
+      pz[:A][:n_n_p_pl] = pz[:A][:n_p_pl] - pzAp
+
+      pz[:B][:n_p_n_pl] = pz[:B][:p_n_pl] - pzBp
+      pz[:B][:n_n_p_pl] = pz[:B][:n_p_pl] - pzBp
+
+      pz[:C][:n_p_n_pl] = pz[:C][:p_n_pl] - pzCp
+      pz[:C][:n_n_p_pl] = pz[:C][:n_p_pl] - pzCp
+
+      pz[:D][:n_p_n_pl] = pz[:D][:p_n_pl] - pzDp                           if iv
+      pz[:D][:n_n_p_pl] = pz[:D][:n_p_pl] - pzDp                           if iv
+
+      # Fetch angle between both extended vectors (A>pC & A>pB),
+      # ... then normalize (Cn).
+      #
+      #             pC
+      #        eC   ^
+      #          \  |
+      #           \ Cn
+      #            \|
+      # <---------- A <---------- B
+      #             |\
+      #             | \
+      #             |  \
+      #             |   C (or D)
+      #
+      a1 = OpenStudio.getAngle(pz[:A][:n_p_n_pl], pz[:A][:n_n_p_pl])
+      a2 = OpenStudio.getAngle(pz[:B][:n_p_n_pl], pz[:B][:n_n_p_pl])
+      a3 = OpenStudio.getAngle(pz[:C][:n_p_n_pl], pz[:C][:n_n_p_pl])
+      a4 = OpenStudio.getAngle(pz[:D][:n_p_n_pl], pz[:D][:n_n_p_pl])       if iv
+
+      # Generate new 3D points A', B', C' (and D') ... zigzag.
+      #
+      #
+      #
+      #
+      #     A' ---------------------- B'
+      #      \
+      #       \      A <---------- B
+      #        \      \
+      #         \      \
+      #          \      \
+      #           C'      C
+      pz[:A][:f_n].normalize
+      pz[:A][:n_p_n_pl].normalize
+      pzAp = pzAp + scalar(pz[:A][:n_p_n_pl], w)
+      pzAp = pzAp + scalar(pz[:A][:f_n], w * Math.tan(a1/2))
+
+      pz[:B][:f_n].normalize
+      pz[:B][:n_p_n_pl].normalize
+      pzBp = pzBp + scalar(pz[:B][:n_p_n_pl], w)
+      pzBp = pzBp + scalar(pz[:B][:f_n], w * Math.tan(a2/2))
+
+      pz[:C][:f_n].normalize
+      pz[:C][:n_p_n_pl].normalize
+      pzCp = pzCp + scalar(pz[:C][:n_p_n_pl], w)
+      pzCp = pzCp + scalar(pz[:C][:f_n], w * Math.tan(a3/2))
+
+      pz[:D][:f_n].normalize                                               if iv
+      pz[:D][:n_p_n_pl].normalize                                          if iv
+      pzDp = pzDp + scalar(pz[:D][:n_p_n_pl], w)                           if iv
+      pzDp = pzDp + scalar(pz[:D][:f_n], w * Math.tan(a4/2))               if iv
+
+      # Re-convert to OpenStudio 3D points.
+      vec  = OpenStudio::Point3dVector.new
+      vec << OpenStudio::Point3d.new(pzAp.x, pzAp.y, pzAp.z)
+      vec << OpenStudio::Point3d.new(pzBp.x, pzBp.y, pzBp.z)
+      vec << OpenStudio::Point3d.new(pzCp.x, pzCp.y, pzCp.z)
+      vec << OpenStudio::Point3d.new(pzDp.x, pzDp.y, pzDp.z)               if iv
+
+      return vec
+    end
+  end
+
   ##
   # Callback when other modules extend OSlg
   #

data/lib/osut/version.rb

@@ -1,6 +1,6 @@
 # BSD 3-Clause License
 #
-# Copyright (c) 2022, Denis Bourgeois
+# Copyright (c) 2022-2023, Denis Bourgeois
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -29,5 +29,5 @@
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 module OSut
-  VERSION = "0.2.6".freeze
+  VERSION = "0.2.8".freeze
 end

data/lib/osut.rb

@@ -1,6 +1,6 @@
 # BSD 3-Clause License
 #
-# Copyright (c) 2022, Denis Bourgeois
+# Copyright (c) 2022-2023, Denis Bourgeois
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: osut
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Denis Bourgeois
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-15 00:00:00.000000000 Z
+date: 2023-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oslg
@@ -90,7 +90,7 @@ licenses:
 - BSD-3-Clause
 metadata:
   homepage_uri: https://github.com/rd2/osut
-  source_code_uri: https://github.com/rd2/osut/tree/v0.2.6
+  source_code_uri: https://github.com/rd2/osut/tree/v0.2.8
   bug_tracker_uri: https://github.com/rd2/osut/issues
 post_install_message:
 rdoc_options: []