=begin
###
Copyright 2015 TIG (c)

All rights reserved.

This software is provided "as is" and without any express or implied 
warranties, including, without limitation, the implied warranties of 
merchantability and fitness for a particular purpose.


Extension:

By default the Extension TIG-shadowProjector is set to be active when it is first installed, but it may be switched on/off later as desired.


Menu:

Tools > ShadowProjector > submenu items  


 New Shadow Projection

1. Select the Face[s] to be processed.  
Note that all other Objects in the Selection are ignored.

2. Run the tool from the submenu item.

3. The Options dialog opens.  
Choose the Shadow 'Type' from the drop-down list.

  Lines
  Faces
  Faces[Edged]
  Faces[Edged]%
  Faces[Edged]%sq…

 
'Lines' draws just lines along each shadow's perimeter [the default Type].

'Faces' draws shadows as 'gray' faces, with edges hidden/visible.

'Faces[Edged]' draws shadows as 'gray' faces, edges visible.

'Faces[Edged]%' draws each shadow as a 'gray' face, edges visible, with a text-tag at the center of the 'Shadow' group showing the % of that Face in shade.

'Faces[Edged]%sq…' is similar, but it also appends the Shaded:Total Area, in either ft² or m² depending on your Model Units settings.

In this Options dialog you can also enter a 'Text Height', in current units.
Note that this is only used if a '%' Type is chosen.
The default text-height is 2" or 50mm depending on your Model Units settings.

These Options are remembered with the Model across sessions.


4. OK to continue, Cancel to abort.

Notes:

Selected Faces that are oriented away from the sun are ignored.
All qualifying Faces are now processed in turn.
All Faces are analyzed for shading, so it is much quicker to Select only those Faces you know to be shaded [or just those which you are interesting in].
Remember that an unshaded Face will take time to analyze and produce no 'Shadow' !  
'Shadows' are drawn over the Face showing the extent on any shadows cast on it by all other Faces in the Model [including any within Groups/Components] located between it and the sun.
Note that a Surface's 'Shadows' are processed as separate facets, so it is much quicker to have hidden geometry 'on' and then Select only those Surface Faces which you know to be shaded...
All Faces within the Model that fall within a face's reversed-umbra will be included in any shadow-casting analysis.
Hidden Objects, those on 'off' Layers, Faces with transparent-materials [<70% opacity] - or faces assigned the default-material within a group/instance that itself has a transparent-material [so it displays 'transparent' and casts no shadow] - and Objects with 'casts shadows' unchecked are ignored in the analysis.  
Each 'Shadow-Group' is named after the Model's ShadowTime and the Face's ID: 
e.g. Shadows@Jun_21_1200#0xc741eac
Those with % or %sq have the text-group similarly named, but with those values appended to the name:
e.g. Shadows@Jun_21_15=67.1%
The 'Shadow-Groups' are put on a Layer named 'SHAD'.
The 'Shadows' 'gray' material is named 'Shadows'; once it has been made you can change its color/transparency etc as desired.
Any text is colored 'Black'.
Later on the text-group can be moved within the shadow-group for clarity etc.
The text-group goes on a Layer named 'SHAD-TEXT'.
The tool beeps when it has finished processing.
The processing/shadow-group is one step undoable.
Note that if the 'Shadows' have Faces then it is moved 0.1mm off the original Face to avoid 'z-fighting' between surfaces.
Similarly any text-group is slightly offset upwards too to be above the Faces.
It is best to process a few faces at a time because Sketchup slows up almost 'exponentially' as it processes larger collections...  
If you process a lot at once be prepared to have lunch and come back when it has done !
Remember that although it might 'white-out', it is still processing.
It is recommended that you keep the Outliner window closed when using this tool, although it can be useful for selecting shadow/text-groups later on.


 Shadow Report to File

Writes a report of all Shadows to a txt file.


 Shadow Report in Ruby Console

Prints the report in the Ruby Console.


 Shadow Options for Model

Opens the Options dialog - this lets you change the settings for that Model without having to run an analysis.
The Options are saved with the Model across sessions.


 Help...

Opens the Help document.


 Locales:

You can make your own locale translations of the tool's .strings file as your own locale copy.

There are detailed instructions at the start of the standard file:
..Plugins/TIG-shadowProjector/Strings/TIG-shadowProjector-EN-US.strings

You can also make a translated copy of the Help .doc file:
..Plugins/TIG-shadowProjectorStrings/TIG-shadowProjector-EN-US.doc


Version:

2.0 20150319 Rewritten to be faster and more robust.  
3.0 20150323 Takes a face that looks away from the sun [thereby shading itself] 
as 100%, with no analysis.  
Takes account of 'casts-shadows/receives-shadows' settings for faces/containers.  
Excludes shadow geometry from transparent [<70% opacity] faces/inherited from 
containers [which therefore don't cast a real shadow]. 
Fixed issues with report writing when just 'lines'.  
3.1 20150324 Typo glitch with unnested faces fixed.  
4.0 20150330 Recoded for speed and robustness.  
###
=end
###
require('sketchup.rb')
###
module TIG
  module ShadowProjector
	###
	VERSION="4.0"
	CREATOR="TIG"
	NAME="ShadowProjector"
	FNAME="#{CREATOR}-#{NAME}"
	###
	if defined?(Encoding)
		ME = __FILE__.force_encoding("UTF-8") ### >=v2014 lashup
	else
		ME = __FILE__
	end
	PLUGINS = File.dirname(ME)
    FOLDER = File.join(PLUGINS, FNAME)
	### set up other folders
 	STRINGS=File.join(FOLDER, "Strings") ### Translations
	HELPS=File.join(FOLDER, "Help") ### Help files
	### set up translations
    file=File.join(STRINGS, "#{FNAME}-#{Sketchup.get_locale.upcase}.strings")
	if File.exist?(file)
		lines=IO.readlines(file)
	else
		file=File.join(STRINGS, "#{FNAME}-EN-US.strings")
		if File.exist?(file)
			lines=IO.readlines(file)
		else
			lines=[]
		end
	end
	lines.each{|line|
		line.chomp!
		next if line.empty? || line=~/^[#]/
		next unless line=~/[=]/ && line=~/["]/
		eval(line) ### set CONSTANT=value
	}
	###
	COPYRIGHT="#{CREATOR} © #{Time.now.year}"
	LOADER=File.join(FOLDER, "#{FNAME}_Loader.rb")
	###
	EXT=SketchupExtension.new(NAME, LOADER)
	EXT.name = NAME
	EXT.description = "#{FNAME}: #{DESC}"
	EXT.version = VERSION
	EXT.creator = CREATOR
	EXT.copyright = COPYRIGHT
	Sketchup.register_extension(EXT, true) # show on 1st install
	###
  end#module
end#module
