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 y la arquitectura de plugins.

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 (View3DExtension, una única extensión para dos acciones). Pero antes de crear el visor 3D, el usuario debe indicar como se deben de cargar las capas mediante las propiedades de cada capa (si no se indica se cargarán con los modos de carga por defecto). 

Las capas dependiendo del tipo puede cargarse del siguiente modo:

* Las capas vectoriales pueden cargarse como "Capa vectorial rasterizada" (LOADMODE.RASTERIZEDVEC) o "Capa vectorial con simbología 3D" (LOADMODE.VECTORIAL). El modo de carga "Capa vectorial rasterizada" toma la información vectorial y crea una imagen (proceso de rasterización) y la carga en el visor 3D. El modo de carga "Capa vectorial con simbología 3D" carga la capa usando simbología 3D. Este último modo de carga no se aboradará a priori. Si el usuario no indica el modo de carga de una capa vectorial por defecto se cargará como "Capa vectorial rasterizada".

* Las capas raster puede cargarse como "Capa raster como imagen" (LOADMODE.RASTER) o "Capa raster como elevación" (LOADMODE.ELEVATION). El modo de carga "Capa raster como imagen" toma el raster y lo representa teselado en el visor 3D mientras que el modo de carga "Capa raster como elevación" toma el raster e interpreta los datos para crear una elevación en la superficie del terreno. Si el usuario no indica el modo de carga de una capa raster por defecto se cargará como "Capa raster como imagen".

Una vez definidos los modos de carga de las capas, el usuario debe pulsar sobre uno de los botones para crear un visor. Al pulsar, el plugin obtendrá la vista activa en ese momento. Con la vista activa se obtendrá el MapContext mediante IView#getMapControl().getMapContext(). Una vez obtenido el MapContext se creará un nuevo visor mediante View3DManager#createView3DPanel(mapContext, type). El tipo dependerá de la acción ejecutada por el usuario. Al crear el visor, este automáticamente añade las capas del MapContext mediante View3DPanel#add(layer, loadMode). Sólo queda invocar el método View3DPanel#show() para mostrar el visor.

Además de la extensión para la creación de visores, el usuario también dispondrá de una extensión llamada RefreshView3DExtension para la actualización de los datos del visor activo con los posibles cambios efectuados sobre la vista 2D. La extensión ejecutará el método View3DPanel#reloadLayers().

Y finalmente, existirá una última extensión llamada SynchronizeView3DExtension que permitirá al usuario sincronizar los enfoques de la vista 2D y el visor 3D asociado a la vista. Se accederá al ViewPort del MapContext asociado para sincronizarlo con el enfoque del visor 3D. 

Para más información acerca de las funcionalidades consultar el análisis funcional indicado en `Introducción`_.

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: or.gvsig.view3d.swing.api

View3DManager

********************

* createView3DPanel(MapContext theMapContext, TYPE type) : View3DPanel

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

View3DPanel

****************************

Define el API del visor 3D.

* add(FLayer layer, LOADMODE loadMode) : void

A partir de la capa que recibe como parámetro y en base al modo de carga obtiene la capa equivalente en la librería World Wind y la añade al visor. 

* 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.

* remove(FLayer layer) : void

Elimina la capa equivalente de la recibida como parámetro y actualiza el visor.

* removeAll() : void

Elimina todas las capas cargadas y actualiza el visor.

* 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.

* show() : void

Invoca al WindowManager para mostrar el visor en modo ventana.

* showAtmosphere() : void

Muestra la atmósfera si el visor es esférico.

* showNortIndicator() : void

Muestra el indicador del norte.

* showMiniMap() : void

Muestra el minimapa.

* showScale() : void

Muestra la escala de la capa.

* showStarBackgroundLayer() : void

Muestra el fondo de estrellas.

* synchronizeViewPorts() : void

Obtiene el ViewPort de la vista y realiza las transformaciones necesarias para el enfoque del visor 3D muestra la misma región. Hay que tener en cuenta si la opción "Animación en la sincronización de enfoques" esta marcada o no. En caso de que este marcada la sincronización se debe animar, en caso contrario, no.

* hideAtmosphere() : void

Oculta la atmósfera en visores esféricos.

* hideMiniMap() : void

Oculta el minimapa.

* hideStarBackgroundLayer() : void

Oculta el fondo de estrellas.

* hideNorthIndicator() : void

Oculta el indicador del norte.

* hideScale() : void

Oculta la escala del mapa.

TYPE

*************

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

LOADMODE

**************

Enumerado que representa los posibles modos de carga de las capas. Los modos de carga son cuatro: ELEVATION, RASTER, RASTERIZEDVEC, VECTORIAL.

AbstractView3DPanel extends JPanel implements View3DPanel

************************************************************

Clase abstracta que extiende de JPanel. Esta clase abstracta no implementa ninguno de lo métodos de la interfaz View3DPanel, sólo implementa el código relacionado con la instanciación y creación de los componentes de la vista. La implementación por defecto del API recae sobre la clase DefaultView3DPanel.

LayerConverter

****************

Interfaz que permite convertir una capa gvSIG en una capa WW. Este proceso dependende del tipo de capa y el modo de carga definido.

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

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

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

DefaultView3DPanel extends AbstractView3DPanel

***************************************************

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

* public DefaultView3DPanel(MapContext mapContext, TYPE type);

Constructor que permite instancia un nuevo visor 3D a partir de un MapContext y el tipo. Este constructor invocará a super(type) para la creación e inicialización de los componentes del visor. Además, también 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#convert(layer)) de la capa gvSIG a una capa WW en base al modo de carga asociado espeficicado por el usuario.

DefaultRasterLayerConverter implements LayerConverter

**********************************************************

Implementación por defecto para convertir capas FLyrRaster de gvSIG en capas SurfaceImageLayer de WW. Se usará el API del objeto FLyrRaster para la conversión. El objeto SurfaceImageLayer permite añadir imágenes mediante dos modos: ruta al archivo y como BufferedImage. Al añadir una imagen a una capa SurfaceImageLayer, la librería WW automáticamente obtiene el proveedor necesario para la lectura de la imagen, la carga y la tesela por lo que no es necesario realizar ninguna acción previa antes de añadir la imagen. La carga de la imagen se debe realizar en un hilo nuevo para no bloquear gvSIG usando TaskStatus. 

Se puede encontrar un ejemplo de como cargar imagenes en una capa SurfaceImageLayer:

 http://worldwind31.arc.nasa.gov/svn/tags/2.0.0/WorldWind/src/gov/nasa/worldwindx/examples/SurfaceImageViewer.java

.. note::

 A priori parace más sencillo usar el path de la imagen que obtener un objecto BufferedImage a partir de la capa raster.

DefaultWMSLayerConverter implements LayerConverter

**********************************************************

.. note::

  TODO en fases posteriores

DefaultElevationLayerConverter implements LayerConverter

***********************************************************

.. note::

  TODO en fases posteriores

DefaultVectorialLayerConverter implements LayerConverter

***********************************************************

.. note::

  TODO en fases posteriores

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. Ademas, 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 dependendencias 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 asi 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: "create-flat-view3d" y "create-spherical-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 View3DPanel y ejecutará la operación View3DPanel#reloadLayers().

* 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 View3DPanel y ejecutará la operación View3DPanel#synchronizeViewPorts().

Persistencia

*************

.. note::

  TODO en fases posteriores. Definir panales y gestión de preferencias.

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 imagenes, objectos 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 ususario 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 View3DPanel 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 espeficios para crear un WorldWindowGLJPanel esférico o plano. Esta configuración se realiza al instanciar un objecto View3DPanel. 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.