Español

6 Layer configuration in projects

CartoDruid allows the user to parameterize a limited set of options for layers and the TOC. To use the full power of the tool, manual configuration is necessary. This section describes the content and structure of the configuration files and includes practical examples of handling.

6.1 General file structure

For each project configured in CartoDruid, there will be a crtdrdLayer.<project_id>.xml file in the cartodroid/config/ folder. This file stores the reference to the layers that will be displayed in the project and their behavior (display, permissions, operations, etc.).

Tag	Description
WKSLayerConfiguration	Root element of the configuration file. It will have a nested `layers` element, within which the layers are configured with `entry` tags.
layers	Element that groups the list of project layers.
entry	Represents an entry in the TOC. It must have two nested elements, `string`, which will be the layer identifier, and another element with the reference to the specific layer model to use: • `es.jcyl.ita.crtcyl.core.model.VectorialLayer`: to add a vector layer. • `es.jcyl.ita.crtcyl.core.model.RasterLayer`: to add a raster layer.

An example of this file:

<es.jcyl.ita.crtcyl.core.config.WKSLayerConfiguration>
 <layers class="java.util.LinkedHashMap">
 <!-- task layer configuration -->
 <entry>
 <string>tasks</string>
 <es.jcyl.ita.crtcyl.core.model.VectorialLayer> 
 ... 
 </es.jcyl.ita.crtcyl.core.model.VectorialLayer>
 </entry>
 <!-- orthophoto layer configuration -->
 <entry>
 <string>ortofotos_pnoa</string>
 <es.jcyl.ita.crtcyl.core.model.RasterLayer> 
 ... 
 </es.jcyl.ita.crtcyl.core.model.RasterLayer>
 </entry>
 ... 
 </layers>
</es.jcyl.ita.crtcyl.core.config.WKSLayerConfiguration>

6.2 Vector layer configuration

The following table lists the tags that can be used within the es.jcyl.ita.crtcyl.core.model.VectorialLayer element.

Tag	Description
id	Unique layer identifier. It must be a text string without white spaces, containing only letters and digits.
nombre	Visible name of the layer in the TOC.
descripcion	Description of the layer to display in the TOC.
vectorialType	Types of features that the layer stores: must have one of these values: • 10 for MULTIPOINT geometries • 20 for POLYLINE geometries • 30 for MULTIPOLYGON geometries
showOnTOC	Determines if the layer is shown in the TOC layer list.
Display and Symbologies
orden	Position of the layer in the TOC layer list.
zOrder	Determines the overlapping order of the layers when painting. The layer with the highest zOrder appears closest to the user.
range	Indicates the zoom levels at which the layer will be visible. To indicate it, two tags max and min must be nested to indicate the range. Ex: `<range> <min>15</min> <max>21</max> </range>`
labels	If labels should be rendered by default: `true\|false`.
labelRange	Indicates the display ranges of the labels. It is configured with nested `min/max` elements similar to the range tag.
geometrySizeRestriction	Indicates the ranges in square meters allowed for a geometry in this layer. Controls the size of new geometries, size modifications, and divisions. It is configured with nested `min/max` elements similar to the range tag.
labelExpression	SQL expression for label generation. Example: `<labelExpression>`field1 \|\| field2`</labelExpression>`
showArrowHeads	Show orientation arrows of the points of the entities. Only applicable for linear entities. `true\|false`.
symbId	Symbology identifier to apply by default to the geometries of a layer. The symbology must exist in the project file or in `crtdrdSymbologies.xml`.
labelSymbId	Symbology identifier to apply by default to the labels of a layer. The symbology must exist in the project file or in `crtdrdSymbologies.xml`.
symbologyExpression	Expression that will be used to calculate the symbology of the layer entities.
labelSymbologyExpression	Expression that will be used to calculate the symbology of the entity labels.
Permissions and Operations at Layer Level
allowOverlaps	If geometries with overlaps within the same layer can be created. `true\|false`.
canChangeSymbology	If modifying the layer symbology is allowed. `true\|false`.
canCopy	If elements of a layer can be copied to others. `true\|false`.
canCreate	If creating new elements in the layer is allowed. `true\|false`.
canDeleteAll	If the "Delete all elements of the layer" button should be shown in the TOC. `true\|false`.
canDieCut	Determines if the layer entities can be die-cut. `true\|false`.
canEditVertices	If the "Edit vertices" operation should be shown during the editing of a layer geometry. `true\|false`.
canExplode	If using the "Explode geometries" operation in the layer is allowed. `true\|false`.
canPaste	If pasting geometries in the layer is allowed. `true\|false`.
exportable	If exporting or sharing the layer is allowed. If this tag is not included, by default it is `true`.
canSanitize	If the "Clean layer data" button should appear in the TOC. `true\|false`.
canZoomVisibles	If the "Zoom to visible elements" button should be shown in the TOC. `true\|false`.
deletable	If deleting an entity from the layer is allowed. `true\|false`.
editable	If the entities of a layer can be edited (both geometries and attributes). `true\|false`.
identificable	If the identification operation should be active for the layer. `true\|false`.
inspeccionable	If the "Inspection filtering" button should be active when the layer is selected. `true\|false`.
layerEditable	Determines if the layer can be configured (name, description, scale restrictions). `true\|false`.
layerRemovable	If the table can be removed from the TOC. `true\|false`.
searchable	If when showing the list of layer entities, the search filters are shown. `true\|false`.
selectable	If the layer entities can be selected. `true\|false`.
visible	If the layer is visible or not in the TOC. `true\|false`.
Layer Information Source
sources	Defines the data source to locate the database or file in which the layer is found. A layer can include several data sources. Within this tag, one of the following elements will be included. See their specific configuration below: `es.jcyl.ita.crtcyl.client.dao.source.SpatiaLiteServiceDescriptor` `es.jcyl.ita.crtcyl.client.dao.source.RepoSpatiaLiteServiceDescriptor` `es.jcyl.ita.crtcyl.client.dao.source.SpatiaLiteQueryServiceDescriptor`
Form Configuration
alphaEditFinisher	Identifier of the form to use to edit the layer attributes.
attributesClassName	Class that will be used to retrieve the layer information. See data sources section for more information.
editAfterCreation	If after an edit or creation the attribute editing form should be launched. `true\|false`.
valuesFromList (Not recommended)	Relates the form fields that will display a selection dropdown with the file in which the values are. If there is more than one, they are separated with the ";" character. `C_USO_SIGPAC=alegaciones15usoSIGPAC;b_B_SUP_COMPROBADA=siNO;` For the `C_USO_SIGPAC` field of the layer, the values contained in the file `/cartodroid/values/alegaciones15usoSIGPAC.properties` will be displayed. Which will have the format: `TA=TIERRAS ARABLES (TA)` `PR=PASTO ARBUSTIVO (PR)` `PA=PASTO CON ARBOLADO (PA)` Note: since version 0.56 of CartoDroid, it is recommended to configure dropdowns directly from the form configuration. This configuration is still maintained so that previous projects work, but the recommended way to configure dropdowns is indicated in section 7.2.4 - Using Dropdowns in Forms.
sqlIdentify	Query that will be executed for identification. Ex: `<sqlIdentify> c_uso_sigpac as "USO", cap_resultante, st_y(st_centroid(geometry)) as "Latitud", st_x(st_centroid(geometry)) as "Longitud" </sqlIdentify>`
sqlAsListView	Query that will be executed to show the list of entities. Ex: `<sqlAsListView> c_uso_sigpac as "USO", cap_resultante, st_y(st_centroid(geometry)) as "Latitud", st_x(st_centroid(geometry)) as "Longitud" </sqlAsListView>`
definitionQuery	SQL query that will be executed to filter the entities. The text introduced within the tag is applied as a `where` clause within the data retrieval query (filter).

The following example shows the minimum XML that must be defined to configure a vector layer. In this case, it is a polygonal layer (vectorialType=30), the DB file is called plantations.sql and will be found in the cartodroid/data folder. The table that stores the layer is also called plantations and has a geographical index idx_plantations_Geometry.

<layers class="java.util.LinkedHashMap">
<entry>
 <string>layer1</string>
 <es.jcyl.ita.crtcyl.core.model.VectorialLayer>
 <id>plantations</id>
 <name>Plantations</name>
 <vectorialType>30</vectorialType> <!-- polygonal layer -->
 <srs>25830</srs>
 <attributesClassName>es.jcyl.ita.crtdrd.data.DefaultSqlite</attributesClassName>
 <sources>
 <es.jcyl.ita.crtcyl.client.dao.source.SpatiaLiteServiceDescriptor>
 <dbURL>plantations.sqlite</dbURL>
 <dataTable>plantations</dataTable>
 <indexTable>idx_plantations_Geometry</indexTable> 
</es.jcyl.ita.crtcyl.client.dao.source.SpatiaLiteServiceDescriptor>
</sources> 
<symbId>REBECA</symbId>
 <range>
 <max>21</max>
 <min>0</min>
 </range>
 </es.jcyl.ita.crtcyl.core.model.VectorialLayer>
</entry>
</layers>

6.3 Raster layer configuration

Etiqueta	Descripción
id	Unique layer identifier. It must be a text string without white spaces, containing only letters and digits.
nombre	Visible name of the layer in the TOC.
descripcion	Description of the layer to display in the TOC.
showOnTOC	Determines if the layer is shown in the TOC layer list.
Display and Symbologies
orden	Position of the layer in the TOC layer list.
zOrder	Determines the overlapping order of the layers when painting. The layer with the highest zOrder appears in the plane closest to the user.
range	Indicates the zoom levels at which the layer will be visible. To indicate it, two tags max and min must be nested to indicate the range. Ex: `<range> <min>15</min> <max>21</max> </range>`
Permissions and Operations at Layer Level
layerRemovable	If the table can be removed from the TOC. `true\|false`.
visible	If the raster image is visible or not.
Layer Information Source
sources	Defines the data source to locate the database or file in which the layer is found. A layer can include several data sources. Within this tag, one of the following elements will be included. See their specific configuration below: `es.jcyl.ita.crtcyl.client.dao.source.RasterLiteServiceDescriptor` `es.jcyl.ita.crtcyl.client.dao.source.RepoRasterLiteServiceDescriptor` `es.jcyl.ita.crtcyl.client.dao.source.MBTilesServiceDescriptor` `es.jcyl.ita.crtcyl.client.dao.source.RepoMBTilesServiceDescriptor` `es.jcyl.ita.crtcyl.client.dao.source.WMSServiceDescriptor`

6.4 Data source configuration

To define the data source that CartoDruid should use to read the information of a layer, a <sources> tag must be nested within the layer definition tag, whether it is VectorialLayer or RasterLayer.

Within the sources tag, we will be able to define the necessary parameters to locate the data source that contains the cartography, a descriptor. In the following section, we will see the different types of descriptors.

On the other hand, in the layer configuration, in the attributesClassName attribute, CartoDruid is told how to process this descriptor and how to treat the layer geometries when reading them.

6.4.1 Data sources for vector layers

To establish a data source against a vector layer, we must define two things:

The implementation to be used (attributesClassName tag): determines how the geometries will be read.
Data source descriptor: determines how the reference DB files are located.

Select the Geometry Query Implementation

When defining the object that will query the geometries, two parameters must be decided:

a) Geometry treatment:

Regular geometries: CartoDruid will retrieve all geometries that intersect with the current screen (extend or bbox). Each geometry is retrieved complete.
Large geometries: if the spatialite file has extremely large geometries (> 10,000 vertices, we are talking about geometries with an amplitude much higher than the municipal level, etc.), with the previous approach, navigation can be penalized. In these cases, an implementation can be used that retrieves only the part of the geometries shown on the screen and not the complete geometry.

b) DB file path definition:

Single: in this case, we only want to use a single database
Multiple: if we want the entities shown in a layer to come from several database files, CartoDruid can query all the DBs whose file name starts with a specific string.

Using this, for example, we can have a layer of SIGPAC plots, which uses the files of Valladolid and Zamora by putting in the descriptor: xml <dbURL>plots.sqlite</dbURL>

And leaving in the same folder the files plots_va.sqlite and plots_za.sqlite.

This way, CartoDruid searches in that same folder for all files that start with "plots" and have the extension "sqlite" and uses them as data sources for the layer.

Note: it is important to emphasize that multi-implementors can only be used for query operations on entities. If this type of implementor is used and an attempt is made to modify a geometry or its attributes, an error message will be displayed.
Query: if we want the entities to be the result of a query on one or more tables in the DB.

Combining these two parameters, we have the four possible values that we can apply in the <attributesClassName> tag.

	Simple Geometries	Complex Geometries
Single File	DefaultSqlite	LargeSqlite
Multiple Files	MultiSqlite	MultiLargeSqlite
Query	QuerySqlite

Data Source Descriptor

When defining the location of a vector layer, CartoDruid supports three types of descriptors:

File descriptor: in this case, we identify the exact location of the file, with an absolute path on the device or relative to the /cartodroid/data folder.

Tag	Description
SpatiaLiteServiceDescriptor
dbURL	File location, with an absolute path on the device or relative to the `/cartodruid/data` folder.
dataTable	Visible name of the layer in the TOC.
indexTable	Identifies the geographic index associated with the layer.

Example:

<SpatiaLiteServiceDescriptor>
 <dbURL>/storage/emulated/0/cartodroid/data/plantations.sqlite</dbURL>
 <dataTable>plantations</dataTable>
 <indexTable>idx_plantations_Geometry</indexTable>
</SpatiaLiteServiceDescriptor>

Repository reference descriptor: the previous system forces the identification of the file name and complicates the reuse of cartography between different projects and extensions. There is an alternative in which CartoDruid is told the characteristics of the layer, and it is responsible for searching throughout the device's file system for a layer with a name that meets those requirements.

Tag	Description
RepoSpatiaLiteServiceDescriptor
resourceid	File location, with an absolute path on the device or relative to the `/cartodroid/data` folder.
srid	Reference system to be used in the layer.
version	Identifier for the cartographic product version.
dataTable	Visible name of the layer in the TOC.
indexTable	Identifies the geographic index associated with the layer.

With these attributes, CartoDruid will search the entire device for a file named:

<resourceid>_<srid>_<version>.sqlite

For example, for the following layer definition:

<RepoSpatiaLiteServiceDescriptor>
 <resourceid>recintos</resourceid>
 <srid>25830</srid>
 <version>2016</version>
 <dataTable>RECINTOS</dataTable>
 <indexTable>idx_RECINTOS_Geometry</indexTable>
</RepoSpatiaLiteServiceDescriptor>

CartoDruid will attempt to locate a database file with the following name:

recintos_25830_2016.sqlite

If we are using a multi implementor (attribute attributesClassName), CartoDruid will also find all database files that start with "recintos_25830_2016" and have the .sqlite extension.

Query-based descriptor: If we want the data to be the result of an SQL query on one or more tables.

Tag	Description
SpatiaLiteQueryServiceDescriptor
fields	Fields that the query will return.
from	- Table or tables involved. - The table containing the geometries will be associated with the alias "g". - Nested SQL subqueries can also be added.
where (optional)	Filter condition for the query.
groupBy (optional)	Grouping condition for the query.
orderBy (optional)	Ordering condition for the query.
primaryKey	Field that will act as the identifier in the query result. It must be within the list of fields in `fields`.
indexTable	Spatial index of the table containing the geometries.
dbURL	Name of the sqlite file containing the data.

With these attributes, to obtain the entities, CartoDruid will generate a query like this:

SELECT <fields> FROM <from> WHERE <where> GROUB by <groupBy> ORDER BY <orderBy>

Which will be executed on the database specified in <dbURL>

For example, for this layer definition:

<SpatiaLiteQueryServiceDescriptor>
 <fields>c_parvit, group_concat("c_subparvit"), st_union(geometry) as geometry</fields>
 <from>subparcelas g</from>
 <groupBy>c_parvit</groupBy>
 <dbURL>ribera2023.sqlite</dbURL>
 <primaryKey>c_parvit</primaryKey>
 <indexTable>idx_subparcelas_Geometry</indexTable>
</SpatiaLiteQueryServiceDescriptor>

CartoDruid will generate the following query:

SELECT c_parvit, group_concat("c_subparvit"), st_union(geometry) as geometry
FROM subparcelas g
GROUP BY c_parvit;

6.4.2 Data sources for raster layers

For raster layers, it is only necessary to specify a data source descriptor. Each raster format or service supported by CartoDruid will have its own descriptor.

6.4.2.1 Configuration of rasterlite and MBTiles layers

Similarly to vector layers, we will have different descriptors depending on whether we want to reference the database directly by the file name or by referencing its cartographic characteristics:

	File Descriptor	Repository Reference Descriptor
Rasterlite	es.jcyl.ita.crtcyl.client.dao.source. RasterLiteServiceDescriptor	es.jcyl.ita.crtcyl.client.dao.source. RepoRasterLiteServiceDescriptor
MBTiles	es.jcyl.ita.crtcyl.client.dao.source. MBTilesServiceDescriptor	es.jcyl.ita.crtcyl.client.dao.source. RepoMBTilesServiceDescriptor

Rasterlite Layer Configuration with Repository Reference Descriptor

<entry>
 <string>ORTOFOTO</string>
 <es.jcyl.ita.crtcyl.core.model.RasterLayer>
 <descripcion>Ortofotos PNOA 2020</descripcion>
 <id>ORTOFOTO</id>
 <name>Ortofotos 2020</name>
 <sources>
 <es.jcyl.ita.crtcyl.client.dao.source.RepoRasterLiteServiceDescriptor>
 <resourceid>ortos</resourceid>
 <rastersTable>ortofotos</rastersTable>
 <srid>4326</srid>
 <version>2020</version>
 </es.jcyl.ita.crtcyl.client.dao.source.RepoRasterLiteServiceDescriptor>
 </sources>
 <zOrder>15</zOrder>
 <range>
<max>21</max>
<min>16</min>
 </range>
 </es.jcyl.ita.crtcyl.core.model.RasterLayer>
</entry>

MBTiles Layer Configuration with Repository Reference Descriptor

<entry>
 <string>MAPASIGN</string>
 <es.jcyl.ita.crtcyl.core.model.RasterLayer>
 <descripcion>Mapas Topográficos del IGN 1/1.250.000, 1/500.000,1/200.000 y 1/25.000</descripcion>
 <id>MAPASIGN</id>
 <name>Mapas IGN</name>
 <sources>
 <es.jcyl.ita.crtcyl.client.dao.source.RepoMBTilesServiceDescriptor>
 <resourceid>ignmapas</resourceid>
 <srid>4326</srid>
 <version>2016</version>
 </es.jcyl.ita.crtcyl.client.dao.source.RepoMBTilesServiceDescriptor>
 </sources>
 <zOrder>10</zOrder>
 <range>
 <max>15</max>
 <min>6</min>
 </range>
 </es.jcyl.ita.crtcyl.core.model.RasterLayer>
</entry>

6.4.2.2 TMS service (Tile Map Service) configuration

CartoDruid can consume online TMS services, but it can also serve tiles from the device’s file system, as long as they are stored in a structure similar to that maintained by TMS servers (base_cache/nivel_zoom/x/y).

In both cases, the descriptor to be used is the same, es.jcyl.ita.crtcyl.client.dao.source.TMSServiceDescriptor, but if referring to an online service, the baseURI tag will be a URL starting with http, and if referring to a cache on the device, we will specify the path to the cache base.

The invertY tag, determines the direction in which the y-coordinate axis grows when constructing the tile URL. In the TMS standard definition, the tile URL is constructed as:

${baseURI}/nivel_zoom/x/y.${imageExtension}

The y-coordinate starts numbering from the bottom of the map. However, in the case of Google Maps services, the y-axis starts numbering from the top.

CartoDruid covers both cases by simply modifying the value of the invertY tag:

invertY = true: access to Google-style tile maps.
invertY = false: access to standard TMS maps.

For more information about these differences: http://www.maptiler.org/google-maps-coordinates-tile-bounds-projection/

Online TMS Access Configuration

<es.jcyl.ita.crtcyl.client.dao.source.TMSServiceDescriptor>
 <baseURI>http://a.tile.openstreetmap.org</baseURI>
 <imageExtension>png</imageExtension>
 <invertY>false</invertY>
</es.jcyl.ita.crtcyl.client.dao.source.TMSServiceDescriptor>

TMS Cache Access Configuration

<es.jcyl.ita.crtcyl.client.dao.source.TMSServiceDescriptor>
 <baseURI>/sdcard/cartorepo/osm_cache/</baseURI>
 <imageExtension>png</imageExtension>
 <invertY>false</invertY>
</es.jcyl.ita.crtcyl.client.dao.source.TMSServiceDescriptor>

6.4.2.3 WMS service (Web Map Service) configuration

CartoDruid supports a minimal implementation for accessing WMS services. The current version does not support GetCapabilities queries to check the server's capabilities, but almost all parameters of a WMS request can be configured.

Tag	Description
es.jcyl.ita.crtcyl.client.dao.source.WMSServiceDescriptor
layerName	LAYERS parameter of the WMS request indicating the layer or layers to query. If more than one layer is queried at the same time, separate the names with commas.
format	FORMAT parameter, for example image/png.
request	Type of WMS request to be sent to the service, generally it will be GetMap.
EPSG	Reference system to be used.
transparent	Transparency of the returned tile. `True \| false`
quality	QUALITY parameter for the WMS request.
invertAxisOrientation	Indicates whether it is necessary to invert the axis order depending on the coordinate reference system (CRS). For geographic coordinate systems, the value is generally "Y", although there are cases where axes are not inverted and the value should be "N". For projected coordinate systems, it is not necessary to invert the axes, so the value should be "N".
wmsVersion	WMS version to be used.
endpointList	Configuration of the route to the online service.

An example of configuring a layer that queries a WMS service:

<entry>
 <string>pnoa_wms</string>
 <es.jcyl.ita.crtcyl.core.model.RasterLayer>
  <descripcion>PNOA WMS ITACyL</descripcion>
  <id>pnoa_wms</id>
  <name>pnoa_wms</name>
  <sources>
  <wms>
    <layerName>Ortofoto_CyL</layerName>
    <format>image/png</format>
    <request>GetMap</request>
    <EPSG>4326</EPSG>
    <quality>50</quality>
    <invertAxisOrientation>Y</invertAxisOrientation>
    <transparent>true</transparent>
    <wmsVersion>1.3.0</wmsVersion>
    <endPointList>
    <es.jcyl.ita.crtcyl.core.model.source.EndPoint>
      <URL>https://orto.wms.itacyl.es/WMS</URL>
    </es.jcyl.ita.crtcyl.core.model.source.EndPoint>
    </endPointList>
  </wms>
  </sources>
  <zOrder>14</zOrder>
  <range>
  <max>21</max>
  <min>0</min>
  </range>
 </es.jcyl.ita.crtcyl.core.model.RasterLayer>
</entry>