/2.1/trunk/doc/dt-visor-3d.rst - Diff - gvSIG 3D - gvSIG

Revision 484 2.1/trunk/doc/dt-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.
     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.
     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:
-...
     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.
     Si la capa es de tipo raster tiene las siguientes propiedades:
     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.
     * Modo de carga elevación: permite indicar si el raster es de tipo elevación o no.
     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()``.
-...
       Asigna en que unidades se encuentra el valor de elvación. Solo acepta dos unidades: metros y pies.
     RasterLayerProperties3D extends LayerProperties3D
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     RasterLayerProperties3D implements LayerProperties3D
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     Clase que representa la propiedades 3D de una capa raster. De momento no tiene ninguna propiedad específica.
     VectorialLayerProperties3D extends LayerProperties3D
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     VectorialLayerProperties3D implements LayerProperties3D
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     Clase que representa la propiedades 3D de una capa vectorial.
-...
       Asgina que atributo del *FeatureType* contiene la información de elevación. Solo se aplica cuando la capa es de tipo vectorial.
     .. note::
       Falta añadir la propiedades de vista y propiedades generales.
     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.
     * 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.
     * 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
     ---------
-...
     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.
-...
       Crea un objeto `MapControl3D`_ a partir del MapContext y el tipo.
     * 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.
     * 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``.
     .. note::
       Falta especificar las propiedades relacionadas con la vista, las propiedades generales y sus interfaces.
     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() : Cancellable
     * getCancellable() : Cancellabl
       Obtiene el objeto compartido el cual permite cancelar todas las ordenes de pintado que se están ejecutando en un momento dado.
-...
     * getType() : TYPE
       Obtiene el tipo del visor. Devuelve un objeto enum que puede ser TPYE.SPHERE o TYPE.FLAT (ver `TYPE`_).
       Obtiene el tipo del visor. Devuelve un objeto enum que puede ser ``TPYE.SPHERE`` o ``TYPE.FLAT`` (ver `TYPE`_).
     * getVerticalExaggeration() : double
-...
     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.
     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.
     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.
     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.
       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.
     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.
     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
-...
     DefaulDataRasterReaderFactory extends BasicDataRasterReaderFactory
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     Factoría que permite la creación de nuestra implementación DefaultDataReaderRasterReader a partir de un objeto de tipo DataStore.
     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.
       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.
     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.
       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
       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.
       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
-...
     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
     ~~~~~~~~~~~~~~~~~~~~~~

Also available in: Unified diff

Application: gvSIG desktop » gvSIG 3D

Revision 484 2.1/trunk/doc/dt-visor-3d.rst