
  Overhaul of qpik's SimpleRays plugin by Dan Rathbun, 2013-01-03
  
  MISC:
  
  a) Formalized versioning and added version entries to doc header.
      (The previous 7 versions are numnered 0.1.0 thru 0.7.0)
      
  b) This overhaul will be version 1.0.0


# ======================================================================

  GENERAL FIXES & CHANGES TO AVOID BAD CODING STYLES

  
  1) Use of Ruby keywords or common method identifiers:
  
    ~ Use of "method" as local var replaced with "meth"

    
  2) Use of local varname same as the method name it is within.
      (We try not to make the Ruby interpreter do more work by
        having to determine whether we are making a recursive call,
        or making an assignment to a local ariable. Also bad style.)
  
    ~ local var names replaced with shorter nicknames

    
  3) Use of do keyword with for .. in statements.
    (Although most Ruby books say this is allowed, it is uneeded because
      the "for" keyword is the block opener. The Ruby interpreter often
      in older versions, raise SyntaxError when "do" is used this way.
      The interpreter expects an "end" to match the "for" and another
      "end" to match the "do".)
  
    ~ removed all unneeded "do" keywords from "for".."in" statements.

    
  4) ALL code wrapped within Qpik::SimpleRays namespace !!!

    ~ defining global methods in the ObjectSpace is a NO-NO !
      (Everyone else's classes and modules inherit them!)

      
  5) Eliminated all use of $ global variables !
  
    ~ There is NEVER a good reason to clutter the global ObjectSpace
      with variables that a only specific plugin uses!
      (Instead, wrap code in a module namespace hierarchy and use
        class / module @@ vars, or constants within your namespaces.)


  6) Where possible, each() iterators replaced with faster for .. in.
  
  
  7) Indentation:
  
    ~ Weird odd indents (ie, 1 space, 3 space, etc.,) replaced with
      conventional Ruby 2 space indents.
      
    ~ Removed ALL outdenting. (Bad Style, makes blocks hard to read.)

    
  8) Plugin is within it's own sub-directory of "Qpik" directory.


# ======================================================================

  FIXED RUBY VERSION COMPATIBILITY ISSUES


  a) Parenthesis ()
  
    ~ Added parentheses around argument lists where appropriate, and
      definately when argument list contains more than one parameter.
      (Readability and future Ruby version Compatibility.)


  b) id() vs object_id()
  
    ~ id() is deprecated and outputs a warning to $stdout on each call.
      replaced all uses with object_id()


# ======================================================================

  FIXED ILLEGAL ADDITION OF CUSTOM METHODS TO API & BASE CLASSES

  # --------------------------------------------------------------------

  class Array methods:

  exposure()  : moved into plugin module
              : xyz_array is now passed in as 1st argument
  
  frontside() : renamed to frontside_vector_array()
              : moved into plugin module
              : vector_array is passed in as 2nd argument
  
  get_bounds_2d() : moved into plugin module
                  : array_of_xy_arrays is now passed in
                  : internal min & max calculations have been
                    replaced with min() & max() from Enumerable

  get_point2d()   : moved into plugin module
                  : point is passed a 1st argument
                  
  get_point3d()   : moved into plugin module
                  : point is passed a 1st argument
                  
  move()  : removed (was not used, but if needed later can be
              replaced with API bulit-in Array.offset method)
  
  move!() : replaced with API bulit-in Array.offset! method
  
  round_to() : replaced with: Array.map {|n| round_f(n,x) }
                (it was only called once

  scale() : replaced with an Array scaling transformation
          : used in only in Bitmap#blur()
  
  to_i()  : renamed intized_array()
          : moved into Bitmap class
          : xyz_array is passed in as argument
          : called only by Bitmap#blur()
          
  # --------------------------------------------------------------------

  class Bitmap  :  moved within the Qpik::SimpleRays namespace
                   (The global ObjectSpace is where Ruby defines it's
                    classes, that EVERYONE will use. Custom classes
                    should ALWAYS be defined within your namespace.)
  
  blur() :
    !! Bad style: making assignments within boolean expressions !!
    
  write() : wrapped file handling in begin .. rescue .. ensure block.
  
  to_byte() : renamed --> lbo_dword() as it does not output a byte.
  Outputs a 4-byte (32bit) DWORD String, in little-endian byte order.
  :
  : !!!! this method might be replaced with:  [n].pack("V")
  
  from_byte() : NOT USED (commented out)

  # --------------------------------------------------------------------

  class Float methods:
  
  round_to() : moved into plugin module
             : renamed round_f()
             : number is passed in as 1st argument
  
  # --------------------------------------------------------------------

  class Numeric methods:
  
  rgb() : moved into plugin module
        : number is passed in as 1st argument

  # --------------------------------------------------------------------

  class Sketchup::Face methods:
  
  lightmap() : moved into plugin module
             : face is passed in as 1st argument
  
  # --------------------------------------------------------------------
  
  class Sketchup::Model methods:
  
  raytest2() : removed (was not used)
  
  to_a() : removed (was empty, and not used.)

  
# ======================================================================

  FIXED PLUGIN METHODS:
  
    + Menu command is now a UI::Command object with a validation proc
        that grays the menu item if the selection is empty.
      
    ~ Creation of command and context menu handler wrapped within a
        unless file_loaded?() block.
  
  # --------------------------------------------------------------------
  
    ALL these methods were global, now defined within plugin module.

  # --------------------------------------------------------------------

  raytest()
  
    + short-circuit return nil if params from inputbox is false
        (ie, the user cancelled the inputbox.)
    ~ The user's previous working Dir is remembered in @@prevDir, and
        restored within an ensure clause.
    + Temporary image files and directories are cleaned up (This cleanup
        is disabled when debug mode is on.)
    ~ Untitled (unsaved) models now use "~/_temp_simple_rays" as temp
        image directory. (Previously they used a temporary dir beneath
        the application "plugins" directory.)
  
  # --------------------------------------------------------------------

  raytest_dialog()
  
    + remembers the last used options in @@def_opts
  
  
# ======================================================================

  ADDITIONS:
  
  + MULTI-LANGUAGE SUPPORT
  
  + SketchupExtension loader file "load_qpik_simple_rays.rb"

# ======================================================================
  