[Code] New Image methods

[TIG]

See here for download http://forums.sketchucation.com/viewtopic.php?p=293677#p293677
###########################################################################
TIG (c) 2010
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.
[NB:definition and transformation methods are Copyright 2008, AlexM]
###########################################################################
image_class.rb
###########################################################################
Needs 'Bumpmapper.jar, 'BumpmapperInverted.jar', 'Thumbnailer.jar' and
'ThumbnailerRGB.jar' in the same sub-folder.
You will need Java installed on your PC/MAC - it usually is...
Also may also needs certain other .rb's that come in the same folder.
Temporary .ini files are written to the ../Plugins/SKMtools/ folder and
are deleted by the various methods to pass values to the .jar executable.
Loaded by 'SKMtools_loader.rb' in the ../Plugins/ folder.
###########################################################################
Adds new methods to the Sketchup class 'Image' - including:

Image.definition

returns the 'definition' of the image.

Image.transformation

returns the 'transformation' of the image.

Image.transformation=tr

set the 'transformation' of the image to a new transformation 'tr'.

Image.use_as_material

makes a new material based on the Image AND keeps the Image intact,
it 'puts' the new Material name and it returns the new Material.

Image.make_unique

if there is more that one instance of an Image the specified image is
'made unique' - now any subsequent changes to it will not affect others.
The associated image_file is duplicated and its name is incremented
with a numerical suffix.
Any Attributes [Animation:folder/timer etc] are cloned from the
original Image into the now 'unique' version.
It returns a new Image object, so you will need to use
'image=image.make_unique' to retain the reference to it as 'image'...

Image.copy

this makes a copy of the Image using the same definition.
Any Attributes [Animation:folder/timer etc] are kept in the copy.
It returns the new Image object for the copied Image so use
'copiedimage=image.copy' to get its reference for later...

Image.clone

this is like Image.copy BUT it runs an Image.make_unique on it so
it is a separate definition of a new Image object.
The associated image_file is duplicated and its name is incremented
with a numerical suffix.
Any Attributes [Animation:folder/timer etc] are cloned from the
original Image into the now 'unique' version.
It returns a new Image object, so you will use
'clonedimage=image.clone' to get the reference to it for later...

Image.imagefile

returns the name of the Image's image-file - e.g. 'Poster666.png'

Image.imagefile='filepath'

this changes the image-file used by the Image to the image 'filepath',
it returns the 'imagefile-name' if successful, or 'nil'.
Only the following file-types are useable:
".jpg", ".jpeg", ".png", ".psd", ".tif", ".tga" and ".bmp".

Image.save_imagefile('folder')

saves the image-file used by the Image into 'folder',
it keeps the original image file's name [with spaces etc squeezed out],
returns the path the the image-file - e.g. "C:\Temp\Poster_01.png".

Image.folder='folder'

this sets the 'folder' that the Image might use for an 'animation'.
It defaults to 'nil'. It is saved as an Attribute with the Image -
'Animation','folder'. When used later, if the 'folder' is not found,
then it is reset to 'nil'.
To 'unset' an Image's folder use Image.folder=nil
The 'folder' should contain image-files that are numbered in the order
you wish them to be used e.g. img001.png, img002.png, img003.png etc.
Only files with the following file-type suffixes are used:
".jpg", ".jpeg", ".png", ".psd", ".tif", ".tga" and ".bmp"
To use the the 'folder' you invoke to use on of the 'animation'
methods explained below.

Image.folder

returns the 'folder' associated with the Image.
Returns 'nil' if not set: of if not found it's reset to 'nil'.

Image.timer='timer'

by default any Image with a 'folder' set has its 'timer' set to 'nil'.
You can reset it to any number >= 0.0 using this method, e.g.
Image.timer=0.1. If the 'timer' is 'nil' [0.0] then the Image's
'animation' will swap its image-files over only when a Scene tab
changes - e.g. during a scene-animation sequence. However, if it's set
to > 0.0 then the Image will also animate within the Scene as you
work, pan/zoom etc and also across scene-animations etc.
This is invoked by a UI.timer() changing frames every 0.1 seconds.
The 'timer' is saved as an Attribute of the Image ["Animation","timer"].
If the Image has no 'folder' set it's set to 'nil'.
It returns the float of the 'timer' value as set, or 'nil'.

Image.timer

return a 'float' representing the 'timer' set for that Image.
It is read from the Image's Attribute "Animation","timer".
If it's not set it returns 'nil'.
If the Image has no 'folder' set it's set to 'nil'.

Image.faceme='type'

this sets the 'faceme' Attribute of the Image to 'type'.
If 'nil' [or '0'] it stops the Image's 'faceme' property - it keeps the
Transformation that the Image has when the 'faceme' property ends.
If '1' it keeps the Image's origin to its bottom-left and makes it
always face the camera, rotating about the Z_AXIS as it does so.
If '2' it resets the Image's origin to its bottom-center and makes it
always face the camera, rotating about the Z_AXIS as it does so.
If '3' it resets the Image's origin to its bottom-right and makes it
always face the camera, rotating about the Z_AXIS as it does so.
Every Instance of the Image in placed into its own Group which has its
'faceme' behaviour set 'true'.
If the Image's 'faceme' is set to 'nil' [or '0'] then any 'faceme'
Groups that contain the Image's Instances are exploded.
The Image/Group 'faceme' property and links are remembered across sessions.

Image.faceme

returns 'nil', 1, 2 or 3 depending on the Image's 'faceme' Attribute.

Image.start_animation

It uses each of the image-files found in the Images's 'folder' -
as set by Image.folder='folder' as explained above.
If the Image does not have an 'Animation','folder' Attribute set then
it returns 0. Assuming the 'folder' exists then its image-files are
used in turn, in alphanumerical order [img01.png, img02.png, etc], and
the 'Image.imagefile=filepath' method changes the Image's 'image-file'.
All of the image-files in the 'set' found in the 'folder' should
preferably have the same pixel w/h etc to ensure consistency and the
same file-type [e.g. all .png] to avoid 'loading-order' discrerencies.
If only one instance of the the Image is to be changed then remember to
use 'Image.make_unique' on it to separate it from all other instances
before using this tool. The Image now displays each of the specified
image-files in turn as the Image's 'image-file'.

If the Image's 'timer' is set to 'nil' then the Image's image-file 
changes with every change of 'Scene' - when makng an Animation etc 
[an Observer is added to the Model's Pages to facilitate this automatic 
change]. The list of image-files is processed repeatedly until either 
the methods Image.stop_animation or Image.stop_animation_all are 
invoked.  If you add a new Scene during an animation sequence [and it 
is set as 'included' in the animation in the settings in the 
Scene-Manager] then these should be included in the Image's animation 
sequence when it is next becomes the 'active' Scene.
The rate of change of the Scene tabs during an Animation will clearly 
affect the appearance of the Image animation changes...

If the Image's 'timer' is set to a number [of seconds] then the Image's 
image-file changes every 'timer' seconds - as you work or make scene-
animations. The list of image-files is processed repeatedly until 
either the methods Image.stop_animation or Image.stop_animation_all are 
invoked.

You can use this tool to animate Images as backgrounds-through-windows, 
Computer/TV-screens, flickering-fires/flames, waving-flags, rotating-
wheels,/machinery, flapping-birds, walking-people/animals 
[when combined with multiple instances of the Image in different 
locations and on different layers on/off between scenes to mimic the 
'translation' movement as well as the repetitive movement within the 
Image animation itself] etc.  
If you are moving the Camera between each Scene, if desired you can set 
the Image to 'faceme' if you want the Image to always face the viewer, 
e.g. a flickering-candle-flame: otherwise it can be left, e.g. 
a TV-screen-image placed onto the TV-set.
Use the Image.faceme='type' method to [re]set this property, see above.

Returns 'true' if set or 'false' if not set, e.g. the Image's 'folder' 
is no longer available or it contains no valid images.
If the Image's 'folder' is not found then the Image's Attribute 
'Animation','run' is reset to 'false'.

Image animation effects only work during that session and have to be 
restarted when the Model is reopened. The Image's 'folder' Attribute is 
remembered across sessions.

Image.start_animation will stop any animations already running on 
that Image - i.e. an Image can only have one active animation at a time.

The 'set' of image-files used is a snap-shot of the contents of the 
'folder' at the moment the animation is started, so any changes to the 
'set' are not registered until a new Image.start_animation is 
invoked, stopping the current one and then running the new version 
using the image-files 'set' currently in the 'folder'.

Returns 1 if the animation was successfully started, 0 otherwise.

Image.start_animation_all

This finds all Images with an 'Animation','folder' Attribute set and
then starts their animation - i.e. a Pages Observer is amde for each
Image. See Image.start_animation above for more details...
Returns the number of animations started.

Image.stop_animation

this stops the current animation [if any].
It either removes the Observer from the Model's Pages so that the
Image does not display 'animation' effects or if the 'timer' is > 0.0
it cancels the current UI.timer() and the resultant 'animation'.
The Image is 'frozen' using its current image-file.
If you want to revert to a particular image-file then after 'stopping'
the animation sequence you will need to invoke the method to change it
using Image.imagefile='path_to_defaultimage.png'.
Returns 1 if the animation was successfully stopped, 0 otherwise.

Image.stop_animation_all

this stops ALL currently running Images' animation effects.
It sets the ALL Images' Attribute 'Animation','run' to be 'false'.
It either removes all of the Observers from the Model's Pages so that
NO Images will display 'animation' effects or it cancels the all of the
UI.timers and their resultant 'animations'.
The Images are 'frozen' using their current image-file.
If you want to revert to a particular image-file for a particular Image
then after 'stopping_all' you will need to invoke the method to change
it using Image.imagefile='path_to_defaultimage.png'.
Returns the number of animations stopped.

###########################################################################
Donations:
By Paypal.com to info @ revitrev.org
###########################################################################
Version:
1.0 20101209 First issue with extended toolset - animation etc.
###########################################################################