User guide for ImageML Plugin usage in ConE
===========================================

Introduction
------------
This page describes how to use the ConE ImageML plug-in.
The plug-in defines the ImageML Implementation Markup Language, which provides
image conversion from BMP to MBM and SVG to MIF using the ``mifconv`` and
``bmconv`` tools.

XML namespace and file extension
--------------------------------

- Namespace: ``http://www.s60.com/xml/imageml/1``
- File extension: ``imageml``

ImageML elements
----------------

The ImageML XML element model is drawn out as a UML class diagram below:

  .. image:: imageml.jpg

output
^^^^^^

The ``output`` element defines an output file for image conversion. A single
ImageML implementation may contain multiple ``output`` elements.

**Attributes**

  * *file* - Output file location, for example ``resource/apps/image.mbm``.
    The output tool used to perform the conversion is deduced from the file
    extension: bmconv for .mbm and mifconv for .mif. The file location can
    also come from a ConfML setting using the ``${}`` notation.
  * *tool* - Override for the path to the tool to use. This is mainly useful
    for testing, in production use the bmconv and mifconv tools should be in PATH.
  * *palette* - Specifies a .pal file to use for MBM conversion.
  * *tooldir* - Override for the location of the bmconv and mifconv tools.
    This is mainly useful for testing, in production use the bmconv and mifconv
    tools should be in PATH.
  * *extraparams* - Optional attribute that can be used to pass extra parameters 
    for tool. For details see bmconv and mifconv documentation. E.g. "/V3" defines
    for mifconv the format version of SVG binary conversion. If not defined value
    forces Svgtbinencode to use the default platform specific value. 
    Options for mifconv /V parameter are:

.. list-table::

    - - *Value*
      - *Format type*
    - - /V1
      - BGR / float encoding
    - - /V2
      - BGR / fixed point encoding
    - - /V3
      - RGB / fixed point encoding
    - - /V4
      - RGB / float encoding
    - - /V5
      - NVG encoding


**Example**

.. code-block:: xml

    <output file="resource/apps/startup.mbm">
    
    <output file="resource/apps/startup.mif">
    
    <!--
    The drive letter is automatically stripped, and the output location
    is the same as in the example above
    -->
    <output file="Z:\\resource\\apps\\startup.mif">
    
    <output file="${StartupSettings.StartupAnimationPath}">


input
^^^^^

The ``input`` element defines a single input file for image conversion, or a
directory from which input files are selected based on regular expression
patterns. One ``output`` element may contain multiple ``input`` elements.

An input element must specify a file using the ``file`` attribute or a directory
using the ``dir`` attribute, but not both.

**Attributes**

  * *file* - Input file from the configuration project content. Can also be
    a ConfML setting reference using the ``${}`` notation.
  * *dir* - Directory for input files from the configuration project content.
    Can also be a ConfML setting reference using the ``${}`` notation.
  * *depth* - Color depth switch passed to bmconv for the file(s) specified by
    the current ``input`` element, does nothing if mifconv is used.
    Can also be a ConfML setting reference using the ``${}`` notation.
  * *optional* - If ``true``, then the input dir or file may be empty and
    no error is reported. Can be used to e.g. specify an optional mask bitmap.

**Examples**

.. code-block:: xml

    <input file="images/icon.svg"/>
    
    <input file="images/image.bmp" depth="c24"/>
    
    <input file="images/image_mask.bmp" depth="c1" optional="true"/>
    
    <input file="${TestFeature.BmpFile.localPath}" depth="${TestFeature.BmpDepth}"/>
    
    <input dir="images/svg_files/">
        <include pattern="svg$"/>
        <exclude pattern=".svn"/>
    </input>


include and exclude
^^^^^^^^^^^^^^^^^^^

The ``include`` and ``exclude`` elements specify regular expressions for
selecting input files from an input directory.

**Attributes**

  * *pattern* - The regular expression used to include or exclude files
  
**Examples**

.. code-block:: xml

    <include pattern="svg$"/>
    <include pattern="bmp$"/>
    <exclude pattern=".svn"/>

Setting references 
------------------

The setting references that an ImageML implementation uses are determined as
follows:

  * If any ``input`` elements contain setting references in their ``file``
    or ``dir`` attributes, those are the setting references used by the
    ImageML implementation.
  * If there are no setting references in those attributes, setting references
    are considered to be irrelevant, and the implementation is always run
    regardless of setting reference filtering.

See the examples in the section below.

ImageML examples
----------------

All the examples shown in this section can also be downloaded:

    * :download:`imageml-example-project.zip`

You need to have bmconv and mifconv somewhere in your path for generation to
work. To generate output from the project simply run::

    > cone generate -p imageml-example-project.zip

Or unzip (e.g. to ``imageml-example-project``) and run::
    
    > cd imageml-example-project
    imageml-example-project\> cone generate


Simple image conversion using a single input file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: examples/simple.imageml
   :language: xml

Setting references of this implementation: None (irrelevant)

Simple image conversion with ConfML setting references
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: examples/with_refs.imageml
   :language: xml

Setting references of this implementation:

    - ``TestSettings.ConeInputBmp.localPath``
    - ``TestSettings.IconInputSvg.localPath``

MBM conversion using multiple input files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: examples/multi_input.imageml
   :language: xml

Setting references of this implementation: None (irrelevant)

MBM conversion using an optional mask file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: examples/bmp_and_optional_mask.imageml
   :language: xml

Setting references of this implementation:

    - ``TestSettings.ConeInputBmp.localPath``
    - ``TestSettings.ConeInputBmpMask.localPath``

FAQ
---

This will be updated based on the questions.