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.