Method: OSut#poly

Defined in:

lib/osut/utils.rb

#poly(pts = nil, vx = false, uq = false, co = false, tt = false, sq = :no) ⇒ OpenStudio::Point3dVector

Returns an OpenStudio 3D point vector as basis for a valid OpenStudio 3D polygon. In addition to basic OpenStudio polygon tests (e.g. all points sharing the same 3D plane, non-self-intersecting), the method can optionally check for convexity, or ensure uniqueness and/or non-collinearity. Returned vector can also be ‘aligned’, as well as in UpperLeftCorner (ULC), BottomLeftCorner (BLC), in clockwise (or counterclockwise) sequence.

Parameters:

• pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

  3D points

• vx (Bool) (defaults to: false) —

  whether to check for convexity

• uq (Bool) (defaults to: false) —

  whether to ensure uniqueness

• co (Bool) (defaults to: false) —

  whether to ensure non-collinearity

• tt (Bool, OpenStudio::Transformation) (defaults to: false) —

  whether to ‘align’

• sq (:no, :ulc, :blc, :cw) (defaults to: :no) —

  unaltered, ULC, BLC or clockwise sequence

Returns:

• (OpenStudio::Point3dVector) —

  3D points (see logs if empty)

# File 'lib/osut/utils.rb', line 3504

def poly(pts = nil, vx = false, uq = false, co = false, tt = false, sq = :no)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  cl  = OpenStudio::Transformation
  v   = OpenStudio::Point3dVector.new
  vx  = false unless [true, false].include?(vx)
  uq  = false unless [true, false].include?(uq)
  co  = false unless [true, false].include?(co)

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Exit if mismatched/invalid arguments.
  ok1 = tt == true || tt == false || tt.is_a?(cl)
  ok2 = sq == :no  || sq == :ulc  || sq == :blc || sq == :cw
  return invalid("transformation", mth, 5, DBG, v) unless ok1
  return invalid("sequence",       mth, 6, DBG, v) unless ok2

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Minimum 3 points?
  p3 = nonCollinears(pts, 3)
  return empty("polygon (non-collinears < 3)", mth, ERR, v) if p3.size < 3

  # Coplanar?
  pln = OpenStudio::Plane.new(p3)

  pts.each do |pt|
    return empty("plane", mth, ERR, v) unless pln.pointOnPlane(pt)
  end

  t  = OpenStudio::Transformation.alignFace(pts)
  at = (t.inverse * pts).reverse

  if tt.is_a?(cl)
    att = (tt.inverse * pts).reverse

    if same?(at, att)
      a = att
      a = ulc(a).to_a if clockwise?(a)
      t = nil
    else
      t = xyz?(att, :z) ? nil : OpenStudio::Transformation.alignFace(att)
      a = t ? (t.inverse * att).reverse : att
    end
  else
    a = at
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Ensure uniqueness and/or non-collinearity. Preserve original sequence.
  p0 = a.first
  a  = uniques(a).to_a       if uq
  a  = nonCollinears(a).to_a if co
  i0 = a.index { |pt| same?(pt, p0) }
  a  = a.rotate(i0)             unless i0.nil?

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Check for convexity (optional).
  if vx && a.size > 3
    zen = OpenStudio::Point3d.new(0, 0, 1000)

    triads(a).each do |trio|
      p1  = trio[0]
      p2  = trio[1]
      p3  = trio[2]
      v12 = p2 - p1
      v13 = p3 - p1
      x   = (zen - p1).cross(v12)
      return v if x.dot(v13).round(4) > 0
    end
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Alter sequence (optional).
  if tt.is_a?(cl)
    case sq
    when :ulc
      a = t ? to_p3Dv(t * ulc(a.reverse)) : to_p3Dv(ulc(a.reverse))
    when :blc
      a = t ? to_p3Dv(t * blc(a.reverse)) : to_p3Dv(blc(a.reverse))
    when :cw
      a = t ? to_p3Dv(t * a) : to_p3Dv(a)
    else
      a = t ? to_p3Dv(t * a.reverse) : to_p3Dv(a.reverse)
    end
  else
    case sq
    when :ulc
      a = tt ? to_p3Dv(ulc(a.reverse)) : to_p3Dv(t * ulc(a.reverse))
    when :blc
      a = tt ? to_p3Dv(blc(a.reverse)) : to_p3Dv(t * blc(a.reverse))
    when :cw
      a = tt ? to_p3Dv(a) : to_p3Dv(t * a)
    else
      a = tt ? to_p3Dv(a.reverse) : to_p3Dv(t * a.reverse)
    end
  end

  a
end