Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

[8a5fe8]: enblend.doc / enblend_4.0.0.xhtml / Response-Files.xhtml Maximize Restore History

Download this file

Response-Files.xhtml    189 lines (183 with data), 14.0 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
<div class="node"><a id="Response-Files" shape="rect" />
<p>Next: <a accesskey="n" href="Common-Options.xhtml#Common-Options" rel="next" shape="rect">Common Options</a>, Up: <a accesskey="u" href="Invocation.html#Invocation" rel="up" shape="rect">Invocation</a></p>
<hr /></div>
<h3 class="section">3.1 Response Files</h3>
<p><a id="index-response-file-35" shape="rect" /></p>
<p><a id="index-g_t_0040samp_007b_0040_0040_007d-_0028response-file-prefix_0029-36" shape="rect" />A response file contains names of images or other response filenames. Introduce response file names with an at-character (‘<samp><span class="samp">@</span></samp>’).</p>
<p><a id="index-processing-order-37" shape="rect" /><a id="index-order_002c-of-processing-38" shape="rect" />Enblend and Enfuse process the list <var>INPUT</var> strictly from left to right, expanding response files in depth-first order. (Multi-layer files are processed from first layer to the last.) The following examples only show Enblend, but Enfuse works exactly the same.</p>
<dl>
<dt>Solely image filenames.</dt>
<dd>Example:
<pre class="example" xml:space="preserve">
enblend image-1.tif image-2.tif image-3.tif
</pre>
<p>The ultimate order in which the images are processed is: <samp><span class="file">image-1.tif</span></samp>, <samp><span class="file">image-2.tif</span></samp>, <samp><span class="file">image-3.tif</span></samp>.<br /></p>
</dd>
<dt>Single response file.</dt>
<dd>Example:
<pre class="example" xml:space="preserve">
enblend @list
</pre>
<p>where file <samp><span class="file">list</span></samp> contains</p>
<pre class="example" xml:space="preserve">
img1.exr
img2.exr
img3.exr
img4.exr
</pre>
<p>Ultimate order: <samp><span class="file">img1.exr</span></samp>, <samp><span class="file">img2.exr</span></samp>, <samp><span class="file">img3.exr</span></samp>, <samp><span class="file">img4.exr</span></samp>.<br /></p>
</dd>
<dt>Mixed literal names and response files.</dt>
<dd>Example:
<pre class="example" xml:space="preserve">
enblend @master.list image-09.png image-10.png
</pre>
<p>where file <samp><span class="file">master.list</span></samp> comprises of</p>
<pre class="example" xml:space="preserve">
image-01.png
@first.list
image-04.png
@second.list
image-08.png
</pre>
<p><samp><span class="file">first.list</span></samp> is</p>
<pre class="example" xml:space="preserve">
image-02.png
image-03.png
</pre>
<p>and <samp><span class="file">second.list</span></samp> contains</p>
<pre class="example" xml:space="preserve">
image-05.png
image-06.png
image-07.png
</pre>
<p>Ultimate order: <samp><span class="file">image-01.png</span></samp>, <samp><span class="file">image-02.png</span></samp>, <samp><span class="file">image-03.png</span></samp>, <samp><span class="file">image-04.png</span></samp>, <samp><span class="file">image-05.png</span></samp>, <samp><span class="file">image-06.png</span></samp>, <samp><span class="file">image-07.png</span></samp>, <samp><span class="file">image-08.png</span></samp>, <samp><span class="file">image-09.png</span></samp>, <samp><span class="file">image-10.png</span></samp>,</p>
</dd>
</dl>
<h4 class="subsection">3.1.1 Response File Format</h4>
<p><a id="index-response-file_002c-format-39" shape="rect" /><a id="index-format-of-response-file-40" shape="rect" /> <a id="index-g_t_0040samp_007b_0023_007d-_0028response-file-comment_0029-41" shape="rect" /><a id="index-response-file_002c-comment-_0028_0040samp_007b_0023_007d_0029-42" shape="rect" />Response files contain one filename per line. Blank lines or lines beginning with a sharp sign (‘<samp><span class="samp">#</span></samp>’) are ignored; the latter can serve as comments. Filenames that begin with an at-character (‘<samp><span class="samp">@</span></samp>’) denote other response files. <a href="Table_003aresponse_002dfile_002dformat.xhtml#Table_003aresponse_002dfile_002dformat" shape="rect">Table:response-file-format</a> states a formal grammar of response files in <a href="http://en.wikipedia.org/wiki/Ebnf" shape="rect"><acronym>EBNF</acronym></a>.</p>
<div class="float"><a id="Table_003aresponse_002dfile_002dformat" shape="rect" />
<table summary="">
<tr align="left">
<td valign="top" rowspan="1" colspan="1"><var>response-file</var></td>
<td valign="top" rowspan="1" colspan="1">::=</td>
<td valign="top" rowspan="1" colspan="1"><var>line</var>*<br /></td>
</tr>
<tr align="left">
<td valign="top" rowspan="1" colspan="1"><var>line</var></td>
<td valign="top" rowspan="1" colspan="1">::=</td>
<td valign="top" rowspan="1" colspan="1">(<var>comment</var> | <var>file-spec</var>) [‘<samp><span class="samp">\r</span></samp>’] ‘<samp><span class="samp">\n</span></samp>’<br /></td>
</tr>
<tr align="left">
<td valign="top" rowspan="1" colspan="1"><var>comment</var></td>
<td valign="top" rowspan="1" colspan="1">::=</td>
<td valign="top" rowspan="1" colspan="1"><var>space</var>* ‘<samp><span class="samp">#</span></samp>’ <var>text</var><br /></td>
</tr>
<tr align="left">
<td valign="top" rowspan="1" colspan="1"><var>file-spec</var></td>
<td valign="top" rowspan="1" colspan="1">::=</td>
<td valign="top" rowspan="1" colspan="1"><var>space</var>* ‘<samp><span class="samp">@</span></samp>’ <var>filename</var> <var>space</var>*<br /></td>
</tr>
<tr align="left">
<td valign="top" rowspan="1" colspan="1"><var>space</var></td>
<td valign="top" rowspan="1" colspan="1">::=</td>
<td valign="top" rowspan="1" colspan="1">‘ ’ | ‘<samp><span class="samp">\t</span></samp>’<br /></td>
</tr>
</table>
<p class="noindent">where <var>text</var> is an arbitrary string and <var>filename</var> is any filename.</p>
<p><a id="index-response-file_002c-grammar-43" shape="rect" /><a id="index-grammar_002c-response-file-44" shape="rect" /></p>
<p><strong class="float-caption">Table 3.1: <acronym>EBNF</acronym> definition of the grammar of response files.</strong></p>
</div>
<p>In a response file relative filenames are used relative the response file itself, not relative to the current-working directory of the application.</p>
<p class="noindent">The above grammar might unpleasantly surprise the user in the some ways.</p>
<dl>
<dt>Whitespace trimmed at both line ends</dt>
<dd>For convenience, whitespace at the beginning and at the end of each line is ignored. However, this implies that response files cannot represent filenames that start or end with whitespace, as there is no quoting syntax. Filenames with embedded whitespace cause no problems, though.<br /></dd>
<dt>Only whole-line comments</dt>
<dd>Comments in response files always occupy a complete line. There are no “line-ending comments”. Thus, in
<pre class="example" xml:space="preserve">
# exposure series
img-0.33ev.tif # "middle" EV
img-1.33ev.tif
img+0.67ev.tif
</pre>
<p>only the first line contains a comment, whereas the second line includes none. Rather, it refers to a file called ‘<samp><span class="samp">img-0.33ev.tif # "middle" EV</span></samp>’<!-- /@w -->.<br /></p>
</dd>
<dt>Image filenames cannot start with ‘<samp><span class="samp">@</span></samp>’</dt>
<dd>An at-sign invariably introduces a response file, even if the filename's extension hints towards an image.</dd>
</dl>
<p><a id="index-response-file_002c-force-recognition-of-45" shape="rect" />If Enblend or Enfuse do not recognize a response file, they will skip the file and issue a warning. To force a file being recognized as a response file add one of the following syntactic comments to the <em>first</em> line of the file.</p>
<pre class="example" xml:space="preserve">
<a id="index-response_002dfile-46" shape="rect" />response-file: true
<a id="index-enblend_002dresponse_002dfile-47" shape="rect" />enblend-response-file: true
<a id="index-enfuse_002dresponse_002dfile-48" shape="rect" />enfuse-response-file: true
</pre>
<p class="noindent">Finally, here is an example of a valid response file.</p>
<pre class="example" xml:space="preserve">
# 4\pi panorama!
# These pictures were taken with the panorama head.
@round-shots.list
# Freehand sky shot.
zenith.tif
# "Legs, will you go away?" images.
nadir-2.tif
nadir-5.tif
nadir.tif
</pre>
<h4 class="subsection">3.1.2 Syntactic Comments</h4>
<p><a id="index-response-file_002c-syntactic-comment-49" shape="rect" /><a id="index-syntactic-comment_002c-response-file-50" shape="rect" /> Comments that follow the format described in <a href="Table_003aresponse_002dfile_002dsyntactic_002dcomment.xhtml#Table_003aresponse_002dfile_002dsyntactic_002dcomment" shape="rect">Table:response-file-syntactic-comment</a> are treated as instructions how to interpret the rest of the response file. A syntactic comment is effective immediately and its effect persists to the end of the response file, unless another syntactic comment undoes it.</p>
<div class="float"><a id="Table_003aresponse_002dfile_002dsyntactic_002dcomment" shape="rect" />
<table summary="">
<tr align="left">
<td valign="top" rowspan="1" colspan="1"><var>syntactic-comment</var></td>
<td valign="top" rowspan="1" colspan="1">::=</td>
<td valign="top" rowspan="1" colspan="1"><var>space</var>* ‘<samp><span class="samp">#</span></samp>’ <var>space</var>* <var>key</var> <var>space</var>* ‘<samp><span class="samp">:</span></samp>’ <var>space</var>* <var>value</var><br /></td>
</tr>
<tr align="left">
<td valign="top" rowspan="1" colspan="1"><var>key</var></td>
<td valign="top" rowspan="1" colspan="1">::=</td>
<td valign="top" rowspan="1" colspan="1">(‘<samp><span class="samp">A</span></samp>’ .. ‘<samp><span class="samp">Z</span></samp>’ | ‘<samp><span class="samp">a</span></samp>’ .. ‘<samp><span class="samp">z</span></samp>’ | ‘<samp><span class="samp">-</span></samp>’)+<br /></td>
</tr>
</table>
<p class="noindent">where <var>value</var> is an arbitrary string.</p>
<p><a id="index-syntactic-comment_002c-grammar-51" shape="rect" /><a id="index-grammar_002c-syntactic-comment-52" shape="rect" /></p>
<p><strong class="float-caption">Table 3.2: <acronym>EBNF</acronym> definition of the grammar of syntactic comments in response files.</strong></p>
</div>
<p>Unknown syntactic comments are silently ignored. <!-- @node Globbing Algorithms --></p>
<h4 class="subsection">3.1.3 Globbing Algorithms</h4>
<p><a id="index-globbing-algorithms-53" shape="rect" /><a id="index-algorithms_002c-globbing-54" shape="rect" /> The three equivalent syntactic keys</p>
<ul>
<li><a id="index-glob-55" shape="rect" /><code>glob</code>,</li>
<li><a id="index-globbing-56" shape="rect" /><code>globbing</code>, or</li>
<li><a id="index-filename_002dglobbing-57" shape="rect" /><code>filename-globbing</code></li>
</ul>
<p>control the algorithm that Enblend or Enfuse use to glob filenames in response files.</p>
<p><a id="index-globbing-algorithm-_0040samp_007bliteral_007d-58" shape="rect" /><a id="index-globbing-algorithm-_0040samp_007bwildcard_007d-59" shape="rect" />All versions of Enblend and Enfuse support at least two algorithms: <code>literal</code>, which is the default, and <code>wildcard</code>. See <a href="Table_003aglobbing_002dalgorithms.xhtml#Table_003aglobbing_002dalgorithms" shape="rect">Table:globbing-algorithms</a> for a list of all possible globbing algorithms. To find out about the algorithms in your version of Enblend or Enfuse team up the options <samp><span class="option">--version</span></samp> and <samp><span class="option">--verbose</span></samp>.</p>
<div class="float"><a id="Table_003aglobbing_002dalgorithms" shape="rect" />
<dl>
<dt><code>literal</code></dt>
<dd><a id="index-globbing-algorithm-_0040samp_007bliteral_007d-60" shape="rect" />Do not glob. Interpret all filenames in response files as literals. This is the default.
<p>Please keep in mind that whitespace at both ends of a line in a response file <em>always</em> gets discarded.<br /></p>
</dd>
<dt><code>wildcard</code></dt>
<dd><a id="index-globbing-algorithm-_0040samp_007bwildcard_007d-61" shape="rect" /><a id="index-glob_00287_0029-62" shape="rect" />Glob using the wildcard characters ‘<samp><span class="samp">?</span></samp>’, ‘<samp><span class="samp">*</span></samp>’, ‘<samp><span class="samp">[</span></samp>’, and ‘<samp><span class="samp">]</span></samp>’.
<p>The <acronym>W*N32</acronym> implementation only globs the filename part of a path, whereas all other implementations perform wildcard expansion in <em>all</em> path components. Also see <a href="http://www.kernel.org/doc/man-pages/online/pages/man7/glob.7.html" shape="rect">glob(7)</a>.<br /></p>
</dd>
<dt><code>none</code></dt>
<dd><a id="index-globbing-algorithm-_0040samp_007bnone_007d-63" shape="rect" />Alias for <code>literal</code>.<br /></dd>
<dt><code>shell</code></dt>
<dd><a id="index-globbing-algorithm-_0040samp_007bshell_007d-64" shape="rect" />The <code>shell</code> globbing algorithm works as <code>literal</code> does. In addition, it interprets the wildcard characters ‘<samp><span class="samp">{</span></samp>’, ‘<samp><span class="samp">}</span></samp>’, and ‘<samp><span class="samp">~</span></samp>’. This makes the expansion process behave more like common <acronym>UN*X</acronym> shells.<br /></dd>
<dt><code>sh</code></dt>
<dd><a id="index-globbing-algorithm-_0040samp_007bsh_007d-65" shape="rect" />Alias for <code>shell</code>.</dd>
</dl>
<p><a id="index-globbing-algorithms-66" shape="rect" /><a id="index-algorithms_002c-globbing-67" shape="rect" /></p>
<p><strong class="float-caption">Table 3.3: Globbing algorithms for the use in response files</strong></p>
</div>
<p>Example:</p>
<pre class="example" xml:space="preserve">
# Horizontal panorama
# 15 images
# filename-globbing: wildcard
image_000[0-9].tif
image_001[0-4].tif
</pre>