= 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 [wiki:FDORfcs 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||Haris,Greg,Orest,Mateusz,Bob,Jason,Frank||
||+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.