Application: gvSIG desktop » gvSIG 3D

=================================================================

 Visor 3D básico que integra Nasa WW SDK

=================================================================

-------------------

 Diseño técnico

-------------------

:Company:   gvSIG Association 

:Author:    DiSiD Corporation, S.L.

:Revision:  $Rev: $

:Date:      $Date: $

:Copyright: All rigths reserved

.. contents::

   :depth: 2

   :backlinks: none

.. sectnum::

   :depth: 1

   :start: 1

.. |year| date:: %Y

.. header:: 

   .. class:: headertable

   +-----------------------+-------------------------+

   |.. class:: left        |.. class:: right         |

   |                       |                         |

   | Diseño técnico        |###Page###               |

   +-----------------------+-------------------------+ 

.. footer:: 

    .. include:: <isonum.txt>

    .. class:: left

    *Visor 3D básico que integra Nasa WW SDK - Diseño técnico*

    |copy| |year| ** 

Introducción

=============

.. note::

 Este documento esta en continua construcción. A medida que se avance en el proyecto se irá añadiendo nueva información y refinando la existente.

Este documento detalla el diseño técnico de las funcionalidades definidas y la arquitectura del nuevo visor 3D basado en la librería NASA WW SDK para gvSIG 2.1+. Para más información consulte:

* http://worldwind.arc.nasa.gov/java/

* http://goworldwind.org/

El diseño técnico tendrá en cuenta el análisis de requisitos y el análisis funcional realizados en:

* http://devel.gvsig.org/svn/gvsig-3d/2.1/trunk/doc/re-visor-3d.rst

* http://devel.gvsig.org/svn/gvsig-3d/2.1/trunk/doc/af-visor-3d.rst

Diseño técnico

=====================

Para tener un poco del contexto del diseño técnico, se expone como debería de funcionar de forma resumida el visor 3D. Seguidamente se detallará como se estructura la librería, la arquitectura de plugins, las gestión de preferencias y por último la persistencia.

Ejemplo de caso de uso

-------------------------------

A partir de una vista 2D, se desea representar la información cargada de forma tridimensional. Para ello, el usuario dispondrá de dos entradas de menú / botones para crear los dos tipos de visores: esférico y plano definidos en ``TYPE.SPHERE`` y ``TYPE.FLAT``. Las dos entradas de menú ejecutarán una misma extensión, ``View3DExtension``, la cual dependiendo del *action command* realizará una acción u otra. Pero antes de explicar la creación de visor el usuario debe definir parámetros o propiedades para la carga y gestión de las capas dentro del visor 3D.

Las capas tienen propiedades comunes, definidas en `LayerProperties3D`_, y especificas que varían en función del tipo de capa, definidas en las subclases ``RasterLayerProperties3D`` y ``VectorialLayerProperties3D``. La propiedades comunes son las siguientes:

* Nivel máximo de detalle: nivel máximo de detalle en la visualización de la capa. Cuanto más alto sea el número máximo de nivel de detalle más tiles se generarán y más espacio ocuparán en el disco.

* Nivel mínimo de detalle: nivel mínimo de detalle en la visualización de la capa. Cuanto más pequeño sea el número mínimo de nivel de detalle menos tiles se generarán y menos espacio ocuparán en el disco.

* Formato: formato de los tiles generados. Depedendido del modo de carga y de las preferencias establecidas por el usuario puede variar entre estos formatos.

* Resolución en el nivel cero de detalle: permite aumentar la resolución o diminuirla en el nivel cero. Al aumentar la resolución al nivel cero los niveles posteriores también aumentan la resolución. Al contrario ocurre si disminuimos la resolución al nivel cero. 

* Tamaño de tesela: tamaño de los tiles generados.

* Elevación: indica si la capa es de elevación o no.

* Valor No Data: valor No Data.

* Unidades de elevación: unidades en las que esta representada el valor altura. Admite dos tipos de unidades: metros y pies.

La librería WW permite dividir un raster, ya sea normal o de elevación, en varios niveles de detalle que se muestran dependiendo de lo cerca o lejos se encuentre el enfoque de la capa raster. Los niveles de detalle se estructuran en forma de pirámide, de menor resolución y número de tiles (nivel mínimo) a mayor nivel de resolución y número de tiles (nivel máximo). Para más información de como se gestionan los niveles de detalle y los tiles dentro de la librería WW consulte:

 http://www.microimages.com/documentation/TechGuides/78Worldwind.pdf

Además de las propiedades descritas anteriormente si la capa es de tipo vectorial tiene las siguientes propiedades:

* Modo de carga rasterizado: permite indicar si la capa vectorial se va a cargar en el visor de forma rasterizada. La rasterización de una capa vectorial consiste en la conversión de una imagen vectorial a una imagen formada por píxeles. Por defecto las capas vectoriales se cargan en el visor rasterizadas debido a que la carga de capas vectoriales sin rasterizar se abordará más adelante.  

* Campo altura: indica el campo que contiene los valores de altura.

Una vez definidas las propiedades 3D de la capas, se procede a la creación de un visor 3D. La extensión obtendrá la instancia única mediante el Locator y ejecutará el método ``ViewPanel3DManager#createViewPanel3D(MapContext, TYPE)`` pasándole como parámetro el ``MapContext`` de la vista activa y el tipo de visor dependiendo del *action command*. En la creación del visor, se accederá a la capas del MapContext para cargarlas obteniendo las propiedades asociadas a las capas mediante ``ViewPanel3D#getLayerProperties3D(FLayer)`` para determinar que tipo de ``LayerConverter`` instanciar.

Instanciado el conversor para la obtención de una capa WW se ejecutará el método ``LayerConverter#convertToLayer(FLayer)`` o ``LayerConverter#convertToElevationModel(FLayer flayer)`` dependiendo del tipo de capa y el modo de carga. Estos método realizarán todo lo necesario para obtener la capa WW correspondiente. Una vez obtenida la capa se debe de añadir al componente WW y mostrar la ventana mediante ``ViewPanel3D#show()``.

Por otra parte cuando se activa un visor, se activan dos entradas de menú adicionales: Refrescar visor y Sincronizar enfoques. La entrada de menú Refrescar visor esta asociada a la extensión ``RefreshView3DExtension`` la cual obtendrá el `MapControl3D`_ del visor activo y ejecutará el método ``MapControl3D#synchronizeLayers()``. La entrada de menú Sincronizar enfoques esta asociada a la extensión ``SynchronizeView3DExtension`` la cual obtendrá el `MapControl3D`_ de la vista activa y ejecutará el método ``MapControl3D#synchronizeViewPorts()``.

Integración con la librería NASA WW SDK

----------------------------------------

World Wind es una colección de componentes que de forma interactiva muestran información geográfica en 3D. Las aplicaciones o applets que usen la librería deberá integrar uno o más componentes dentro de su interfaz gráfica. World wind sigue el siguiente esquema:

.. image:: images/world-wind-diagram.png

* Globe: representa la forma del planeta y el terreno. Contiene un Tessellator el cual es el encargado de generar el terreno.

* Layer: las capas añaden las imágenes, objetos u otra información al globo. La capas se ajustan a la forma del globo y se mueven junto a el cuando el usuario navega por el espacio tridimensional.

* Model: junta el globo y las capas.

* View: determina la vista del usuario sobre el modelo. La vista se va modificando en base a los eventos de usuario que recibe.

* SceneController: asocia la vista con el modelo. Controla el tiempo y el renderizado del modelo.

Se pretende crear una nivel de abstracción que ofrezca a los consumidores de la librería la funcionalidades descritas en el análisis funcional de forma que no tengan que interactuar con la librería WW. La integración del plugin con la librería World Wind se ha diseñado del siguiente modo:

* El componente `ViewPanel3D`_ integra un componente ``WorldWindowGLJPanel``. ``WorldWindowGLJPanel`` es autocontenido y su propósito es servir la aplicación WorldWind mostrando el modelo definido (globo y capas).

* La librería posee unos archivos de configuración en XML que son cargados cuando la librería se registra. Estos archivos de configuración por un lado definen la clases que implementan los distintos servicios que ofrece la librería y por otro las capas que se cargan por defecto al crear un modelo básico.

* Además de esta configuración, es necesario configurar unos parámetros especificados para crear un ``WorldWindowGLJPanel`` esférico o plano. Esta configuración se realiza al instanciar un objeto `ViewPanel3D`_. Dependiendo del modo indicado como parámetro, se establece una configuración u otra.

* La obtención de las capas WW a partir de capas de gvSIG se realiza mediante la clase `LayerConverter`_ la cual permite obtener la capa equivalente en WW a partir de una capa de gvSIG para añadirla a las capas del modelo WW. Se ha implementa un nuevo tipo de capa llamado RasterTiledImageLayer la cual gestiona la peticiones de tiles en tiempo para que se obtengan los datos directamente desde el DAL de gvSIG. Esta gestión se realiza mediante los objetos ``DefaultRetrieverFactory``, ``DefaultRasterRetriever``, ``DefaultRasterServer``, ``DefaultDataRasterReaderFactory``, ``DefaultDataRasterReader`` y ``DefaultDataRaster``.

LIB API

---------

Este es el API de la lógica de la librería, la cual esta basada en el modelo de implementación simple API/IMPL

* Project: org.gvsig.view3d/org.gvsig.view3d.lib/org.gvsig.view3d.lib.api

* Package: org.gvsig.view3d.lib.api

LayerProperties3D

~~~~~~~~~~~~~~~~~~~~~~

Clase que representa la propiedades 3D de una capa.

* getFormat() : String

  Obtiene el formato MIME de las teselas. El valor por defecto del modo de carga "Imagen raster" o "Vectorial rasterizada" es **image/png** y el formato por defecto del modo "Modelo digital del terreno" es **image/bil16**.

* setFormat(String theFormat) : void

  Asigna el formato de tipo MIME de las teselas. Dependiendo del modo de carga admite unos formatos u otros. Para el modo de carga "Imagen raster" o "Vecotiral raserizada" admite los formatos: image/png, image/jpg, image/jpeg y image/dds. Para el modo de carga "Modelo digital del terreno" acepta los formatos: image/bil16 y image/bil32.

* setMaxLevel(int maxLevel) : void

  Asigna el máximo nivel de detalle de la capa. Si el valor recibido como parámetro es igual a 0 o cadena vacía se asigna el valor óptimo dependiendo del tamaño del raster y del pixel.

* getMaxLevel() : int

  Obtiene el máximo nivel de detalle de la capa. 

* setMinLevel(int minLevel) : void

  Asigna el mínimo nivel de detalle de la capa. Si el valor recibido como parámetro es igual a 0 o cadena vacía se asigna el valor óptimo dependiendo del tamaño del raster y del pixel.

* getMinLevel() : int

  Obtiene el mínimo nivel de detalle de la capa.

* getLevelZeroResolutionMultiplier() : double

  Obtiene el multiplicador de resolución del nivel cero de detalle. 

* setLevelZeroresolutionMultiplier(double multiplier) : void

  Asigna el multiplicador de resolución al nivel cero de detalle. Admite como valor mínimo 0.5 y como valor máximo 1.5. 

* getTileWidth() : int

  Obtiene el ancho en píxeles de una tesela.

* setTileWidth(int width) : void

  Asigna el ancho en píxeles de una tesela.

* getTileHeight() : int

  Obtiene el alto en píxles de una tesela.

* setTileHeight(int height) : void

  Asigna el ancho en píxeles de una tesela.

* setElevation(boolean elevation) : void

  Asigna a la capa si el modo de carga de la capa es de elevación o no.

* getElevation() : boolean

  Obtiene si el modo de carga de la capa raster es de elevación o no.

* getNoDataValue() : double

  Obtiene el valor tomado como No Data.

* setNoDataValue(double noDataValue) : void

  Asigna el valor No Data. Si no se asigna ningún valor se obtiene el valor por defecto -99999.0.

* getElevationUnits() : String

  Obtiene en que unidades se encuentra el valor de elevación.

* setElevationUnits(String units) : void

  Asigna en que unidades se encuentra el valor de elvación. Solo acepta dos unidades: metros y pies.

RasterLayerProperties3D implements LayerProperties3D

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clase que representa la propiedades 3D de una capa raster. De momento no tiene ninguna propiedad específica.

VectorialLayerProperties3D implements LayerProperties3D

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clase que representa la propiedades 3D de una capa vectorial.

* setRasterized(boolean rasterized) : void

  Asigna a la capa si el modo de carga de la capa es rasterizado o no. Hay que tener en cuenta si ya se ha definido como elevación. Una capa solo puede ser o de elevación o rasterizada. Las dos propiedades a la vez es un estado inconsistente.

* getRasterized() : boolean

  Obtiene si el modo de carga de la capa vectorial es rasterizado o no.

* getElevationField() : String

  Obtiene el atributo del *FeatureType* que contiene la información de elevación. Solo se aplica cuando la capa es de tipo vectorial.

* setElevationField(String field) : void

  Asgina que atributo del *FeatureType* contiene la información de elevación. Solo se aplica cuando la capa es de tipo vectorial.

MapControlProperties3D

~~~~~~~~~~~~~~~~~~~~~~

Clase que representa las propiedades 3D de un MapControl3D.

* getVerticalExageration() : double

  Obtiene la exageración vertical del `MapControl3D`_.

* setVerticalExageration(double verticalExageration) : void

  Asigna la exagearación vertical al `MapControl3D`_.

* getAutoViewPortSynchronize() : boolean

  Obtiene si esta activada o no la sincronización automática de enfoques. Para la sincronización automática de enfoque la clase ``MapControl3D`` debe resgistrar un ``ViewPortListener`` en el ``Viewport`` de la vista enlaza. Esto le permitirá ejecutar el método ``MapControl3D#synchronizeViewports()`` cada vez que se llame al método ``ViewPortListener#extentChanged(ExtendEvent e)``.

* setAutoViewPortSynchronize(boolean flag) : void

  Asigna un valor a la sincronización automática de enfoques. ``True`` activa la sincronización automática mientras que ``False`` lo esactiva.

* getAutoLayerSynchronize() : boolean

  Obtiene si esta activa o no la sincronización de capas con cambios cuando se activa un visor. Para la sincronización automática de capas se debe registrar un ``FocusListener`` en la ventana que contiene el componenete WorldWind. Esto nos permite mediente el método ``FocusListener#focusGained(FocusEvent e)`` ejectuar el método ``MapControl3D#synchronizeLayers()`` cuando la ventana obtenga el foco. 

* setAutoLayerSynchronize(boolean flag) : void

  Asigna un valor a la sincronización automática de capas. ``True`` activa la sincronización automática mientras que ``False`` lo esactiva.

* getBlueMarbleLayerVisibility() : boolean

  Obtiene si esta visible o no la capa de fondo BlueMarble.

* setBlueMarbleLayerVisibility(boolean visibility) : void

  Asigna una visibilidad a la capa BlueMarble.

* getNasaLandsatLayerVisibility() : boolean

  Obtiene si esta visible o no la capa Nasa Landsat.

* setNasaLansatLayerVisibility() : boolean

  Asigna una visibilidad a la capa Nasa Landsat.

* getElevationVisiblity() : boolean

  Obtiene si esta visible o no la capa la capa de elevación global.

* setElevationVisibility(boolean visiblity) : void

  Asigna una visibilidad a la capa de elevaciones por defecto.

ViewProperties3D

~~~~~~~~~~~~~~~~~~~~~~

* getDefaultViewDimension() : Dimension

  Obtiene el tamaño por defecto de un visor 3D.

* setDefaultViewDimension(Dimension dimension) : void 

  Asigna el tamaño por defecto de un visor 3D.

* getAtmosphereVisibility() : boolean

  Obtiene si es visible o no la capa que representa la atmósfera.

* setAtmosphereVisiblity(boolean visibility) : void

  Asigna una visibilidad a la capa que representa la atmósfera.

* getNorthIndicatorVisibility() : boolean

  Obtiene si es visible o no la capa que representa el indicador del norte.

* setNorthIndicatorVisiblity(boolean visibility) : void

  Asigna una visibilidad a la capa que representa el indicado del norte.

* getScaleVisibility() : boolean

  Obtiene si es visible o no la capa que representa la escala.

* setScaleVisiblity(boolean visibility) : void

  Asigna una visibilidad a la capa que representa la escala.

* getStarBackgroundVisibility() : boolean

  Obtiene si es visible o no la capa que representa el fondo de estrellas.

* setStarBackgroundVisiblity(boolean visibility) : void

  Asigna una visibilidad a la capa que representa el fondo de estrellas.

* getMinimapVisibility() : boolean

  Obtiene si es visible o no la capa que representa el minimapa.

* setMinimapVisiblity(boolean visibility) : void

  Asigna una visibilidad a la capa que representa el minimapa

* getAnimationViewPortSynchronize() : boolean

  Obtiene si esta activa o no la animación de sincronización de enfoques.

* setAnimationViewPortSynchronize(boolean flag) : void

  Asigna un valor para activar o desactivar la animación en la sincronización automática.

* getCachePath() : String

  Obtiene la ruta a la caché.

* setCachePath(String path) : void

  Asigna la ruta que recibe como parámetro a la caché.

View3DManager

~~~~~~~~~~~~~~~~~

* getLayerProperties3D(FLayer layer) : LayerProperties3D

  Obtiene las propiedades asociadas a un capa.

* setLayerProperties3D(FLayer layer, LayerProperties3D properties) : void

  Asigna las propiedades a la capa que recibe como parámetro.

* getViewProperties3D() : ViewProperties3D

  Obtiene las propiedades 3D generales de la aplicación.

LIB IMPL

---------

Esta es la implementación de la lógica de la librería.

DefaulRasterLayerProperties3D implements RasterLayerProperties3D

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto de las propiedades de las capas raster.

DefaultVectorialLayerProperties3D implements VectorialLayerProperties3D

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto de la propiedades de las capas vectoriales.

SWING API

----------

Este es el API de la interfaz de usuario de la librería del visor 3D, la cual esta basada en el modelo de implementación simple API/IMPL.

* Project: org.gvsig.view3d/org.gvsig.view3d.swing/org.gvsig.view3d.swing.api

* Package: org.gvsig.view3d.swing.api

View3DSwingManager

~~~~~~~~~~~~~~~~~~~~~~

Punto de entrada a la librería view3D. Proporciona métodos para la creación de visores, paneles de propiedades y obtención de las propiedades 3D de una capa.

* createViewPanel3D(MapContext theMapContext, TYPE type) : ViewPanel3D

  Crea un objeto `ViewPanel3D`_ pasándole como parámetro el MapContext y el tipo de panel.

* createMapControl3D(MapContext mapContext, TYPE type) : MapControl3D

  Crea un objeto `MapControl3D`_ a partir del MapContext y el tipo.

* getMapControl3D(MapContext theMapContext, TYPE type) : MapControl3D

  Obtiene el `MapControl3D`_ del tipo indicado mediante el parámetro ``TYPE`` registrado al ``MapContext``. Si no hay ningún `MapControl3D`_ registrado devuelve ``null``.  

MapControl3D

~~~~~~~~~~~~~~~~~~~~~~

Define el API del componente 3D.  Esta clase representa el componente 3D del visor. Permite añadir y quitar capas, sincronizar capas y enfoques con la vista 2D enlazada, configurar la visibilidad de los componentes del visor. Además, a partir de un MapContext obtiene las capas y las convierte en capas WW para añadirlas al componente WorldWind.

* getCancellable() : Cancellabl

  Obtiene el objeto compartido el cual permite cancelar todas las ordenes de pintado que se están ejecutando en un momento dado.

* getMapContext() : MapContext

  Obtiene el ``MapContext`` asociado al visor. Del ``MapContext`` asociado se extrae la información necesaria para la representación de los datos en 3D y la sincronización de enfoques.

* getType() : TYPE

  Obtiene el tipo del visor. Devuelve un objeto enum que puede ser ``TPYE.SPHERE`` o ``TYPE.FLAT`` (ver `TYPE`_).

* getVerticalExaggeration() : double

  Obtiene la exageración vertical del visor.

* reloadLayers() : void

  Elimina las capas cargadas. Accede al MapContext asociado al visor y carga de nuevo las capas. Se usa para actualizar el visor con los posibles cambios realizados sobre la vista 2D.

* setMapContext(MapContext theMapContext) : void

  Establece el MapContext al visor y recarga la información mediante reloadLayers().

* setVerticalExaggeration(double verticalExaggeration) : void

  Establece las exageración vertical del visor.

* showAtmosphere() : void

  Si no esta añadida la capa que representa la Atmosphera la añade al componente ``WorldWind``.

* showNortIndicator() : void

  Si no esta añadido el componente que representa el indicador del norte lo añade al componente ``WorldWind``.

* showMiniMap() : void

  Si no esta añadido el componente que representa el minimapa lo añade al componente ``WorldWind``.

* showScale() : void

  Si no esta añadido el componente que representa la escala lo añade al componente ``WorldWind``.

* showStarBackground() : void

  Si no esta añadido el componente que representa el fondo de estrellas lo añade al componente ``WorldWind``.

* synchronizeViewPorts() : void

  Obtiene el ``ViewPort`` de la vista enlazada y realiza las transformaciones necesarias para obtener el ``Sector`` equivalente. Una vez obtenido el ``Sector`` hay que calcular el tamaño dentro del modelo actual usando ``Sector#computeBoundingBox(Globe globe, double verticalExaggeration, Sector sector)``. Con la extensión obtenida se debe estimar el zoom adecuado para que la extensión obtenida ocupe toda la vista. Una vez obtenido el zoom, habrá que usar ``View#goTo(Position position, double zoom)`` para cambiar el enfoque. Hay que tener en cuenta si la opción "Animación en la sincronización de enfoques" en las preferencias de la vista esta marcada o no. En caso de que este marcada la sincronización se debe realizar como se ha descrito anteriormente, en caso contrario, no hay que usar ``View#goTo(Position position, double zoom)`` sino ``View#setCenterPosition(Position position)`` y seguidamente ``View#setZoom(double zoom)``. En la método ``gov.nasa.worldwindx.examples.util.ExampleUtil#goto(WorldWindow wwd, Sector sector)`` se muestra un ejemplo de todo lo descrito anteriormente.

* synchronizeLayers() : void

  Comprueba que capas han sufrido cambios mediante el versionado del MapContext y la vuelve a recargar en el modelo del componente WW. Para la comprobación de cambios será necesario guardar las versiones de pintado de las capas en el momento de la instanciación del ``MapContext`` para que cuando este método se ejecute se compruebe con el valor actual de la capa para decidir si se sincroniza o no. Para recargar la capa se debe de eliminar y volver a añadir. Cuando se añade se debe de actualizar el registro de las versiones de pintado para futuras sincronizaciones.

* hideAtmosphere() : void

  Si esta añadido, elimina el componente que representa la atmósfera del componente ``WorldWind``.

* hideMiniMapVisibility() : void

  Si esta añadido, elimina el componente que representa el minimapa del componente ``WorldWind`` si esta añadido.

* hideStarBackgroun() : void

  Si esta añadido, elimina el componente que representa el fondo de estrellas del componente ``WorldWind`` si esta añadido.

* hideNorthIndicator() : void

  Si esta añadido, elimina el componente que representa el indicador del norte del componente ``WorldWind`` si esta añadido.

* hideScale() : void

  Si esta añadido, elimina el componente que representa las escala  del componente ``WorldWind`` si esta añadido.

* isAtmosphereVisible(): boolean

  Obtiene si esta visible o no la capa que representa la Atmosfera.

* isMinimapVisible(): boolean

  Obtiene si esta visible o no el Minimapa.

* isNorthIndicatorVisible(): boolean

  Obtiene si esta visible o no el indicador del Norte.

* isStartBackgroundVisible(): boolean

  Obtiene si esta visible o no el fondo de estrellas.

* isScaleVisible(): boolean

  Obtiene si esta visible o no la escala.

DefaultTiledImageLayer

________________________

Los pasos para obtener una capa RasterTiledImageLayer son los siguientes:

* Configuración de los parámetros necesarios en un fichero XML para crear una capa del tipo RasterTileImageLayer. Los parámetros necesarios son:

 * DATASET_NAME: Nombre del dataset.

 * DATA_CACHE_NAME: Nombre de la carpeta dentro de la cache donde se alojará los tiles generados en tiempo de ejecución. Este nombre debe ser único.

 * SERVICE_NAME: En nuestro caso siempre será *Offline*.

 * SECTOR: Zona geográfica del raster especificada en grados sobre la proyección EPSG:4326.

 * WIDTH: Ancho en píxeles de la imagen raster.

 * HEIGHT: Alto en píxeles de la imagen raster.

 * DISPLAY_NAME: Nombre de la capa.

 * IMAGE_FORMAT: Formato de los tiles que se generan. Se indican en formato MIME y se aceptan cuatro tipos: PNG, JPG, JPEG y DDS.

 * PIXEL_FORMAT: Formato del pixel. Puede tener dos valores: AVKey.IMAGE y AVKey.ELEVATION. En caso de DefaultTiledImageLayer siempre será AVKey.IMAGE.

 * TEXTURE_FORMAT: Tipo MIME del formato de la texturas. Se indican en formato MIME y se aceptan cuatro tipos: PNG, JPG, JPEG y DDS.

 * FORMAT_SUFFIX: sufijo de archivo de los tiles generados. Debe corresponderse al formato de imagen indicado.

 * AVAILABLE_IMAGE_FORMATS: Formatos de imagen disponibles.

 * TILE_ORIGIN: Origen desde donde se empiezan a crear los tiles.

 * TILE_WIDTH: Ancho en píxeles del tile.

 * TILE_HEIGHT: Alto en píxeles del tile.

 * NUM_LEVELS: Numero de niveles de detalle. Por defecto se calcular el valor óptimo dependiendo de la resolución del raster.

 * LEVEL_ZERO_DELTA: Objeto LatLon con valores en grados. Define que resolución corresponde a que nivel de detalle. Si el valor es muy pequeño (~1º) muestra en niveles de detalle bajos (0 o 1) resoluciones muy altas haciendo el proceso de pintado muy costoso. Es cambio si se asignan valores muy grandes (entre 36 y valores máximos) en niveles bajos de detalle se muestra una resolución muy pequeña haciendo que el proceso de pintado sea muy rápido. Por defecto en capas raster se calcula el valor óptimo y en capas rasterizadas se asigna el valor 20º.

 * NETWORK_RETRIEVAL_ENABLED: En nuestro caso siempre será ``false`` ya que para la libería los datos siempre están en local.

 * USE_MIP_MAPS: En este caso siempre tendrá el valor ``true`` debido a que mejora la visualización del raster.

 * USE_TRANSPARENT_TEXTURES: En este caso siempre tendrá el valor ``true`` debido a que mejora la visualización del raster.

Además de estos parámetros también es necesario añadir en tiempo de ejecución la capa gvSIG que se desea convertir de la cual se obtendrá la información para la creación de tiles mediante la clave GVSIG_LAYER. Por otra parte, existen parámetros opcionales que si no se asigna ningún valor la librería asigna el valor por defecto.

* Crear la capa de tipo RasterTileImageLayer a partir de los parámetros y añadirla al modelo. Al instanciar una nueva capa RasterTileImageLayer, se configura una factoría del tipo DefaultRetrieverFactory la cual permite la creación de objetos DefaultRasterRetriever. Dichos objetos son los encargados de realizar la distintas peticiones a un objeto DefaultRasterServer el cual es el encargado de servir la información procedente de un DataRaster genérico.

DefaultElevationModel

________________________

Los pasos para obtener una capa RasterTiledImageLayer son los siguientes:

* Configuración de los parámetros necesarios en un fichero XML para crear una modelo de elevación ElevationModel. Los parámetros necesarios son:

  * DISPLAY_NAME: Nombre del modelo de elevación

  * SECTOR: Zona geográfica del raster especificada en grados sobre la proyección EPSG:4326.

  * WIDTH: ancho en píxeles de la imagen raster.

  * HEIGHT: alto en píxeles de la imagen raster.

  * FILE_STORE: almacén de archivos de la cache. Proporciona métodos para añadir / quitar localizaciones, buscar archivos, borra archivos...

  * IMAGE_FORMAT: formato de los tiles genera

  * DATA_TYPE: tipo de dato de la información del raster.

  * PIXEL_FORMAT: formato del pixel: AVKey.ELEVATION o AVKey.IMAGE

  * FORMAT_SUFFIX: sufijo de archivo de los tiles generados.

    Además de estos parámetros también es necesario añadir en tiempo de ejecución la capa gvSIG que se desea convertir de la cual se obtendrá la información para la creación de tiles mediante la clave GVSIG_LAYER. Por otra parte, existen parámetros opcionales que si no se asigna ningún valor la librería asigna el valor por defecto. Los parámetros opcionales son:

  * BYTE_ORDER: orden de los bytes. Little endian o big endian.

  * ELEVATION_MAX: elevación máxima y mínima.

  * ELEVATION_MIN: elevación mínima del raster.

  * EXPIRY_TIME: tiempo de expiración de un tile dentro de la cache.

  * MISSING_DATA_SIGNAL: Valor "no data"

  * MISSING_DATA_REPLACEMENT: Valor que se obtiene al obtener la elevación sobre un punto "no data".

  * NETWORK_RETRIEVAL_ENABLED: Indica el modo de trabajo online o offline.

  * ELEVATION_EXTREMES_FILE: ruta al fichero que contiene información sobre las elevaciones extremas.

* Crear el modelo de elevación DefaultElevationModel a partir de lo parámetros y añadirlo al modelo ya existente. El modelo existente será de tipo CompoundElevationModel el cual permite añadir varios modelos de elevación y mostrarlos a la vez. Al instanciar un nuevo modelo de elevación, se configura una factoría del tipo DefaultRetrieverFactory la cual permite la creación de objetos DefaultRasterRetriever. Dichos objetos son los encargados de realizar las distintas peticiones a un objeto DefaultRasterServer el cual es el encargado de servir la información procedente de un DataRaster genérico. 

ViewPanel3D

~~~~~~~~~~~~~~~~~~~~~~

Representa la ventana que contiene el componente `MapControl3D`_.

* show() : void

  Invoca al WindowManager para mostrar el visor en modo ventana.

* getMapControl3D() : MapControl3D

  Devuelve el componente asociado a la ventana.

TYPE

~~~~~~~~~~~~~~~~~~~~~~

Enumerado que representa los dos tipos posibles de un visor 3D. Los dos tipos son: SPHERE y FLAT.

SWING IMPL

--------------

Este es la implementación de la interfaz de usuario de la librería del visor 3D.

* Project: org.gvsig.view3d/org.gvsig.view3d.swing/org.gvsig.view3d.swing.impl

* Package: or.gvsig.view3d.swing.impl

DefaultView3DManager implements View3DManager

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto del manager View3DManager

DefaultViewPanel3D implements ViewPanel3D

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto de los métodos descritos en la interfaz ViewPanel3D. Esta clase tendrá asociado un MapContext que permitirá obtener información acerca del enfoque, escucha eventos de cambio sobre capas y enfoque, versionado... 

* public DefaultViewPanel3D(MapContext mapContext, TYPE type);

  Constructor que permite instancia un nuevo visor 3D a partir de un MapContext y el tipo. Este constructor accederá a las capas del mapContext para añadirlas al componente de la librería WW. Para añadir una capa al componente WW es necesaria una transformación (``LayerConverter#convertToLayer(layer)``) de la capa gvSIG a una capa WW en base al modo de carga asociado especificado por el usuario.

LayerConverter

~~~~~~~~~~~~~~~~~~~~~~

Interfaz que permite convertir una capa gvSIG en una capa WW o en un modelo de elevación. Este proceso depende del tipo de capa y el modo de carga definido.

* convertToLayer(FLayer layer) : gov.nasa.worldwind.layers.Layer

  Método que a partir de una capa gvSIG obtiene una capa WW.

* convertToElevationModel(FLayer layer) : gov.nasa.worldwind.globes.ElevationModel

  Método que permite convertir una capa de gvSIG en un ElevationModel el cual representa una elevación del terreno.

DefaultLayerConverter

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto de la interfaz LayerConverter. Esta clase permite convertir una capa de gvSIG en un DataRaster genérico el cual permitirá pintar la zona requeridas mediante el método ``FLayer#draw(image,graphics,viewport,scale)``. 

RasterTiledImageLayer extends BasicTiledImageLayer

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación de una capa WW. Entre otras funcionalidades, esta capa gestiona las peticiones de texturas e imágenes que recibe por parte de la aplicación así como la composición de tiles para un sector en concreto, las diferentes resoluciones por nivel de detalle y la creación de tareas para la recuperación / generación de tiles.

Esta capa tiene enlazado un objeto ``DefaultRetrieverFactory`` que le permite a la capa crear objetos ``DefaultRasterRetriever`` para gestionar las peticiones de datos para la creación de tiles.

En principio solo que habrá que sobrescribir los constructores de la clase ``BasicTiledImageLayer`` para que cuando se instancie una capa ``RasterTiledImageLayer`` se instancie también un ``DefaultretrieverFactory`` a partir de los parámetros.

DefaultRetrieverFactory implements RetrieverFactory

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto de un ``RetrieverFactory``. Representa la factoría para la creación de instancias de objetos ``Retriever``.

* createRetriever(AVList params, RetrievalPostProcessor postProcessor) : Retriever

  Instancia una implementación de la interfaz Retriever a partir de una lista de parámetros y un ``RetrievalPostProcessor`` que recibe como parámetro y una instancia local de ``RasterServer``.

DefaultRasterRetriever implements Retriever

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto de ``Retriever``. Esta clase gestiona las peticiones de imágenes que recibe por parte de la capa. Permite configurar tiempos de respuesta como timeouts, tiempo de expiración... además permite saber el estado en que se encuentra el retriever.

DefaultRasterServer implements RasterServer

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implementación por defecto de la interfaz RasterServer. Como su nombre indica esta clase representa un servidor de raster que atiende a las peticiones realizadas por objetos ``Retriever``. Cuando recibe una petición mediante el método ``RasterServer#getRasterAsByteBuffer()`` accede al ``DataRaster`` que tiene asociado obtiene la información que precisa y la devuelve en un objeto de tipo ``java.nio.ByteBuffer``.

* getRasterAsByteBuffer(AVList params) : ByteBuffer

  Obtiene del DataRaster asociado la información definida en los parámetros que recibe y la devuelve en un objeto java.nio.ByteBuffer.

* getSector() : Sector

  Obtiene el sector del data raster asociado.

DefaulDataRasterReaderFactory extends BasicDataRasterReaderFactory

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Factoría que permite la creación de nuestra implementación ``DefaultDataReaderRasterReader`` a partir de un objeto de tipo ``DataStore``.

* findReaderFor(Object source, AVList params) : DataRasterReader

  Obtiene la instancia de ``DataRasterReader`` apropiada para la lectura de la fuente de datos.

DefaultDataRasterReader extends AbstractDataRasterReader

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Permite saber si se puede leer y obtener objetos ``DataRaster`` a partir de DataStore validando lo parámetros y metadatos del almacén.

* canRead(Object source, AVList params) : boolean

  Obtiene si este DataRasterReader es capaz de leer la fuente de datos y crear objetos ``DataRaster``.

* read(Object source, AVList params) throws java.io.IOException : DataRaster[]

  Lee de la fuente de datos y crea objetos ``DataRaster``.

* readMetadata(Object source, AVList params) throws java.io.IOException : AVList

  Obtiene los metadatos asociados a las fuente de datos. Los metadatos varían en función de la fuente y el ``DataRasterReader``.

* isImageryRaster(Object source, AVList params) : boolean

  Obtiene si la fuente de datos es de tipo raster imagen.

* isElevationsRaster(Object source, AVList params) : boolean

  Obtiene si la fuente de datos es de tipo imagen

GvSIGLayerDataRaster implements DataRaster

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Representa información raster. Esta clase recibe peticiones de datos para la generación de tiles por lo que es la encargada de mediante el método ``FLayer#draw()`` de la capa que tiene asociada pintar la sección requerida.

* getWidth() : int

  Obtiene el ancho en píxeles del raster.

* getHeiht() : int

  Obtiene el alto en píxeles del raster.

* drawOnTo(DataRaster canvas) : void

  Copia la información de este raster al especificado por parámetro. Es usado para hacer peticiones de datos sobre zonas determinadas por el tamaño y posición del DataRaster especificado.

* getSubRaster(AVList params) : DataRaster

  A partir de los parámetros que recibe obtiene una sección del raster.

* getSubRaster(int with, int height, Sector sector, AVList params) : DataRaster

  A partir de los parámetros que recibe obtiene una sección del raster.

View3D APP

----------------

Este es el módulo donde se encuentran los diferentes plugins de la librería. Se deben implementar en total cinco plugins. Por un lado, habrá un plugin llamada **org.gvsig.view3d.app.common** el cual contiene todas las extensiones de la librería y los paneles de preferencias de aplicación y de propiedades de vista. Además, debe de tener las dependencias comunes a todas las plataformas y el archivo de configuración "config.xml" para la creación de las entradas de menú y botones en gvSIG. Por otro lado, debe de haber un plugin por cada plataforma el cual no debe de contener ninguna clase debido a que ya se encuentran en el plugin "common". Este plugin solo debe de gestionar las dependencias nativas con la plataforma correspondiente y preparar el empaquetado JAR para que se despliegue como si fuera un plugin normal usando el archivo de configuración del plugin org.gvsig.view3d.app.common así como sus dependencias junto con las dependencias nativas. El resultado esperado debería ser:

* org.gvsig.view3d.app

  - about

  - i18n

  - images

  - lib

    + dependencias comunes

    + dependencias nativas de la plataforma

  - config.xml

  - package.info

Plugin common

~~~~~~~~~~~~~~~~~~~~~~

El plugin common (org.gvsig.view3d.app.common) estará compuesto por tres extensiones: View3DExtension, RefreshView3DExtension y SynchronizeView3DExtension. Además, gestionará la persistencia de las opciones establecidas por el usuario.

* View3DExtension: extensión de Andami asociada a dos acciones: "flat-view3d" y "sphere-view3d". Esta extensión deberá estar siempre visible y activa solo cuando se active una vista 2D con un capa o más. Las dos acciones obtendrán la instancia del View3DSwingManager, crearán el panel, añadirán las capas de la vista activa, y lo mostrarán.

* RefreshView3DExtension: extensión de Andami asociada a la acción: "refresh-view3d". Esta extensión deberá estar visible cuando se active un visor 3D y siempre activa. La extensión obtendrá la instancia de tipo ViewPanel3D y ejecutará la operación ``ViewPanel3D#synchronizeLayers()``.

* SynchronizeView3DExtension: extensión de Andami asociada a la acción: "synchronize-view3d". Esta extensión deberá estar visible cuando se active una vista3D y siempre activa. La extensión obtendrá la instancia de tipo ViewPanel3D y ejecutará la operación ``ViewPanel3D#synchronizeViewPorts()``.

Preferencias

~~~~~~~~~~~~~~~~~~~~~~

El plugin view3D maneja diferentes tipos de preferencias que dependiendo de a que afecten se sitúan en un lugar u otro. Existen tres tipos: preferencias 3D de capa, preferencias de vista y preferencias generales.

Preferencias 3D de capa

________________________

La preferecias de capa afectan solo a una capa. Esta preferencias serán accesibles desde la propiedades de capa del menu contextual del TOC. Para añadir una nueva pestaña a las propiedades de una capa, nuestro panel de propiedades 3D debe extender de la clase ``AbstractThemeManagePage``. La clase que representa la vista se creará dentro de `Plugin common`_ y usuará como modelo la clase `LayerProperties3D`_. A continuación se muestra dos *mockups* de los paneles. El primero representa los parámetros configurables cuando el modo de carga es *Vectorial rasterizada* e *Imagen raster* mientras que el segundo *mockup* representa las opciones configurables cuando el modo de carga es *Modelo ditital del terreno*.

.. image:: images/layer-properties-raster.jpg

Mockup 1: Panel de propiedades cuando el modo de carga es *Vectorial rasterizada* o *Imagen raster*.

Explicación de las propiedades:

* Formato de imagen: formato de los tiles generados. Las opciones disponibles son png, jpg, jpeg y dds.

* Nivel de detalle: numero mínimo y máximo de nivel de detalle. Para el valor óptimo dejar en blanco.

* Resolución nivel cero: resolución en el nivel cero. Por defecto se calcula el valor óptimo teniendo en cuenta el número de niveles de detalle y el tamaño del pixel del raster. En la posición central se situa el valor por defecto, el cual es aumentado o reducido si el usuario establece una resolución baja o alta en el nivel cero.

* Tamaño de tesela: tamaño en pixeles de los tiles generados.

.. image:: images/layer-properties-mdt.jpg

Mockup 2: Panel de propiedades cuando el modo de carga es *Modelo digital del terreno*.

Explicación de las propiedades disponibles:

* Formato de la imagen: formato de los tiles de elevación generados. Se puede elegir entre Bil16 o Bil32.

* Campo altura: al elegir sobre una capa vectorial el modo de cargar MDT, este campo se activa para indicar que campo del FeatureType representa la altura. Si la capa no es de tipo vectorial este campo aparecerá deshabilitado.

* Unidades del valor altura: Unidades del valor alutura. Dos opciones: metros y pies.

* Valor No Data: Valor del No Data. Todos los pixeles con este valor no se representarán en el visor.

* Nivel de detalle: numero mínimo y máximo de nivel de detalle. Para el valor óptimo dejar en blanco.

* Resolución nivel cero: resolución en el nivel cero. Por defecto se calcula el valor óptimo teniendo en cuenta el número de niveles de detalle y el tamaño del pixel del raster. En la posición central se situa el valor por defecto, el cual es aumentado o reducido si el usuario establece una resolución baja o alta en el nivel cero.

* Tamaño de tesela: tamaño en pixeles de los tiles.

Properties3DManager extends AbstractThemeManagerPage

''''''''''''''''''''''''''''''''''''''''''''''''''''

* getName()

  Obtiene el nombre de la pestaña que mostrará el panel. En este caso "3D".

* getPriority()

  Obtiene la priporidad del panel. Cuanta más prioridad más a la izquierda aparecerá.

* acceptAction()

  Método ejecutado cuando el botón "Aceptar" es pulsado. Delega en el método Properties3DManager#applyAction().

* applyAction()

  Método ejecutado cuando el botón "Aplicar" es pulsado. Se debe obtener los valores de los campos del panel de propiedades y actualizar el modelo de la capa correspondiente.

* cancelAction()

  Método ejecutado cuando el botón "Cancelar" es pulsado. Se deben de descartar todos los cambios efectuados sobre el modelo de la capa.

* setModel(FLayer)

  Método ejecutado al abrir el panel de propiedades. Debe de obtener el modelo a partir de la capa y actualizar los campos del panel.

Preferencias 3D de vista

________________________

La preferencias de vista solo afectan a los visores enlazados a esa vista. Estas preferencias serán accesibles desde las propiedades de vista del gestor de documentos. Para añadir una nueva pestaña a las propiedades de vista se debe seguir el siguiente post:

 http://blog.gvsig.org/2015/02/16/anadir-una-pagina-de-propiedades-al-dialogo-de-propiedades-de-la-vista-en-gvsig-2-1/

La clase que representa el panel se creará dentro de `Plugin common`_ y usará como modelo la clase `MapControlProperties3D`_. A continuación se muestra un mockup del panel de propiedades.

.. image:: images/mapcontrol3d-properties.jpg

Mockup3: panel de preferencias 3D de vista

Explicación de los parámetros:

* Exageración vertical visor esférico: muestra la exageración vertical actual del visor esférico. Permite cambiar el valor.

* Exageración vertical visor plano: muestra la exageración vertical actual del visor plano. Permite cambiar el valor. 

* Sincronización automática de enfoques: permite activar o desactivar la sincronización de enfoques automática.

* Sincronización automática de capas: permite activar o desactivas la sincronización de capas cuando se active un visor de forma automática.

* Mostrar capa BlueMarble: permite mostrar u ocultar la capa BlueMarble.

* Mostrar capa NASA Landsat: permite mostrar u ocultar la capa NASA Landsat.

* Mostrar elevación global: permite activar o desactivar la elevación por defecto global.

Preferencias 3D de aplicación

_____________________________

La preferencias de aplicación afectan al plugin 3D en general. Estas preferencias serán accesible desde la preferencias de aplicación de gvSIG. Para añadir un nuevo panel a las preferencias general seguir el siguiente post:

 http://blog.gvsig.org/2015/02/05/como-gestionar-las-preferencias-de-un-plugin-en-gvsig-2-1/

La clase que representa el panel se creará dentro de `Plugin common`_ y usuará como modelo la clase `ViewProperties3D`_. A continuación se muestra un mockup del panel de propiedades.

.. image:: images/view3d-properties.jpg

Mockup4: panel de preferencias 3D generales.

Explicación de los parámetros:

* Tamaño por defecto: tamaño por defecto del visor 3D cuando se crea.

* Mostrar atmósfera: permite mostrar u ocultar la atmósfera.

* Mostrar indicator del norte: permite mostrar u ocultar el indicador del norte.

* Mostrar minimapa: permite mostrar u ocultar el minimapa.

* Mostrar fondo de estrellas: permite mostrar u ocultar el fondo de estrellas.

* Mostrar escala: permite mostrar u ocultar la escala.

* Ruta de la caché: muestra la ruta de la cache. Permite modificar la ruta.

* Borrar caché: permite borra la caché de tiles. Borra la cache de la ruta espeficidada en el momento de accionar el botón.

Persistencia

~~~~~~~~~~~~~~~~~~~~~~

.. note::

   TODO