Catalog Mechanism Overview

The Carmenta Engine Catalog mechanism is a framework for providing applications with map configurations and corresponding data in a uniform way. It consists of a specification of a catalog (see below), and an API used by an application to access such a catalog.

Using a catalog like this decouples the application development from the data management, which has several benefits:

The application developer does not need to know exactly which maps will be available on a deployed system. The application can retrieve a list of available maps and let the user select one, or it can rely on the data provider that there is always at least one map available with a certain name or similar.
It is possible to install new map configurations and data into an existing catalog, for instance covering new parts of the world, without changing the application.
Existing map configurations and/or data may be updated without changing the application.
Catalog maps may be packaged into reusable units that can be deployed to many sites, and used by many different applications. A large organization developing and maintaining several different applications may dedicate a part of the organization to produce these map packages. This relieves the application developers from having to manage the map data.
Several applications on the same machine may share the same catalog.

The design of Catalog mechanism is influenced by various OGC (www.opengeospatial.org) standards, such as CS/W (Catalog Service for the Web), WMS (Web Map Service), WMTS (Web Map Tile Service), WCS (Web Coverage Service) and WFS (Web Feature Service). The services and functions provided by a Carmenta Engine catalog may use both local map configurations and data, and existing CS/W, WMS, WMTS, WCS and WFS services. The application uses the exact same API regardless of whether the services are local or remote.

Services provided by a catalog

A catalog provides three different types of services:

A catalog map is a set of map layers that can be added to a Carmenta Engine view, plus related metadata. It may be a complete vector or raster map to be used as a background map in an application, or an overlay map suitable to add on top of another background map. A catalog map may be local (defined by a .px file and local data) or remote (encapsulating a remote OGC WMS or WMTS service).

A catalog dataset is a Carmenta Engine dataset, plus related metadata. The dataset provided by the service can be either just an ordinary Carmenta Engine dataset or an operator chain wrapped as a CatalogDataSet. The dataset may use local data or read data from a remote OGC WCS or WFS service.
A catalog globe is a set of map layers and operators that can be added to a Carmenta Engine GlobeView, plus related metadata. It may hold both the regular 3D layers and the surface layers for a globe view, plus the elevation and auxiliary ground inputs. Currently only local catalog globes are supported.

The API

The API is centered around the Catalog class. The application creates an instance of this class and specifies its location; either a folder on disk, or the URL of a CS/W service.

As of version 5.15, a Catalog instance may load services from multiple locations, by specifying its root directory as a comma-separated list of locations. Both remote and local catalogs may be used together in the same Catalog instance.

The application can use this class to search for catalog maps, datasets and globes, inspect the corresponding metadata, and then load the actual resources. The result of loading a catalog map is a CatalogMap instance, which the application can insert directly as a layer into its Carmenta Engine view. The result of loading a catalog dataset service is a Carmenta Engine DataSet instance, which the application can use for whatever purpose. Loading a globe will return a CatalogGlobe instance, from which the layers and operator can be extracted and added to a globe view.

A catalog map may define a hierarchy of child layers. This hierarchy can be is accessed through CatalogLayer child layers of the CatalogMap instance. These child layers support most of the functionality of regular layers, regardless of whether the layer is defined by a local .px file or from a remote server.

The following C# example shows how the API may be used by an application to load a map and add it as a background layer in its view. The procedure to load a dataset is very similar.

Loading a catalog map

// Load a catalog map and insert as background map
void LoadMap(String catalogDir, View v)
{
	// Create the catalog and find maps marked with keyword "VectorMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"VectorMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetMaps(query);
	if (metadata.Count > 0)
	{
		// Load first matching map and insert as background layer in view
		CatalogMap map = catalog.LoadMap(metadata[0]);
		using (Guard g = new Guard())
		{
			v.Layers.Insert(0, map);
		}
	}
}

And a similar example to load a globe view:

Loading a catalog globe

// Load a catalog globe and populate a globe view
void LoadGlobe(String catalogDir, GlobeView v)
{
	// Create the catalog and find globes marked with keyword "WorldMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"WorldMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetGlobes(query);
	if (metadata.Count > 0)
	{
		// Load first matching globe
		CatalogGlobe globe = catalog.LoadGlobe(metadata[0]);
		using (Guard g = new Guard())
		{
			// Populate globe view. Note that the member may be null.
			if (globe.Layers != null)
				v.Layers.Insert(0, globe.Layers);
			if (globe.SurfaceLayers != null)
				v.SurfaceLayers.Insert(0, globe.SurfaceLayers);
			if (globe.ElevationInput != null)
				v.ElevationInput = globe.ElevationInput;
			if (globe.AuxiliaryGroundInput != null)
				v.AuxiliaryGroundInput = globe.AuxiliaryGroundInput;
			v.SurfaceBackground = globe.SurfaceBackground;
		}
	}
}

The catalog

Local catalog

A local Carmenta Engine catalog is a folder on disk. When a Catalog instance is created, it searches this folder for Carmenta Engine configuration files. All files with a ".px" extension directly under the catalog folder will be loaded and searched for catalog services. Also, if the folder contains a subfolder named "Services", that subfolder will be searched recursively to find additional .px files, which allows for a more flexible organization of the files in the catalog.

The .px files are regular Carmenta Engine configuration files, but a few properties need to be added to define a Catalog map, dataset or globe service. The .px files may also define some essential metadata about the services, such as titles and descriptions. The metadata can be added and edited directly in Carmenta Studio, no other tool is needed. Metadata can also be specified for multiple languages; a separate map service will be created for each language specified in the .px file.

The amount of metadata that can be specified in a .px file is limited. It is possible to extend this by supplementing the .px file with one or more ISO 19139 documents. For each individual catalog map, layer or dataset, a link to an ISO document may be specified. The ISO documents will be read when the .px file is loaded, and some of the information will be extracted and made available to the application. If needed the application may also parse the ISO files to extract even more information. Note though that Carmenta Engine has no support for writing or editing ISO 19139 files.

Configuration files for local maps

The configuration file for a catalog map is best created with Carmenta Studio. There is nothing special with these files, except that some of the objects should be tagged with certain user properties.

The configuration must contain exactly one View or GlobeView instance, with the user property "CatalogMap" set to True. This is in itself enough to define a catalog map or globe; the following steps are optional.
All the child layers of the view will of course be rendered as expected when the application loads the map and adds it to its own application view. However, the application will not be able to access child layers to turn them on or off, adjust opacity properties, enable or disable named styles and so on. But by marking layers in the configuration with the user property "CatalogLayer", the layers will be made accessible to the application. The value of the property should be True, or any non-empty string except "False" and "false". Each such marked layer will turn up as a sublayer to the CatalogMap retrieved by loading the map or globe.
A catalog map or globe may define one or more "public objects". These are just ordinary Carmenta Engine objects from the configuration that the map provider chooses to expose with certain names. For instance, a map providing a line-of-sight layer could make the dataset where the observer is read from a public object with a name like "ObserverDataSet", so that the application can easily find it and insert observers for the line-of-sight analysis. To make a public object, simply set the user property "CatalogPublicObject" to the public name of the object.

ISO metadata documents, as well as all geographic data files used by the configurations may be placed anywhere, even outside the catalog. The recommended way is to keep the .px along with all ISO files referenced by it in a separate sub-folder of the "Services" folder. Keeping geographic data files in the same folder is not recommended though; as the folder is searched recursively during initialization that could increase load times significantly. Instead it is better to keep data files outside "Services", perhaps in a "GeoData" folder in the catalog.

Configuration files for local datasets

A catalog dataset service can be defined in two different ways.

A dataset in a .px file with the user property "CatalogDataSet" will define a catalog dataset service. The dataset must also be marked as public in the configuration. The dataset may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.
An Operator in a .px file with the user property "CatalogDataSet" set to True will define a catalog dataset service. The operator must also be marked as public in the configuration. When that catalog dataset service is loaded, a CatalogDataSet will be returned. The features held by the CatalogDataSet will be the result of the output of the marked Operator.

The dataset and operator chains may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.

User properties

This is a list of all user properties recognized by the Catalog mechanism:

Class	User property	Comment
View, GlobeView	CatalogMap	A boolean attribute indicating that the view should define a catalog map or globe service. If it is False, or not set, the view will be ignored by the catalog.
View	CatalogMapType	A string attribute. Set this to "View" to indicate that the map service is designed as a standalone background map. This information can help the application to load a suitable map, by checking the isView property of the metadata record for the service.
View, GlobeView	CatalogMapKeywords	A comma-separated list of keywords, that will be added to the metadata record for the service, in addition to any keywords read from an ISO 19139 metadata file.
View	CatalogMapExtent	A comma-separated list of four doubles, specifying the extent of the map service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be calculated automatically by querying the datasets in the view. However, doing so could increase catalog initialization time, since all the datasets would need to be initialized.
View, GlobeView	CatalogMapSelectable	A boolean attribute indicating if CatalogMap instances loaded from this service should be initially selectable or not. If the property is set to False or not specified, the maps will not be selectable.
Layer	CatalogLayer	A flag indicating that the layer should be accessible by the application, for instance so it can add the layer to a layer control, allowing the end user may turn the layer on or off. The attribute should be a boolean attribute, but for historical reasons, string values are also recognized. Any value except boolean False, the strings "False" and "false", and the empty string are treated as true.
DataSet, Operator	CatalogDataSet	A flag indicating that the dataset should be available as a dataset service in the catalog. For historical reasons, all values are treated as True. To make a dataset not available as a dataset service in the catalog, remove this user property from it.
DataSet, Operator	CatalogDataSetKeywords	A comma-separated list of keywords, that will be added to the metadata record for the dataset service, in addition to any keywords read from an ISO 19139 metadata file.
DataSet, Operator	CatalogDataSetExtent	A comma-separated list of four doubles, specifying the extent of the dataset service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be set automatically by querying the bounds of the dataset. However, doing so could increase catalog initialization time, since the dataset would need to be initialized.
ResourceObject	CatalogPublicObject	A string attribute, that makes the object available to the application as a public object with the specified name.
View, GlobeView, DataSet, Operator	CatalogRequiredVersion	A Carmenta Engine version number expressed as a string, like "5.8.1" or 5.9". This can be specified to hide a map or a dataset from applications running older Carmenta Engine versions.

Note that even though these are user properties, Carmenta Studio knows about them and will provide editing capabilities for them just as if they were regular properties. See Carmenta Studio User's Guide for more information.

Combining maps into more complex maps

One or more existing map services may be combined into a composite map, by defining a new map service in a new .px file, and using the CatalogLoadLayerSet class to include one or more existing maps.

Remote catalog

A catalog can also be specified directly by a remote OGC CS/W web service, or a Carmenta Server WMC web service. Instantiating a Catalog by specifying a URL to a remote catalog service will create a catalog holding all records of OGC WMS, WMTS, WCS and WFS types listed by the remote service. If an OGC CS/W web service holds records of additional OGC CS/W web services, these will recursively be queried for other records.

Catalog sample

A sample catalog is provided, demonstrating regular 2D and 3D configuration files converted into catalog services.

Catalog Mechanism Overview

Using a catalog like this decouples the application development from the data management, which has several benefits:

The application developer does not need to know exactly which maps will be available on a deployed system. The application can retrieve a list of available maps and let the user select one, or it can rely on the data provider that there is always at least one map available with a certain name or similar.
It is possible to install new map configurations and data into an existing catalog, for instance covering new parts of the world, without changing the application.
Existing map configurations and/or data may be updated without changing the application.
Catalog maps may be packaged into reusable units that can be deployed to many sites, and used by many different applications. A large organization developing and maintaining several different applications may dedicate a part of the organization to produce these map packages. This relieves the application developers from having to manage the map data.
Several applications on the same machine may share the same catalog.

Services provided by a catalog

A catalog provides three different types of services:

A catalog map is a set of map layers that can be added to a Carmenta Engine view, plus related metadata. It may be a complete vector or raster map to be used as a background map in an application, or an overlay map suitable to add on top of another background map. A catalog map may be local (defined by a .px file and local data) or remote (encapsulating a remote OGC WMS or WMTS service).

A catalog dataset is a Carmenta Engine dataset, plus related metadata. The dataset provided by the service can be either just an ordinary Carmenta Engine dataset or an operator chain wrapped as a CatalogDataSet. The dataset may use local data or read data from a remote OGC WCS or WFS service.
A catalog globe is a set of map layers and operators that can be added to a Carmenta Engine GlobeView, plus related metadata. It may hold both the regular 3D layers and the surface layers for a globe view, plus the elevation and auxiliary ground inputs. Currently only local catalog globes are supported.

The API

The API is centered around the Catalog class. The application creates an instance of this class and specifies its location; either a folder on disk, or the URL of a CS/W service.

The following C# example shows how the API may be used by an application to load a map and add it as a background layer in its view. The procedure to load a dataset is very similar.

Loading a catalog map

// Load a catalog map and insert as background map
void LoadMap(String catalogDir, View v)
{
	// Create the catalog and find maps marked with keyword "VectorMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"VectorMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetMaps(query);
	if (metadata.Count > 0)
	{
		// Load first matching map and insert as background layer in view
		CatalogMap map = catalog.LoadMap(metadata[0]);
		using (Guard g = new Guard())
		{
			v.Layers.Insert(0, map);
		}
	}
}

And a similar example to load a globe view:

Loading a catalog globe

// Load a catalog globe and populate a globe view
void LoadGlobe(String catalogDir, GlobeView v)
{
	// Create the catalog and find globes marked with keyword "WorldMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"WorldMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetGlobes(query);
	if (metadata.Count > 0)
	{
		// Load first matching globe
		CatalogGlobe globe = catalog.LoadGlobe(metadata[0]);
		using (Guard g = new Guard())
		{
			// Populate globe view. Note that the member may be null.
			if (globe.Layers != null)
				v.Layers.Insert(0, globe.Layers);
			if (globe.SurfaceLayers != null)
				v.SurfaceLayers.Insert(0, globe.SurfaceLayers);
			if (globe.ElevationInput != null)
				v.ElevationInput = globe.ElevationInput;
			if (globe.AuxiliaryGroundInput != null)
				v.AuxiliaryGroundInput = globe.AuxiliaryGroundInput;
			v.SurfaceBackground = globe.SurfaceBackground;
		}
	}
}

The catalog

Local catalog

Configuration files for local maps

The configuration must contain exactly one View or GlobeView instance, with the user property "CatalogMap" set to True. This is in itself enough to define a catalog map or globe; the following steps are optional.
All the child layers of the view will of course be rendered as expected when the application loads the map and adds it to its own application view. However, the application will not be able to access child layers to turn them on or off, adjust opacity properties, enable or disable named styles and so on. But by marking layers in the configuration with the user property "CatalogLayer", the layers will be made accessible to the application. The value of the property should be True, or any non-empty string except "False" and "false". Each such marked layer will turn up as a sublayer to the CatalogMap retrieved by loading the map or globe.
A catalog map or globe may define one or more "public objects". These are just ordinary Carmenta Engine objects from the configuration that the map provider chooses to expose with certain names. For instance, a map providing a line-of-sight layer could make the dataset where the observer is read from a public object with a name like "ObserverDataSet", so that the application can easily find it and insert observers for the line-of-sight analysis. To make a public object, simply set the user property "CatalogPublicObject" to the public name of the object.

Configuration files for local datasets

A catalog dataset service can be defined in two different ways.

A dataset in a .px file with the user property "CatalogDataSet" will define a catalog dataset service. The dataset must also be marked as public in the configuration. The dataset may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.
An Operator in a .px file with the user property "CatalogDataSet" set to True will define a catalog dataset service. The operator must also be marked as public in the configuration. When that catalog dataset service is loaded, a CatalogDataSet will be returned. The features held by the CatalogDataSet will be the result of the output of the marked Operator.

The dataset and operator chains may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.

User properties

This is a list of all user properties recognized by the Catalog mechanism:

Class	User property	Comment
View, GlobeView	CatalogMap	A boolean attribute indicating that the view should define a catalog map or globe service. If it is False, or not set, the view will be ignored by the catalog.
View	CatalogMapType	A string attribute. Set this to "View" to indicate that the map service is designed as a standalone background map. This information can help the application to load a suitable map, by checking the isView property of the metadata record for the service.
View, GlobeView	CatalogMapKeywords	A comma-separated list of keywords, that will be added to the metadata record for the service, in addition to any keywords read from an ISO 19139 metadata file.
View	CatalogMapExtent	A comma-separated list of four doubles, specifying the extent of the map service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be calculated automatically by querying the datasets in the view. However, doing so could increase catalog initialization time, since all the datasets would need to be initialized.
View, GlobeView	CatalogMapSelectable	A boolean attribute indicating if CatalogMap instances loaded from this service should be initially selectable or not. If the property is set to False or not specified, the maps will not be selectable.
Layer	CatalogLayer	A flag indicating that the layer should be accessible by the application, for instance so it can add the layer to a layer control, allowing the end user may turn the layer on or off. The attribute should be a boolean attribute, but for historical reasons, string values are also recognized. Any value except boolean False, the strings "False" and "false", and the empty string are treated as true.
DataSet, Operator	CatalogDataSet	A flag indicating that the dataset should be available as a dataset service in the catalog. For historical reasons, all values are treated as True. To make a dataset not available as a dataset service in the catalog, remove this user property from it.
DataSet, Operator	CatalogDataSetKeywords	A comma-separated list of keywords, that will be added to the metadata record for the dataset service, in addition to any keywords read from an ISO 19139 metadata file.
DataSet, Operator	CatalogDataSetExtent	A comma-separated list of four doubles, specifying the extent of the dataset service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be set automatically by querying the bounds of the dataset. However, doing so could increase catalog initialization time, since the dataset would need to be initialized.
ResourceObject	CatalogPublicObject	A string attribute, that makes the object available to the application as a public object with the specified name.
View, GlobeView, DataSet, Operator	CatalogRequiredVersion	A Carmenta Engine version number expressed as a string, like "5.8.1" or 5.9". This can be specified to hide a map or a dataset from applications running older Carmenta Engine versions.

Combining maps into more complex maps

One or more existing map services may be combined into a composite map, by defining a new map service in a new .px file, and using the CatalogLoadLayerSet class to include one or more existing maps.

Remote catalog

Catalog sample

A sample catalog is provided, demonstrating regular 2D and 3D configuration files converted into catalog services.

Catalog Mechanism Overview

Using a catalog like this decouples the application development from the data management, which has several benefits:

The application developer does not need to know exactly which maps will be available on a deployed system. The application can retrieve a list of available maps and let the user select one, or it can rely on the data provider that there is always at least one map available with a certain name or similar.
It is possible to install new map configurations and data into an existing catalog, for instance covering new parts of the world, without changing the application.
Existing map configurations and/or data may be updated without changing the application.
Catalog maps may be packaged into reusable units that can be deployed to many sites, and used by many different applications. A large organization developing and maintaining several different applications may dedicate a part of the organization to produce these map packages. This relieves the application developers from having to manage the map data.
Several applications on the same machine may share the same catalog.

Services provided by a catalog

A catalog provides three different types of services:

A catalog map is a set of map layers that can be added to a Carmenta Engine view, plus related metadata. It may be a complete vector or raster map to be used as a background map in an application, or an overlay map suitable to add on top of another background map. A catalog map may be local (defined by a .px file and local data) or remote (encapsulating a remote OGC WMS or WMTS service).

A catalog dataset is a Carmenta Engine dataset, plus related metadata. The dataset provided by the service can be either just an ordinary Carmenta Engine dataset or an operator chain wrapped as a CatalogDataSet. The dataset may use local data or read data from a remote OGC WCS or WFS service.
A catalog globe is a set of map layers and operators that can be added to a Carmenta Engine GlobeView, plus related metadata. It may hold both the regular 3D layers and the surface layers for a globe view, plus the elevation and auxiliary ground inputs. Currently only local catalog globes are supported.

The API

The API is centered around the Catalog class. The application creates an instance of this class and specifies its location; either a folder on disk, or the URL of a CS/W service.

The following C# example shows how the API may be used by an application to load a map and add it as a background layer in its view. The procedure to load a dataset is very similar.

Loading a catalog map

// Load a catalog map and insert as background map
void LoadMap(String catalogDir, View v)
{
	// Create the catalog and find maps marked with keyword "VectorMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"VectorMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetMaps(query);
	if (metadata.Count > 0)
	{
		// Load first matching map and insert as background layer in view
		CatalogMap map = catalog.LoadMap(metadata[0]);
		using (Guard g = new Guard())
		{
			v.Layers.Insert(0, map);
		}
	}
}

And a similar example to load a globe view:

Loading a catalog globe

// Load a catalog globe and populate a globe view
void LoadGlobe(String catalogDir, GlobeView v)
{
	// Create the catalog and find globes marked with keyword "WorldMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"WorldMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetGlobes(query);
	if (metadata.Count > 0)
	{
		// Load first matching globe
		CatalogGlobe globe = catalog.LoadGlobe(metadata[0]);
		using (Guard g = new Guard())
		{
			// Populate globe view. Note that the member may be null.
			if (globe.Layers != null)
				v.Layers.Insert(0, globe.Layers);
			if (globe.SurfaceLayers != null)
				v.SurfaceLayers.Insert(0, globe.SurfaceLayers);
			if (globe.ElevationInput != null)
				v.ElevationInput = globe.ElevationInput;
			if (globe.AuxiliaryGroundInput != null)
				v.AuxiliaryGroundInput = globe.AuxiliaryGroundInput;
			v.SurfaceBackground = globe.SurfaceBackground;
		}
	}
}

The catalog

Local catalog

Configuration files for local maps

The configuration must contain exactly one View or GlobeView instance, with the user property "CatalogMap" set to True. This is in itself enough to define a catalog map or globe; the following steps are optional.
All the child layers of the view will of course be rendered as expected when the application loads the map and adds it to its own application view. However, the application will not be able to access child layers to turn them on or off, adjust opacity properties, enable or disable named styles and so on. But by marking layers in the configuration with the user property "CatalogLayer", the layers will be made accessible to the application. The value of the property should be True, or any non-empty string except "False" and "false". Each such marked layer will turn up as a sublayer to the CatalogMap retrieved by loading the map or globe.
A catalog map or globe may define one or more "public objects". These are just ordinary Carmenta Engine objects from the configuration that the map provider chooses to expose with certain names. For instance, a map providing a line-of-sight layer could make the dataset where the observer is read from a public object with a name like "ObserverDataSet", so that the application can easily find it and insert observers for the line-of-sight analysis. To make a public object, simply set the user property "CatalogPublicObject" to the public name of the object.

Configuration files for local datasets

A catalog dataset service can be defined in two different ways.

A dataset in a .px file with the user property "CatalogDataSet" will define a catalog dataset service. The dataset must also be marked as public in the configuration. The dataset may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.
An Operator in a .px file with the user property "CatalogDataSet" set to True will define a catalog dataset service. The operator must also be marked as public in the configuration. When that catalog dataset service is loaded, a CatalogDataSet will be returned. The features held by the CatalogDataSet will be the result of the output of the marked Operator.

The dataset and operator chains may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.

User properties

This is a list of all user properties recognized by the Catalog mechanism:

Class	User property	Comment
View, GlobeView	CatalogMap	A boolean attribute indicating that the view should define a catalog map or globe service. If it is False, or not set, the view will be ignored by the catalog.
View	CatalogMapType	A string attribute. Set this to "View" to indicate that the map service is designed as a standalone background map. This information can help the application to load a suitable map, by checking the isView property of the metadata record for the service.
View, GlobeView	CatalogMapKeywords	A comma-separated list of keywords, that will be added to the metadata record for the service, in addition to any keywords read from an ISO 19139 metadata file.
View	CatalogMapExtent	A comma-separated list of four doubles, specifying the extent of the map service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be calculated automatically by querying the datasets in the view. However, doing so could increase catalog initialization time, since all the datasets would need to be initialized.
View, GlobeView	CatalogMapSelectable	A boolean attribute indicating if CatalogMap instances loaded from this service should be initially selectable or not. If the property is set to False or not specified, the maps will not be selectable.
Layer	CatalogLayer	A flag indicating that the layer should be accessible by the application, for instance so it can add the layer to a layer control, allowing the end user may turn the layer on or off. The attribute should be a boolean attribute, but for historical reasons, string values are also recognized. Any value except boolean False, the strings "False" and "false", and the empty string are treated as true.
DataSet, Operator	CatalogDataSet	A flag indicating that the dataset should be available as a dataset service in the catalog. For historical reasons, all values are treated as True. To make a dataset not available as a dataset service in the catalog, remove this user property from it.
DataSet, Operator	CatalogDataSetKeywords	A comma-separated list of keywords, that will be added to the metadata record for the dataset service, in addition to any keywords read from an ISO 19139 metadata file.
DataSet, Operator	CatalogDataSetExtent	A comma-separated list of four doubles, specifying the extent of the dataset service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be set automatically by querying the bounds of the dataset. However, doing so could increase catalog initialization time, since the dataset would need to be initialized.
ResourceObject	CatalogPublicObject	A string attribute, that makes the object available to the application as a public object with the specified name.
View, GlobeView, DataSet, Operator	CatalogRequiredVersion	A Carmenta Engine version number expressed as a string, like "5.8.1" or 5.9". This can be specified to hide a map or a dataset from applications running older Carmenta Engine versions.

Combining maps into more complex maps

One or more existing map services may be combined into a composite map, by defining a new map service in a new .px file, and using the CatalogLoadLayerSet class to include one or more existing maps.

Remote catalog

Catalog sample

A sample catalog is provided, demonstrating regular 2D and 3D configuration files converted into catalog services.

Catalog Mechanism Overview

Using a catalog like this decouples the application development from the data management, which has several benefits:

The application developer does not need to know exactly which maps will be available on a deployed system. The application can retrieve a list of available maps and let the user select one, or it can rely on the data provider that there is always at least one map available with a certain name or similar.
It is possible to install new map configurations and data into an existing catalog, for instance covering new parts of the world, without changing the application.
Existing map configurations and/or data may be updated without changing the application.
Catalog maps may be packaged into reusable units that can be deployed to many sites, and used by many different applications. A large organization developing and maintaining several different applications may dedicate a part of the organization to produce these map packages. This relieves the application developers from having to manage the map data.
Several applications on the same machine may share the same catalog.

Services provided by a catalog

A catalog provides three different types of services:

A catalog map is a set of map layers that can be added to a Carmenta Engine view, plus related metadata. It may be a complete vector or raster map to be used as a background map in an application, or an overlay map suitable to add on top of another background map. A catalog map may be local (defined by a .px file and local data) or remote (encapsulating a remote OGC WMS or WMTS service).

A catalog dataset is a Carmenta Engine dataset, plus related metadata. The dataset provided by the service can be either just an ordinary Carmenta Engine dataset or an operator chain wrapped as a CatalogDataSet. The dataset may use local data or read data from a remote OGC WCS or WFS service.
A catalog globe is a set of map layers and operators that can be added to a Carmenta Engine GlobeView, plus related metadata. It may hold both the regular 3D layers and the surface layers for a globe view, plus the elevation and auxiliary ground inputs. Currently only local catalog globes are supported.

The API

The API is centered around the Catalog class. The application creates an instance of this class and specifies its location; either a folder on disk, or the URL of a CS/W service.

The following C# example shows how the API may be used by an application to load a map and add it as a background layer in its view. The procedure to load a dataset is very similar.

Loading a catalog map

// Load a catalog map and insert as background map
void LoadMap(String catalogDir, View v)
{
	// Create the catalog and find maps marked with keyword "VectorMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"VectorMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetMaps(query);
	if (metadata.Count > 0)
	{
		// Load first matching map and insert as background layer in view
		CatalogMap map = catalog.LoadMap(metadata[0]);
		using (Guard g = new Guard())
		{
			v.Layers.Insert(0, map);
		}
	}
}

And a similar example to load a globe view:

Loading a catalog globe

// Load a catalog globe and populate a globe view
void LoadGlobe(String catalogDir, GlobeView v)
{
	// Create the catalog and find globes marked with keyword "WorldMap"
	Catalog catalog = new Catalog(catalogDir);
	CatalogQuery query = new CatalogQuery("keyword(\"WorldMap\") and language = \"eng\"");
	CatalogMetadataCollection metadata = catalog.GetGlobes(query);
	if (metadata.Count > 0)
	{
		// Load first matching globe
		CatalogGlobe globe = catalog.LoadGlobe(metadata[0]);
		using (Guard g = new Guard())
		{
			// Populate globe view. Note that the member may be null.
			if (globe.Layers != null)
				v.Layers.Insert(0, globe.Layers);
			if (globe.SurfaceLayers != null)
				v.SurfaceLayers.Insert(0, globe.SurfaceLayers);
			if (globe.ElevationInput != null)
				v.ElevationInput = globe.ElevationInput;
			if (globe.AuxiliaryGroundInput != null)
				v.AuxiliaryGroundInput = globe.AuxiliaryGroundInput;
			v.SurfaceBackground = globe.SurfaceBackground;
		}
	}
}

The catalog

Local catalog

Configuration files for local maps

The configuration must contain exactly one View or GlobeView instance, with the user property "CatalogMap" set to True. This is in itself enough to define a catalog map or globe; the following steps are optional.
All the child layers of the view will of course be rendered as expected when the application loads the map and adds it to its own application view. However, the application will not be able to access child layers to turn them on or off, adjust opacity properties, enable or disable named styles and so on. But by marking layers in the configuration with the user property "CatalogLayer", the layers will be made accessible to the application. The value of the property should be True, or any non-empty string except "False" and "false". Each such marked layer will turn up as a sublayer to the CatalogMap retrieved by loading the map or globe.
A catalog map or globe may define one or more "public objects". These are just ordinary Carmenta Engine objects from the configuration that the map provider chooses to expose with certain names. For instance, a map providing a line-of-sight layer could make the dataset where the observer is read from a public object with a name like "ObserverDataSet", so that the application can easily find it and insert observers for the line-of-sight analysis. To make a public object, simply set the user property "CatalogPublicObject" to the public name of the object.

Configuration files for local datasets

A catalog dataset service can be defined in two different ways.

A dataset in a .px file with the user property "CatalogDataSet" will define a catalog dataset service. The dataset must also be marked as public in the configuration. The dataset may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.
An Operator in a .px file with the user property "CatalogDataSet" set to True will define a catalog dataset service. The operator must also be marked as public in the configuration. When that catalog dataset service is loaded, a CatalogDataSet will be returned. The features held by the CatalogDataSet will be the result of the output of the marked Operator.

The dataset and operator chains may be specified in a configuration file of its own, or in a configuration file together with a catalog map service or other dataset services.

User properties

This is a list of all user properties recognized by the Catalog mechanism:

Class	User property	Comment
View, GlobeView	CatalogMap	A boolean attribute indicating that the view should define a catalog map or globe service. If it is False, or not set, the view will be ignored by the catalog.
View	CatalogMapType	A string attribute. Set this to "View" to indicate that the map service is designed as a standalone background map. This information can help the application to load a suitable map, by checking the isView property of the metadata record for the service.
View, GlobeView	CatalogMapKeywords	A comma-separated list of keywords, that will be added to the metadata record for the service, in addition to any keywords read from an ISO 19139 metadata file.
View	CatalogMapExtent	A comma-separated list of four doubles, specifying the extent of the map service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be calculated automatically by querying the datasets in the view. However, doing so could increase catalog initialization time, since all the datasets would need to be initialized.
View, GlobeView	CatalogMapSelectable	A boolean attribute indicating if CatalogMap instances loaded from this service should be initially selectable or not. If the property is set to False or not specified, the maps will not be selectable.
Layer	CatalogLayer	A flag indicating that the layer should be accessible by the application, for instance so it can add the layer to a layer control, allowing the end user may turn the layer on or off. The attribute should be a boolean attribute, but for historical reasons, string values are also recognized. Any value except boolean False, the strings "False" and "false", and the empty string are treated as true.
DataSet, Operator	CatalogDataSet	A flag indicating that the dataset should be available as a dataset service in the catalog. For historical reasons, all values are treated as True. To make a dataset not available as a dataset service in the catalog, remove this user property from it.
DataSet, Operator	CatalogDataSetKeywords	A comma-separated list of keywords, that will be added to the metadata record for the dataset service, in addition to any keywords read from an ISO 19139 metadata file.
DataSet, Operator	CatalogDataSetExtent	A comma-separated list of four doubles, specifying the extent of the dataset service in WGS84 longitude/latitude coordinates (west, south, east, north). If this property is not specified, the information will be set automatically by querying the bounds of the dataset. However, doing so could increase catalog initialization time, since the dataset would need to be initialized.
ResourceObject	CatalogPublicObject	A string attribute, that makes the object available to the application as a public object with the specified name.
View, GlobeView, DataSet, Operator	CatalogRequiredVersion	A Carmenta Engine version number expressed as a string, like "5.8.1" or 5.9". This can be specified to hide a map or a dataset from applications running older Carmenta Engine versions.

Catalog Mechanism Overview

In this article

Catalog Mechanism Overview

In this article

Catalog Mechanism Overview

In this article

Catalog Mechanism Overview

In this article