## com.bbn.openmap.image
Class MagicPlanetImageComponent

    java.lang.Object
      com.bbn.openmap.MapHandlerChild
          com.bbn.openmap.OMComponent
              com.bbn.openmap.image.MagicPlanetImageComponent

All Implemented Interfaces:
  java.awt.event.ActionListener, java.beans.beancontext.BeanContextChild, java.beans.beancontext.BeanContextMembershipListener, java.util.EventListener, LayerListener, LightMapHandlerChild, java.beans.PropertyChangeListener, PropertyConsumer

public class MagicPlanetImageComponent
extends OMComponent
implements LayerListener, java.beans.PropertyChangeListener, java.awt.event.ActionListener

The MagicPlanetImageComponent is an OpenMap Component designed to create images for Global Imagination's MagicPlanet Globe. This component, when added to an OpenMap MapHandler, will find the LayerHandler so it can find out when the Layer given to the MapBean change, so it knows which ones to use when creating an image file. This component also connects to the MapBean as a PropertyChangeListener to find out when the ocean color has changed. The MagicPlanet software (Storyteller) has the option of displaying images stored in a particular directory, either displaying the latest (lexically) image or cycling through a set of images in the directory to create a movie on the globe.

The class has options that change the format of the images created, where the images are stored, how often they are created, and the scale of the images. The scale of the image dictates its pixel size, since the proportion of the projection has to be constant for it to work on the globe. The projection used for the images is always the OpenMap LLXY projection, that's what the MagicPlanet expects.

The properties for this component are:

                    outputDirectory=path_to_directory_for_writing_images

                    # Milliseconds between image creation, 60000 is the default, representing 1 minute
                    updateInterval=60000

                    # Milliseconds after the timer is created before the MagicPlanetImageComponent takes
                    # its first image and starts updating according to the updateInterval.  Default is 0,
                    # so the first image is taken as soon as the component finds the layers.
                    initialDelay=180000

                    # The scale of the image, it determines the size of the image.  This
                    # may be important for certain layers to show particular details.
                    # The default is 60000000F, which represents an image approximately 2kx1k
                    scale=60000000F

                    # Property to tell the component to create a new image and reset the timer if the
                    # layers on the MapBean change.  True by default.
                    autoUpdate=true

                    # Property to tell the component to remove old images, default is true
                    cleanup=true

                    # Property to set the wait time before deleting old images, represented
                    # in milliseconds. The default is 86400000, representing one day.
                    cleanupInterval=86400000

                    # Properties for setting the pixel width and height of the images. These properties
                    # provide a more precise way to control the image size, and tell the component to
                    # scale the image created with the scale setting set above.  The closer you get
                    # the scale to provide you the image size you want, the higher quality image
                    # you will have.  The default values for these properties are -1, which tells
                    # the component to not change the size of the image resulting from the scale setting.
                    width=-1
                    height=-1

                    # Property to set the name of the last image written in a file, so other programs
                    # can more easily figure out what it was.  The property should reflect the path
                    # to the file to be written, which will contain 'MagicPlanet.lastFile=YYYYMMDDhhmmss.ext',
                    # where YYYYMMDDhhmmss are year, month, day, hour, minute and second the file was created,
                    # and ext is the extension for the image type.  This information, combined with the directory
                    # information stored above, will let you know where the file is.  If this property is not set,
                    # no text file will be written.
                    lastImageFile=path_to_text_file

                    # Property that describes a system command that should be run each time an image is created.
                    # The property should contain exactly what would be typed into a command line for a script
                    # to be run, in the same environment this component is being run in.  There are special arguments
                    # that can be inserted into this property string that the component will use to replace the current
                    # image file name:
                    #
                    # %FILEPATH% gets replaced with the complete path of the new image file.
                    # %FILENAME% gets replaced with the file name if the image file.
                    # %FILENAME_WITHOUT_EXTENSION% gets replaced with the file name without a '.' or anything after that.
                    #
                    # The default is no value being set for the script, which means nothing will happen.  Here is an example for
                    # creating a .dds file from the current image, using nvidiea's nvdxt script.
                    postProcessingScript="c:/Program Files/NVIDIA Corporation/NVIDIA DDS Utilities/nvdxt.exe" -swap -dxt1c -file %FILEPATH% -output c:/%FILENAME_WITHOUT_EXTENSION%.dds

Author:
  dietrick

Field Summary
`protected boolean` `autoUpdate`
`static java.lang.String` `AutoUpdateProperty`
`protected java.awt.Paint` `background`
`protected boolean` `cleanup`
`protected int` `cleanupInterval`
`static java.lang.String` `CleanupIntervalProperty`
`static java.lang.String` `CleanupProperty`
`protected boolean` `DEBUG`
`protected int` `height`
`static java.lang.String` `HeightProperty`
`protected ImageFormatter` `imageFormatter`
`protected int` `initialDelay`
`static java.lang.String` `InitialDelayProperty`
`static java.lang.String` `LAST_IMAGE_FILE_KEY`
`protected java.lang.String` `lastImageFile`
`static java.lang.String` `LastImageFileProperty`
`protected LayerHandler` `layerHandler`
`protected Layer[]` `layers`
`protected MapBean` `mapBean`
`static java.lang.String` `OutputDirectoryProperty`
`protected java.lang.String` `outputDirectoryString` Parent directory for images.
`protected java.lang.String` `postProcessingScript`
`static java.lang.String` `PostProcessingScriptProperty`
`protected Projection` `proj`
`static java.lang.String` `REPLACE_FILENAME_MARKER`
`static java.lang.String` `REPLACE_FILENAME_WOEXT_MARKER`
`static java.lang.String` `REPLACE_FILEPATH_MARKER`
`protected float` `scale`
`static java.lang.String` `ScaleProperty`
`protected javax.swing.Timer` `timer`
`protected int` `updateInterval`
`static java.lang.String` `UpdateIntervalProperty`
`protected int` `width`
`static java.lang.String` `WidthProperty`

Fields inherited from class com.bbn.openmap.OMComponent
`i18n, propertyPrefix`

Fields inherited from class com.bbn.openmap.MapHandlerChild
`beanContextChildSupport`

Fields inherited from interface com.bbn.openmap.PropertyConsumer
`EditorProperty, initPropertiesProperty, LabelEditorProperty, ScopedEditorProperty`

Constructor Summary
`MagicPlanetImageComponent()`

Method Summary
`void` `actionPerformed(java.awt.event.ActionEvent e)`
`protected java.lang.String` `checkTrimAndNull(java.lang.String s)`
`void` `cleanup(boolean deleteAll)` Remove old files.
`void` `createImage()` Create a new image.
`void` `createTimer()` Creates a timer with the current updateInterval and calls setTimer().
`void` `findAndInit(java.lang.Object someObj)` MapHandlerChild method extended through the OMComponent hierarchy.
`void` `findAndUndo(java.lang.Object someObj)` MapHandlerChild method extended through the OMComponent hierarchy.
`protected java.lang.String` `generatePostProcessingCmd(java.lang.String script, java.lang.String filePath)`
`java.awt.Paint` `getBackground()` Return the 'ocean' color of the planet.
`int` `getCleanupInterval()`
`protected java.lang.String` `getFileNameForTime(long l)`
`int` `getHeight()`
`ImageFormatter` `getImageFormatter()`
`int` `getInitialDelay()`
`java.lang.String` `getLastImageFile()` Get the location of a file that can be read to find out the name of the last image to be created.
`protected LayerHandler` `getLayerHandler()`
`Layer[]` `getLayers()`
`protected MapBean` `getMapBean()`
`java.lang.String` `getOutputDirectoryString()`
`java.lang.String` `getPostProcessingScript()`
`Projection` `getProj()` Get the image projection.
`java.util.Properties` `getProperties(java.util.Properties props)` PropertyConsumer method, to fill in a Properties object, reflecting the current values of the OMComponent.
`java.util.Properties` `getPropertyInfo(java.util.Properties props)` Method to fill in a Properties object with values reflecting the properties able to be set on this PropertyConsumer.
`float` `getScale()`
`protected long` `getTimeForFileName(java.lang.String fileName)` Decode the file name to see what time the file was created.
`javax.swing.Timer` `getTimer()` Get the timer being used for automatic updates.
`int` `getUpdateInterval()`
`int` `getWidth()`
`void` `handleUpdate()` Checks to see if there is a timer, and if the component wants to automatically update the current image.
`boolean` `isAutoUpdate()`
`boolean` `isCleanup()`
`void` `propertyChange(java.beans.PropertyChangeEvent evt)`
`void` `setAutoUpdate(boolean autoUpdate)` Set whether a new image should be created immediately if the MapBean's layers change, or if the MapBean's background color changes.
`protected void` `setBackground(java.awt.Paint paint)` Set the 'ocean' color of the planet.
`void` `setCleanup(boolean cleanup)` Set whether the component should delete old images.
`void` `setCleanupInterval(int cleanupInterval)` Set the interval, in milliseconds, between the current time and the time old images were created before they are deleted.
`void` `setHeight(int height)` Set the scaled pixel height of the images.-1 maintains what the scale setting decides.
`void` `setImageFormatter(ImageFormatter iFormatter)` Set the ImageFormatter to use for creating the image files.
`void` `setInitialDelay(int initialDelay)`
`void` `setLastImageFile(java.lang.String lastImageFile)` Set the location of a file that can be read to find out the name of the last image to be created.
`protected void` `setLayerHandler(LayerHandler lh)` Set the LayerHandler, become a LayerListener object to it to know when the layers on the MapBean change.
`void` `setLayers(Layer[] layers)`
`void` `setLayers(LayerEvent evt)`
`protected void` `setMapBean(MapBean mb)` Set the MapBean, become a PropertyChangeListener object to it to know when the background color on the MapBean changes.
`void` `setOutputDirectoryString(java.lang.String outputDirectoryString)` Set the directory where the images should be written to.
`void` `setPostProcessingScript(java.lang.String postProcessingScript)`
`void` `setProj(Projection proj)` Set the image projection.
`void` `setProperties(java.lang.String prefix, java.util.Properties props)` Sets the properties for the OMComponent.
`void` `setScale(float scale)` Sets the scale for the projection, which directly affects the size of the image.
`void` `setTimer(javax.swing.Timer t)` If you want the layer to update itself at certain intervals, you can set the timer to do that.
`void` `setUpdateInterval(int delay)` The delay between timer pulses, in milliseconds.
`void` `setWidth(int width)` Set the scaled pixel width of the images.

Methods inherited from class com.bbn.openmap.OMComponent
`getPropertyPrefix, setProperties, setPropertyPrefix`

Methods inherited from class com.bbn.openmap.MapHandlerChild
`addPropertyChangeListener, addVetoableChangeListener, childrenAdded, childrenRemoved, findAndInit, firePropertyChange, fireVetoableChange, getBeanContext, removePropertyChangeListener, removeVetoableChangeListener, setBeanContext`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### OutputDirectoryProperty

    public static final java.lang.String OutputDirectoryProperty

See Also:
  Constant Field Values

### UpdateIntervalProperty

    public static final java.lang.String UpdateIntervalProperty

See Also:
  Constant Field Values

### InitialDelayProperty

    public static final java.lang.String InitialDelayProperty

See Also:
  Constant Field Values

### ScaleProperty

    public static final java.lang.String ScaleProperty

See Also:
  Constant Field Values

### AutoUpdateProperty

    public static final java.lang.String AutoUpdateProperty

See Also:
  Constant Field Values

### CleanupProperty

    public static final java.lang.String CleanupProperty

See Also:
  Constant Field Values

### CleanupIntervalProperty

    public static final java.lang.String CleanupIntervalProperty

See Also:
  Constant Field Values

### HeightProperty

    public static final java.lang.String HeightProperty

See Also:
  Constant Field Values

### WidthProperty

    public static final java.lang.String WidthProperty

See Also:
  Constant Field Values

### LastImageFileProperty

    public static final java.lang.String LastImageFileProperty

See Also:
  Constant Field Values

### PostProcessingScriptProperty

    public static final java.lang.String PostProcessingScriptProperty

See Also:
  Constant Field Values

### LAST_IMAGE_FILE_KEY

    public static final java.lang.String LAST_IMAGE_FILE_KEY

See Also:
  Constant Field Values

### REPLACE_FILEPATH_MARKER

    public static final java.lang.String REPLACE_FILEPATH_MARKER

See Also:
  Constant Field Values

### REPLACE_FILENAME_MARKER

    public static final java.lang.String REPLACE_FILENAME_MARKER

See Also:
  Constant Field Values

### REPLACE_FILENAME_WOEXT_MARKER

    public static final java.lang.String REPLACE_FILENAME_WOEXT_MARKER

See Also:
  Constant Field Values

### DEBUG

    protected boolean DEBUG

### layerHandler

    protected LayerHandler layerHandler

### mapBean

    protected MapBean mapBean

### outputDirectoryString

    protected java.lang.String outputDirectoryString

  Parent directory for images.

### updateInterval

    protected int updateInterval

### initialDelay

    protected int initialDelay

### scale

    protected float scale

### proj

    protected Projection proj

### background

    protected java.awt.Paint background

### layers

    protected Layer[] layers

### autoUpdate

    protected boolean autoUpdate

### imageFormatter

    protected ImageFormatter imageFormatter

### cleanup

    protected boolean cleanup

### cleanupInterval

    protected int cleanupInterval

### height

    protected int height

### width

    protected int width

### lastImageFile

    protected java.lang.String lastImageFile

### postProcessingScript

    protected java.lang.String postProcessingScript

### timer

    protected javax.swing.Timer timer

Constructor Detail

### MagicPlanetImageComponent

    public MagicPlanetImageComponent()

Method Detail

### findAndInit

    public void findAndInit(java.lang.Object someObj)

  MapHandlerChild method extended through the OMComponent hierarchy. This is the method called by the MapHandler with objects added to the MapHandler.

  Specified by:
    `findAndInit` in interface `LightMapHandlerChild`
  Overrides:
    `findAndInit` in class `MapHandlerChild`

### findAndUndo

    public void findAndUndo(java.lang.Object someObj)

  MapHandlerChild method extended through the OMComponent hierarchy. This is the method called by the MapHandler with objects removed from the MapHandler.

  Specified by:
    `findAndUndo` in interface `LightMapHandlerChild`
  Overrides:
    `findAndUndo` in class `MapHandlerChild`

### getTimer

    public javax.swing.Timer getTimer()

  Get the timer being used for automatic updates. May be null if a timer is not set.

### setTimer

    public void setTimer(javax.swing.Timer t)

  If you want the layer to update itself at certain intervals, you can set the timer to do that. Set it to null to disable it. If the current timer is not null, the graphic loader is removed as an ActionListener. If the new one is not null, the graphic loader is added as an ActionListener.

### createTimer

    public void createTimer()

  Creates a timer with the current updateInterval and calls setTimer().

### setUpdateInterval

    public void setUpdateInterval(int delay)

  The delay between timer pulses, in milliseconds.

### getUpdateInterval

    public int getUpdateInterval()

### getInitialDelay

    public int getInitialDelay()

### setInitialDelay

    public void setInitialDelay(int initialDelay)

### actionPerformed

    public void actionPerformed(java.awt.event.ActionEvent e)

  Specified by:
    `actionPerformed` in interface `java.awt.event.ActionListener`

### getLayerHandler

    protected LayerHandler getLayerHandler()

  Returns:
    the object currently known as the LayerHandler by this object.

### setLayerHandler

    protected void setLayerHandler(LayerHandler lh)

  Set the LayerHandler, become a LayerListener object to it to know when the layers on the MapBean change. If there is already a LayerHandler known to this component, this component will remove itself as a listener to the previous LayerHandler.

  Parameters:
    `lh` - LayerHandler.

### getMapBean

    protected MapBean getMapBean()

  Returns:
    the object currently known as the MapBean by this object.

### setMapBean

    protected void setMapBean(MapBean mb)

  Set the MapBean, become a PropertyChangeListener object to it to know when the background color on the MapBean changes. If there is already a MapBean known to this component, this component will remove itself as a listener to the previous MapBean.

  Parameters:
    `mb` - MapBean.

### setProperties

    public void setProperties(java.lang.String prefix,
                              java.util.Properties props)

  Description copied from class: `OMComponent`
  Sets the properties for the OMComponent.

  Specified by:
    `setProperties` in interface `PropertyConsumer`
  Overrides:
    `setProperties` in class `OMComponent`
  Parameters:
    `prefix` - the token to prefix the property names
    `props` - the `Properties` object

### getProperties

    public java.util.Properties getProperties(java.util.Properties props)

  Description copied from class: `OMComponent`
  PropertyConsumer method, to fill in a Properties object, reflecting the current values of the OMComponent. If the component has a propertyPrefix set, the property keys should have that prefix plus a separating '.' prepended to each propery key it uses for configuration.

  Specified by:
    `getProperties` in interface `PropertyConsumer`
  Overrides:
    `getProperties` in class `OMComponent`
  Parameters:
    `props` - a Properties object to load the PropertyConsumer properties into. If props equals null, then a new Properties object should be created.
  Returns:
    Properties object containing PropertyConsumer property values. If getList was not null, this should equal getList. Otherwise, it should be the Properties object created by the PropertyConsumer.

### getPropertyInfo

    public java.util.Properties getPropertyInfo(java.util.Properties props)

  Description copied from class: `OMComponent`
  Method to fill in a Properties object with values reflecting the properties able to be set on this PropertyConsumer. The key for each property should be the raw property name (without a prefix) with a value that is a String that describes what the property key represents, along with any other information about the property that would be helpful (range, default value, etc.). For Layer, this method should at least return the 'prettyName' property.

  Specified by:
    `getPropertyInfo` in interface `PropertyConsumer`
  Overrides:
    `getPropertyInfo` in class `OMComponent`
  Parameters:
    `props` - a Properties object to load the PropertyConsumer properties into. If getList equals null, then a new Properties object should be created.
  Returns:
    Properties object containing PropertyConsumer property values. If getList was not null, this should equal getList. Otherwise, it should be the Properties object created by the PropertyConsumer.

### setLayers

    public void setLayers(LayerEvent evt)

  Specified by:
    `setLayers` in interface `LayerListener`

### handleUpdate

    public void handleUpdate()

  Checks to see if there is a timer, and if the component wants to automatically update the current image. If the timer isn't running, it's started.

### createImage

    public void createImage()

  Create a new image.

### generatePostProcessingCmd

    protected java.lang.String generatePostProcessingCmd(java.lang.String script,
                                                         java.lang.String filePath)

### getFileNameForTime

    protected java.lang.String getFileNameForTime(long l)

  Parameters:
    `l` - unix time in milliseconds
  Returns:
    String representing file name for the given time.

### getTimeForFileName

    protected long getTimeForFileName(java.lang.String fileName)
                               throws java.lang.NumberFormatException

  Decode the file name to see what time the file was created.

  Parameters:
    `fileName` -
  Returns:
    milliseconds from unix epoch.
  Throws:
    `java.lang.NumberFormatException` - if the filename can't be decoded.

### cleanup

    public void cleanup(boolean deleteAll)

  Remove old files. Checks the current time against the timestamps decoded by the names of files found in the output directory, and deletes them if the difference between those times is greater than the cleanupInterval.

  Parameters:
    `deleteAll` - if true, all images will be deleted, regardless of when they were created.

### propertyChange

    public void propertyChange(java.beans.PropertyChangeEvent evt)

  Specified by:
    `propertyChange` in interface `java.beans.PropertyChangeListener`

### setBackground

    protected void setBackground(java.awt.Paint paint)

  Set the 'ocean' color of the planet. The MagicPlanetImageComponent listens for events from the MapBean and will call this method if the ocean color on the MapBean is changed.

  Parameters:
    `paint` -

### getBackground

    public java.awt.Paint getBackground()

  Return the 'ocean' color of the planet.

  Returns:
    Returns the background.

### getLayers

    public Layer[] getLayers()

### setLayers

    public void setLayers(Layer[] layers)

### getOutputDirectoryString

    public java.lang.String getOutputDirectoryString()

### setOutputDirectoryString

    public void setOutputDirectoryString(java.lang.String outputDirectoryString)

  Set the directory where the images should be written to.

  Parameters:
    `outputDirectoryString` -

### getProj

    public Projection getProj()

  Get the image projection.

  Returns:
    current Projection of image.

### setProj

    public void setProj(Projection proj)

  Set the image projection.

  Parameters:
    `proj` -

### getScale

    public float getScale()

  Returns:
    the scale value of the projection.

### setScale

    public void setScale(float scale)

  Sets the scale for the projection, which directly affects the size of the image. Larger numbers make smaller images. Calling this method causes the setProj() method to be called with the new projection to use for images.

  Parameters:
    `scale` -

### isAutoUpdate

    public boolean isAutoUpdate()

  Returns:
    check if a new image should be created if the layers or background color changes.

### setAutoUpdate

    public void setAutoUpdate(boolean autoUpdate)

  Set whether a new image should be created immediately if the MapBean's layers change, or if the MapBean's background color changes. If false, a new image will be created on the next normal timer cycle.

  Parameters:
    `autoUpdate` -

### getImageFormatter

    public ImageFormatter getImageFormatter()

### setImageFormatter

    public void setImageFormatter(ImageFormatter iFormatter)

  Set the ImageFormatter to use for creating the image files.

  Parameters:
    `iFormatter` -

### isCleanup

    public boolean isCleanup()

### setCleanup

    public void setCleanup(boolean cleanup)

  Set whether the component should delete old images.

  Parameters:
    `cleanup` -

### getCleanupInterval

    public int getCleanupInterval()

### setCleanupInterval

    public void setCleanupInterval(int cleanupInterval)

  Set the interval, in milliseconds, between the current time and the time old images were created before they are deleted. This setting only matters if isCleanup() returns true.

  Parameters:
    `cleanupInterval` -

### getHeight

    public int getHeight()

### setHeight

    public void setHeight(int height)

  Set the scaled pixel height of the images.-1 maintains what the scale setting decides.

  Parameters:
    `height` - pixels.

### getWidth

    public int getWidth()

### setWidth

    public void setWidth(int width)

  Set the scaled pixel width of the images. -1 maintains what the scale setting decides.

  Parameters:
    `width` - pixels.

### getLastImageFile

    public java.lang.String getLastImageFile()

  Get the location of a file that can be read to find out the name of the last image to be created. If null, that means no such file is being created.

  Returns:
    the file name.

### setLastImageFile

    public void setLastImageFile(java.lang.String lastImageFile)

  Set the location of a file that can be read to find out the name of the last image to be created. If null, that means no such file is being created.

  Parameters:
    `lastImageFile` -

### getPostProcessingScript

    public java.lang.String getPostProcessingScript()

### setPostProcessingScript

    public void setPostProcessingScript(java.lang.String postProcessingScript)

### checkTrimAndNull

    protected java.lang.String checkTrimAndNull(java.lang.String s)

Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details