= 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||Greg Boone [[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||Greg, Orest, Mateusz, Frank, Jason ||
||+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")
}}}

The 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 in a NEW WMS configuration element <!FormatType>:

{{{
<RasterDefinition name="Image">
  <FormatType>image/png;PhotometricInterpretation=PaletteColor</FormatType> 
  ...
</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);
...
}
}}}

=== Notes ===

In order to make the proposed change both backwards and forwards compatible. Configuration files created by the 3.3.0 version of the WMS Provider will continue to write the value of the <Format> element as was previously done in FDO 3.2.2. This would allow continued compatibility with applications written for 3.2.2. At the same time the FDO 3.3 WMS provider configuration file would be modified to contain a new <!FormatType> element that would only be evaluated by the 3.3 version of the WMS provider and subsequent releases. FDO 3.3 would look for <!FormatType> first and if not found evaluate <Format>. FDO 3.2.2 would continue to evaluate <Format>  and ignore <!FormatType>. There would some duplication of information, but applications written on both versions of the WMS Provider should continue to work as designed. The <Format> would be deemed deprecated and removed once forward compatibility support is no longer required.

The resulting 3.3 WMS configuration xml document would take the form of...

{{{
<RasterDefinition name="Image">
  <Format>PNG</Format> // Deprecated element. This one is consistent with FDO 3.2.2
  <FormatType>image/png;PhotometricInterpretation=PaletteColor</FormatType>
...
</RasterDefinition>
}}}


'''For the 3.2.2 FDO WMS configuration API'''....

Calls to 

{{{
void FdoWmsOvRasterDefinition::SetFormatType(FdoWmsOvFormatType value);
}}}

would continue to result in the generation of XML content that contained only the <Format> element as follows 

{{{
<RasterDefinition name="Image">
  <Format>PNG</Format>
  ...
</RasterDefinition>
}}}


Calls to 

{{{
FdoWmsOvFormatType FdoWmsOvRasterDefinition::GetFormatType(void) const;
}}}

would continue to result in the return of the expected !FdoWmsOvFormatType enumeration type 


'''For the 3.3 FDO WMS configuration API'''....

Calls to 

{{{
void SetImageFormat(FdoString* value);
}}}

would result in the generation of XML content that contained both <Format> and <!FormatType>

{{{
<RasterDefinition name="Image">
  <Format>PNG</Format>
  <FormatType>image/png;PhotometricInterpretation=PaletteColor</Format>
  ...
</RasterDefinition>
}}}

where the content of <!FormatType> is the content passed through the call to !SetImageFormat() and the content of <Format> is interpreted and set form the allowed values of <!FormatType>, with a default value of PNG being used no valid interpretation can be made.

Calls to 

{{{
FdoString* GetImageFormat(void) const;
}}}

would result in the return of the expected string set through the call to !SetImageFormat() and/or the value contained in the <!FormatType> element. The content in <Format> would not be returned or evaluated.

== Test Plan ==

Existing unit tests will be expanded to test those changes. Regression testing will be performed against applications using FDO 3.2.2.

== Funding/Resources ==

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