|
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 |