Draw object import-export

The ImportExport MariaGDK component offers functionality to convert draw objects to and from different data formats. The following internal Maria GDK drivers are used:

• GDAL - The GDAL-driver uses the OGR part of GDAL (Geospatial Data Abstraction Library) to read and write to different formats. Information about GDAL can be found at https://gdal.org/. GDAL is accessed using the C# nuget components GDAL and GDAL.Native See also GdalOgrInCsharp for more information.
• NVG - The NVG driver supports the Nato Vector Graphics format. The XML-based data objects are stored as files with .xml extension. Information about NVG can be found at https://nisp.nw3.dk/standard/nato-tide-nvg.html

How to use the component

The ImportExport component can be used as a stand-alone assembly, but a number of MariaGDK assemblies are referenced and must be included in the runtime environment.

Assembly

The ImportExport assembly is TPG.DrawObjects.Data.ImportExport.dll.

NuGet

The GDAL functionality in the library requires the following NuGet components: GDAL and GDAL.Native. These must be included in the runtime environment either as NuGet references or as assemblies.

Import

The import of a data source is done using the DataSourceImport class which is an implementation of the IDataSourceImport interface. The import steps are:

1. Create an import instance
2. Open the datasource
3. If the datasource was open successfully, convert the datasource's objects to draw objects.
4. Retrieve the created draw objects from the import object for further external processing.

Data import drivers

The import object handles datasources using internal drivers in the ImportExport component dedicated to different data formats. Available drivers can be obtained using DataSourceImport::DriverNames.

GDAL-driver

The GDAL driver reads data sources recognized by the GDAL system (Geospatial Data Abstraction Library). The GDAL system is based on open source code and more information about GDAL can be found at www.gdal.org.

Supported data formats

GDAL has internal drivers to support different data formats like kml, kmz, shp etc. When opening a data source, GDAL will automatically select the proper internal driver or fail to open the data source if unknown data format. Supported data formats can be obtained using the SourceGdalImportDriver::DataFormats.

NVG-driver

The driver reads NVG files which are xml-formatted. Information about NVG can be found at nisp.nw3.dk/standard/nato-tide-nvg.html

Open a datasource

The datasource is opened by trying the available Import component drivers to see which driver recognizes the data source. Alternative, a specific import driver can be specified and the data source can be opened using this driver.

DataSourceImport::OpenDataSource(string filename) =

Returns true if any of the data import drivers successfully opens the given datasource.

DataSourceImport::SelectDriver(string drivername)

Returns the given driver and the datasource can then be opened directly through the driver's OpenDataSource(string filename).

Converting the datasource

The datasource's content can be imported after the datasource has been successfully opened. The convert process is modal and can be started by the import object or directly using the selected driver.

DataSourceImport::ConvertFromSource

Returns true if the convert process was successully. The resulting converted draw objects can be retrieved using DataSourceImport::DrawObjects.

DataSourceImport::DrawObjects

Returns the converted draw objects.

Controlling the convert process

The convert process can be controlled by the DataSourceImport::ImportSetup property. Typical options is selecting specific geometry types, how to import attributes etc.

DataSourceImport::ImportSetup

This property is used to control the import process and must be set before the import is started. Available options are defined in DataSourceImportBase::ImportSettingEnum.

ISourceImportDriver::DriverImportSettings

This property controls how imported draw objects are handled. Available options are defined in the DriverImportSetting enum.

ISourceImportDriver::DrawObjectSelectionObject

This property can be used to select objects from the imported datasource using conditions.

Getting information about the converted process

The convert process is modal, but information about errors and general information can be obtained from the import object after the convert process.

Converted error information

Any information about unknown geometries etc can be obtained from DataSourceImport::ErrorInformation.

Logging the import process

Setting DataSourceImport::LogConvert as true will log information about the convert process. The information can then be obtained from DataSourceImport::LogInformation. By default, the logging is disabled.

Styling

Styles defined in the datasource will, by default, be attached on the created draw objects. These styles can be combined or overwritten with manually defined styles. The draw style for the imported draw objects is controlled by values in the IDrawObjectData::Fields property.

Import styles from datasource

The import process will automatically convert any styles in the data source objects to equivalent IDrawObjectData::Fields values. Note: only certain data formats support built-in styles. Examples are KML and KMZ.

Setting styles on imported draw objects

The styles can be set directly or based on draw object attributes.

Setting styles based on attribute conditions

The styling of imported objects can be controlled using ISourceImportDriver.DrawObjectStyleObject which is set up directly or loaded from a xml file. Finally, the styling is activated with IDrawObjectStyling.StylingActivated. The attributes for each created draw object will decide which style that shall be attached to the draw object. This property must be set before the import process is started.

A thematic map can be created using fieldconditions to set line styles etc. based on draw object properties. Objects which do not match these conditions can either be ignored or imported with standard draw setup. This is controlled by setting ISourceImportDriver.DrawObjectStyleSettings with options defined in DrawObjectStyleSetting.

The following xml example will set line width and line line color based on the property extrude.

<?xml version="1.0" encoding="utf-8" ?> 
<styleset name="Default">
  <stylecategory name="DrawObjects">    
    <style>
      <fieldcondition field="extrude" op="Eq" value="1" />
      
      <compositeitem name="Fill">
        <valueitem name="ForegroundColor" value="127,127,127,127" />
        <valueitem name="BackgroundColor" value="127,100,127,200" />
        <valueitem name="Style" value="VerticalLine" />
      </compositeitem>

      <compositeitem name="Line">
        <valueitem name="Color" value="255,0,0,255"/>
        <valueitem name="Width" value="14" />
        <valueitem name="OutlineColor" value="255, 99, 71, 255" />
        <valueitem name="DashStyle" value="DashDot" />
        <valueitem name="BeginScaleStep" value="1.1" />
        <valueitem name="EndScaleStep" value="1.3" />
      </compositeitem> 
      
      <compositeitem name="CenterLine">
        <valueitem name="Width" value="3" />
        <valueitem name="Color" value="100, 50, 23, 190" />
        <valueitem name="DashStyle" value="DashDotDot"/>
      </compositeitem>

      <compositeitem name="Symbol">
        <valueitem name="Type" value="SymbolPoint" />
        <valueitem name="Code" value="003837a5-fbec-4b0e-98af-cfd48808aa42:8b68fc34_GENERAL/Dot" />
        <valueitem name="MinDynamicScale" value="1000" />
        <valueitem name="MaxDynamicScale" value="200000" />
        <valueitem name="CustomDynamicScale" value="1000:0.3,20000:0.5" />      
      </compositeitem>

      <compositeitem name="Scaling">
        <valueitem name="MinMapScale" value="0" />
        <valueitem name="MaxMapScale" value="2500000" />
      </compositeitem>

      <compositeitem name="Alignment">    
        <valueitem name="TextAlignment" value="2" />
        <valueitem name="TextPosition" value="1" />
      </compositeitem>

      <compositeitem name="DefaultFont">
        <valueitem name="Bold" value="true"/>
        <valueitem name="Italic" value="false"/>
        <valueitem name="Underline" value="false"/>
        <valueitem name="Strikethrough" value="false"/>
        <valueitem name="Font" value="Arial"/>
        <valueitem name="Size" value="12"/>
        <valueitem name="Color" value="0,0,0,255"/>
        <valueitem name="BackgroundColor" value="255,255,255,127"/>
        <valueitem name="OutlineColor" value="255,255,255,127"/>
        <valueitem name="MinFontSize" value="10"/>
        <valueitem name="MinFontMapScale" value="1000"/>
        <valueitem name="MaxFontMapScale" value="10000"/>
        <valueitem name="CustomFontScale" value="true"/>
      </compositeitem>
    </style>

    <style>
      <fieldcondition field="extrude" op="Eq" value="2" />

      <compositeitem name="Line">
        <valueitem name="Width" value="6" />
        <valueitem name="Color" value="100,0,50,255"/>
      </compositeitem>     
    </style>
  </stylecategory>
</styleset>

Setting a specific style on converted draw objects

The method DataSourceImport::ConvertFromSource(IDataSourceAttachedStyle style) will apply the given style to all imported draw objects. By default, the given style will not overwrite existing style values in the created draw objects. This can be overriden by the DataSourceImport::IgnoreSourceStyle property.

Style already imported draw objects

Draw styles are defined by creating style objects for line, polygon etc. These style objects can then be attached (transferred) to existing draw objects.

Geometry styles

All styles have a StyleChanged property that is true is the corresponding property has been set. This is to prevent setting unneccessary values in the IDrawObjectData::Fields property.

DataSourceLineStyle

The following line styles can be set: LineColor, LineWidth, LineDashStyle and LineOpacity.

DataSourceFillStyle

The following fill styles can be set: Fill, FillColor, FillOpacity and FillPattern.

DataSourceSymbolStyle

The following symbol styles can be set: SymbolCode and SymbolType.

DataSourceTextStyle

The following text styles can be set: Weight, Color, TextAlign, VerticalAlign, FontSize, FontFamily, FontStyle and TextAttribute.

Applying styles to draw objects

Styles can be applied to draw objct using the DataSourceImportBase::AttachStyle method. Only style properties with corresponding StyleChanged set to true will be converted to equivalent Fields value. If equivalent value already exist on the draw object, it will only be overwritten if the method's overwriteExistingStyle is true.

Any issues when applying the style will be added to errorInformation.

Extract style definitions from datasource

Some datasource formats, for example kml-files, may contain styles for the geometry objects. This can be obtained from the property ISourceImportDriver::DatasourceStyleDatasourceStyle. The return xml-string will be empty if no defined styles.

Export

The export of draw obejcts to a new external data source is done using the DataSourceExport object which is an implementation of the IDataSourceExport interface. The export steps are:

1. Create export object.
2. Create datasource using the filepath.
3. If the datasource was created successfully, convert the draw objects to exported objects.

Data export drivers

The export object handles datasources using internal drivers in the ImportExport component dedicated to different data formats. Available drivers can be obtained using DataSourceExport::DriverNames.

GDAL-driver

GDAL has internal drivers to support different data formats like kml, kmz, shp etc. When creating a data source, GDAL will automatically select the proper internal driver or fail to create the data source if unknown data format. Supported GDAL data formats can be obtained using the SourceGdalImportDriver::DataFormats. It is important to realize that GDAL will not be able to create new datasources for all these data formats.

The method DataSourceExport::ExportSupportedDataFormats returns data formats that has been tested to successfully create new datasources.

NVG-driver

The NVG driver exports draw objects to a NVG file.

Create a datasource

The export object will create the datasource by trying the available Export component drivers to see which driver recognizes the requested datasource. Alternative, a specific driver can be selected and the data source can be created with this driver.

DataSourceExport::CreateDataSource(string path)

Returns true if any of the data export drivers successfully created the requested datasource.

DataSourceExport::SelectSourceExportDriver(string drivername)

Returns the requested driver and the datasource can then be created directly through the driver using ISourceExportDriver::CreateDataSource(string dataFormatName, string path).

Exporting the draw objects

The draw objects can be exported after a successfully creation of the datasource. The export process is modal and can be executed by the export object or directly by the driver.

DataSourceExport::ConvertDrawObjectData(List<IDrawObjectData> drawObjects, bool logConvert)

Export the given draw objects to the already created datasource. Return true if the export was successful.

Controlling the export process

The convert process can be controlled by the DataSourceExport::ExportSetting property. Typical options is selecting specific geometry types, how to export attributes etc.

Creating the datasource

Some datasources has limitations on field attributes or field values. This can be controlled with the DataSourceExport properties FieldNameMaxLength, FieldValueWidth and FieldWidths.

ExportSettingEnum

Available options for IDataSourceExport::ExportSetting.

Getting information about the export process

The export process is modal, but information about errors and general information can be obtained from the export object after the export process.

Converted error information

Any information about unknown geometries etc can be obtained using DataSourceExport::ErrorInformation.

Logging the convert process

Setting DataSourceExport::LogExport to true will log information about the export process. The information can be obtained using DataSourceExport::LogInformation. By default, the logging is disabled.