3
|
1 |
User guide for ImageML Plugin usage in ConE
|
|
2 |
===========================================
|
|
3 |
|
|
4 |
Introduction
|
|
5 |
------------
|
|
6 |
This page describes how to use the ConE ImageML plug-in.
|
|
7 |
The plug-in defines the ImageML Implementation Markup Language, which provides
|
|
8 |
image conversion from BMP to MBM and SVG to MIF using the ``mifconv`` and
|
|
9 |
``bmconv`` tools.
|
|
10 |
|
|
11 |
XML namespace and file extension
|
|
12 |
--------------------------------
|
|
13 |
|
|
14 |
- Namespace: ``http://www.s60.com/xml/imageml/1``
|
|
15 |
- File extension: ``imageml``
|
|
16 |
|
|
17 |
ImageML elements
|
|
18 |
----------------
|
|
19 |
|
|
20 |
The ImageML XML element model is drawn out as a UML class diagram below:
|
|
21 |
|
|
22 |
.. image:: imageml.jpg
|
|
23 |
|
|
24 |
output
|
|
25 |
^^^^^^
|
|
26 |
|
|
27 |
The ``output`` element defines an output file for image conversion. A single
|
|
28 |
ImageML implementation may contain multiple ``output`` elements.
|
|
29 |
|
|
30 |
**Attributes**
|
|
31 |
|
|
32 |
* *file* - Output file location, for example ``resource/apps/image.mbm``.
|
|
33 |
The output tool used to perform the conversion is deduced from the file
|
|
34 |
extension: bmconv for .mbm and mifconv for .mif. The file location can
|
|
35 |
also come from a ConfML setting using the ``${}`` notation.
|
|
36 |
* *tool* - Override for the path to the tool to use. This is mainly useful
|
|
37 |
for testing, in production use the bmconv and mifconv tools should be in PATH.
|
|
38 |
* *palette* - Specifies a .pal file to use for MBM conversion.
|
|
39 |
* *tooldir* - Override for the location of the bmconv and mifconv tools.
|
|
40 |
This is mainly useful for testing, in production use the bmconv and mifconv
|
|
41 |
tools should be in PATH.
|
|
42 |
* *extraparams* - Optional attribute that can be used to pass extra parameters
|
|
43 |
for tool. For details see bmconv and mifconv documentation. E.g. "/V3" defines
|
|
44 |
for mifconv the format version of SVG binary conversion. If not defined value
|
|
45 |
forces Svgtbinencode to use the default platform specific value.
|
|
46 |
Options for mifconv /V parameter are:
|
|
47 |
|
|
48 |
.. list-table::
|
|
49 |
|
|
50 |
- - *Value*
|
|
51 |
- *Format type*
|
|
52 |
- - /V1
|
|
53 |
- BGR / float encoding
|
|
54 |
- - /V2
|
|
55 |
- BGR / fixed point encoding
|
|
56 |
- - /V3
|
|
57 |
- RGB / fixed point encoding
|
|
58 |
- - /V4
|
|
59 |
- RGB / float encoding
|
|
60 |
- - /V5
|
|
61 |
- NVG encoding
|
|
62 |
|
|
63 |
|
|
64 |
**Example**
|
|
65 |
|
|
66 |
.. code-block:: xml
|
|
67 |
|
|
68 |
<output file="resource/apps/startup.mbm">
|
|
69 |
|
|
70 |
<output file="resource/apps/startup.mif">
|
|
71 |
|
|
72 |
<!--
|
|
73 |
The drive letter is automatically stripped, and the output location
|
|
74 |
is the same as in the example above
|
|
75 |
-->
|
|
76 |
<output file="Z:\\resource\\apps\\startup.mif">
|
|
77 |
|
|
78 |
<output file="${StartupSettings.StartupAnimationPath}">
|
|
79 |
|
|
80 |
|
|
81 |
input
|
|
82 |
^^^^^
|
|
83 |
|
|
84 |
The ``input`` element defines a single input file for image conversion, or a
|
|
85 |
directory from which input files are selected based on regular expression
|
|
86 |
patterns. One ``output`` element may contain multiple ``input`` elements.
|
|
87 |
|
|
88 |
An input element must specify a file using the ``file`` attribute or a directory
|
|
89 |
using the ``dir`` attribute, but not both.
|
|
90 |
|
|
91 |
**Attributes**
|
|
92 |
|
|
93 |
* *file* - Input file from the configuration project content. Can also be
|
|
94 |
a ConfML setting reference using the ``${}`` notation.
|
|
95 |
* *dir* - Directory for input files from the configuration project content.
|
|
96 |
Can also be a ConfML setting reference using the ``${}`` notation.
|
|
97 |
* *depth* - Color depth switch passed to bmconv for the file(s) specified by
|
|
98 |
the current ``input`` element, does nothing if mifconv is used.
|
|
99 |
Can also be a ConfML setting reference using the ``${}`` notation.
|
|
100 |
* *optional* - If ``true``, then the input dir or file may be empty and
|
|
101 |
no error is reported. Can be used to e.g. specify an optional mask bitmap.
|
|
102 |
|
|
103 |
**Examples**
|
|
104 |
|
|
105 |
.. code-block:: xml
|
|
106 |
|
|
107 |
<input file="images/icon.svg"/>
|
|
108 |
|
|
109 |
<input file="images/image.bmp" depth="c24"/>
|
|
110 |
|
|
111 |
<input file="images/image_mask.bmp" depth="c1" optional="true"/>
|
|
112 |
|
|
113 |
<input file="${TestFeature.BmpFile.localPath}" depth="${TestFeature.BmpDepth}"/>
|
|
114 |
|
|
115 |
<input dir="images/svg_files/">
|
|
116 |
<include pattern="svg$"/>
|
|
117 |
<exclude pattern=".svn"/>
|
|
118 |
</input>
|
|
119 |
|
|
120 |
|
|
121 |
include and exclude
|
|
122 |
^^^^^^^^^^^^^^^^^^^
|
|
123 |
|
|
124 |
The ``include`` and ``exclude`` elements specify regular expressions for
|
|
125 |
selecting input files from an input directory.
|
|
126 |
|
|
127 |
**Attributes**
|
|
128 |
|
|
129 |
* *pattern* - The regular expression used to include or exclude files
|
|
130 |
|
|
131 |
**Examples**
|
|
132 |
|
|
133 |
.. code-block:: xml
|
|
134 |
|
|
135 |
<include pattern="svg$"/>
|
|
136 |
<include pattern="bmp$"/>
|
|
137 |
<exclude pattern=".svn"/>
|
|
138 |
|
|
139 |
Setting references
|
|
140 |
------------------
|
|
141 |
|
|
142 |
The setting references that an ImageML implementation uses are determined as
|
|
143 |
follows:
|
|
144 |
|
|
145 |
* If any ``input`` elements contain setting references in their ``file``
|
|
146 |
or ``dir`` attributes, those are the setting references used by the
|
|
147 |
ImageML implementation.
|
|
148 |
* If there are no setting references in those attributes, setting references
|
|
149 |
are considered to be irrelevant, and the implementation is always run
|
|
150 |
regardless of setting reference filtering.
|
|
151 |
|
|
152 |
See the examples in the section below.
|
|
153 |
|
|
154 |
ImageML examples
|
|
155 |
----------------
|
|
156 |
|
|
157 |
All the examples shown in this section can also be downloaded:
|
|
158 |
|
|
159 |
* :download:`imageml-example-project.zip`
|
|
160 |
|
|
161 |
You need to have bmconv and mifconv somewhere in your path for generation to
|
|
162 |
work. To generate output from the project simply run::
|
|
163 |
|
|
164 |
> cone generate -p imageml-example-project.zip
|
|
165 |
|
|
166 |
Or unzip (e.g. to ``imageml-example-project``) and run::
|
|
167 |
|
|
168 |
> cd imageml-example-project
|
|
169 |
imageml-example-project\> cone generate
|
|
170 |
|
|
171 |
|
|
172 |
Simple image conversion using a single input file
|
|
173 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
174 |
|
|
175 |
.. literalinclude:: examples/simple.imageml
|
|
176 |
:language: xml
|
|
177 |
|
|
178 |
Setting references of this implementation: None (irrelevant)
|
|
179 |
|
|
180 |
Simple image conversion with ConfML setting references
|
|
181 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
182 |
|
|
183 |
.. literalinclude:: examples/with_refs.imageml
|
|
184 |
:language: xml
|
|
185 |
|
|
186 |
Setting references of this implementation:
|
|
187 |
|
|
188 |
- ``TestSettings.ConeInputBmp.localPath``
|
|
189 |
- ``TestSettings.IconInputSvg.localPath``
|
|
190 |
|
|
191 |
MBM conversion using multiple input files
|
|
192 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
193 |
|
|
194 |
.. literalinclude:: examples/multi_input.imageml
|
|
195 |
:language: xml
|
|
196 |
|
|
197 |
Setting references of this implementation: None (irrelevant)
|
|
198 |
|
|
199 |
MBM conversion using an optional mask file
|
|
200 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
201 |
|
|
202 |
.. literalinclude:: examples/bmp_and_optional_mask.imageml
|
|
203 |
:language: xml
|
|
204 |
|
|
205 |
Setting references of this implementation:
|
|
206 |
|
|
207 |
- ``TestSettings.ConeInputBmp.localPath``
|
|
208 |
- ``TestSettings.ConeInputBmpMask.localPath``
|
|
209 |
|
|
210 |
FAQ
|
|
211 |
---
|
|
212 |
|
|
213 |
This will be updated based on the questions.
|
|
214 |
|