FDO RFC 10 - Modify WMS override API to support additional parameters and bit depth variations?

This page contains a request for comments document (RFC) for the FDO Open Source project. More FDO RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date
Last Modified	Klain Qin Timestamp
Author	Klain Qin
RFC Status	Draft
Implementation Status	Under Development
Proposed Milestone	3.3.0.0
Assigned PSC guide(s)	Greg Boone
Voting History
+1
+0
-0
-1

Overview

The purpose is to add support to additional parameters and bit-depth variations to image formats.

Currently, WMS Provider supports four image formats: image/png, image/jpg, image/tif, image/gif. They are defined as:

enum FdoWmsOvFormatType{

    FdoWmsOvFormatType_Png = 0,
    FdoWmsOvFormatType_Tif,
    FdoWmsOvFormatType_Jpg,
    FdoWmsOvFormatType_Gif
};

This enhancement will support additional parameters and bit-depth variations such as:

image/png; PhotometricInterpretation=PaletteColor
image/png; PhotometricInterpretation=RGB
image/png; mode=24bit

Proposed Solution

WMS Override API will accept a string instead of the enumeration for image format. It will only accept server defined format strings that contain ‘png’, ‘tiff’, ‘jpeg’ or ‘gif’ in their definitions.

For example, by calling SetImageFormat("image/png; PhotometricInterpretation=PaletteColor"), WMS Provider will return raster stream in palette model. And by calling SetImageFormat("image/png; PhotometricInterpretation=RGB"), the raster stream will be returned in RGB model.

In this way, WMS Provider could fully make use of the server capability to support different bit-depth. These additional parameters will go into the configuration file like:

<RasterDefinition name="Image">
  <Format>image/png;PhotometricInterpretation=PaletteColor</Format> 
  ...
</RasterDefinition>

However, still only four image file formats are supported: png, tiff, jpeg, and gif. If the user passed a string that contains other image formats like "bmp", "wbmp", etc, an exception will be thrown.

This following section outlines the necessary code changes in the unmanaged and managed code.

Unmanaged Code

/// \brief
///
/// The FdoWmsOvRasterDefinition class defines the physical overrides for a raster property in a WMS FDO schema.
class FdoWmsOvRasterDefinition : public FdoPhysicalElementMapping
{
...
    /// \brief
    /// Gets the format type in which the WMS image will be generated.
    /// 
    /// \remarks
    /// Allowed map formats are "picture" formats . Picture formats constitute 
    /// a rectangular pixel array of fixed size. Picture formats include file types such 
    /// as Portable Network Graphics (PNG), Joint Photographics Expert Group (JPEG) 
    /// and file types such as Tagged Image File Format (TIFF).
    /// 
    /// \return
    /// Returns the WMS image format.
    /// 
    FDOWMS_API FdoString* GetImageFormat(void) const;

    /// \brief
    /// Sets the format type in which the WMS image will be generated.
    /// 
    /// \remarks
    /// Allowed map formats are "picture" formats . Picture formats constitute 
    /// a rectangular pixel array of fixed size. Picture formats include file types such 
    /// as Portable Network Graphics (PNG), Joint Photographics Expert Group (JPEG) 
    /// and file types such as Tagged Image File Format (TIFF).
    /// 
    /// \return
    /// Returns nothing.
    /// 
    FDOWMS_API void SetImageFormat(FdoString* value);
...
}

Managed Code

/// <summary> 
/// The FdoWmsOvRasterDefinition class defines the physical overrides for a raster property in a WMS FDO schema.
/// </summary>
public __gc class OvRasterDefinition : public NAMESPACE_OSGEO_FDO_COMMANDS_SCHEMA::PhysicalElementMapping
{
...
    /// <summary>Gets the format type in which the WMS image will be generated.</summary>
    /// <returns>Returns the WMS format type.</returns> 
    /// <remarks>Allowed map formats are "picture" formats . Picture formats constitute 
    /// a rectangular pixel array of fixed size. Picture formats include file types such 
    /// as Portable Network Graphics (PNG), Joint Photographics Expert Group (JPEG) 
    /// and file types such as Tagged Image File Format (TIFF).</remarks> 
    __property System::String* get_ImageFormat();

    /// <summary>Sets the format type in which the WMS image will be generated.</summary>
    /// <returns>Returns nothing.</returns> 
    /// <remarks>Allowed map formats are "picture" formats . Picture formats constitute 
    /// a rectangular pixel array of fixed size. Picture formats include file types such 
    /// as Portable Network Graphics (PNG), Joint Photographics Expert Group (JPEG) 
    /// and file types such as Tagged Image File Format (TIFF).</remarks> 
    __property System::Void set_ImageFormat(System::String* value);
...
}

Implications

• The change is backwards compatible with existing config files. Existing config files will be readable by the updated WMS provider.

• The change is not forwards compatible. New config files created by the updated provider are not readable by earlier versions of the WMS provider.

This is a problem because earlier versions of the WMS override API will do a strict check on parsing <Image> ... </Image> in the configuration file. It could only recognize "png", "jpg", "Gif", or "tif", as they are hard-coded in the code:

    static FdoString* g_WmsImageFormatPng                   = L"PNG";
    static FdoString* g_WmsImageFormatTif                   = L"TIF";
    static FdoString* g_WmsImageFormatJpg                   = L"JPG";
    static FdoString* g_WmsImageFormatGif                   = L"GIF";

Test Plan

Existing unit tests will be expanded to test those changes.

Funding/Resources

Autodesk to provide resources / funding to update WMS Override API.