</pre>
</p>
- <h2><a name="outputtingalignmentfiles"></a>Outputting/converting alignment files and images (<code>--output</code>, <code>--format</code>, <code>--image</code>, <code>--type</code>, <code>--textrenderer</code>, <code>--scale</code>, <code>--backups</code>, <code>--overwrite</code>)</h2>
+ <h2><a name="outputtingalignmentfiles"></a>Outputting/converting alignment files and images (<code>--output</code>, <code>--format</code>, <code>--image</code>, <code>--structureimage</code>, <code>--type</code>, <code>--scale</code>, <code>--width</code>, <code>--height</code>, <code>--imagecolour</code>, <code>--bgcolour</code>, <code>--textrenderer</code>, <code>--overwrite</code>, <code>--backups</code>, <code>--mkdirs</code>)</h2>
<p>
You can save an alignment as an alignment file, or exported as an image, in different formats. Jalview's alignment output formats are:
</pre>
</p>
- <h3><a name="image"></a><code>--structureimage</code></h3>
+ <h3><a name="structureimage"></a><code>--structureimage</code></h3>
<p>
To export an open structure as an image, use the <code>--structureimage</code> argument, which will give an image of the structure as it appears (or would appear if not in <code>--headless</code> mode) in a Jmol window including colour scheme. <code>--structureimage</code> can currently only be used with structures opened with the <code>jmol</code> structureviewer (the default viewer).
</p>
These by default produce a PNG image of screen or webpage resolution, which you will probably want to improve upon. There are two ways of doing this with Jalview: increasing the scale of the PNG image, or using a vector based image format (EPS, SVG, HTML).
<p>
+ <h3><a name="type"></a><code>--type</code></h3>
+
+ <p>
+ To specify the type of image file to write (if using an unrecognised file extension) use the <code>--type</code> argument to specify a value (see above). A sub-value modifier on the <code>--image</code> and <code>--structureimage</code> value can also be used. Valid values are:
+ <br/>
+ <code>png</code> - A Portable Network Graphics image (bitmap, default),
+ <br/>
+ <code>svg</code> - A Scalable Vector Graphics image (vector),
+ <br/>
+ <code>eps</code> - An Encapsulated PostScript file (vector),
+ <br/>
+ <code>html</code> - An HTML rendition of the alignment with embedded source data (vector/web browser),
+ <br/>
+ <code>biojs</code> - An HTML rendition of the alignment with interactive MSA viewer <a href="biojsmsa.html">BioJS-MSA</a> (vector).
+ </p>
+
<h3><a name="bitmap"></a>Bitmap image types (<code>png</code>)</h3>
<p>
<h3><a name="scale"></a><code>--scale</code></h3>
<p>
- We can increase the size of the PNG image by a factor of <em>S</em> by following the <code>--image</code> argument with a <code>--scale <em>S</em></code> argument and value. The value doesn't have to be an integer and should be given as an integer or floating point formatted number, e.g.
+ We can increase the size of the PNG image by a factor of <em>S</em> by following the <code>--image</code> or <code>--structureimage</code> argument with a <code>--scale <em>S</em></code> argument and value. The value doesn't have to be an integer and should be given as an integer or floating point formatted number, e.g.
<pre>
jalview --open examples/uniref50.fa --colour gecos-ocean --image mypic.png --scale 5.5 --headless
</pre>
</p>
<p>
- You can specify two or all of <code>--scale</code>, <code>--width</code> and <code>--height</code> as limits to the size of the image (think of one or two bounding boxes) and the one which produces the smallest scale of image is used. You can also specify each of these as sub-value modifiers to the <code>--image</code> value:
+ You can specify two or all of <code>--scale</code>, <code>--width</code> and <code>--height</code> as limits to the size of the image (think of one or two bounding boxes) and the one which produces the smallest scale of image is used. You can also specify each of these as sub-value modifiers to the <code>--image</code> or <code>--structureimage</code> value:
<pre>
jalview --headless --open https://www.ebi.ac.uk/interpro/api/entry/pfam/PF03760/?annotation=alignment%3Aseed --noshowannotations --colour gecos-flower --image [scale=0.25,width=320,height=240]thumbnail.png
</pre>
</p>
- <h3><a name="height"></a><code>--imagecolour</code></h3>
+ <h3><a name="imagecolour"></a><code>--imagecolour</code></h3>
<p>
Specify a colour scheme to use just for this image using the <code>--imagecolour</code> argument:
</pre>
</p>
- <h3><a name="height"></a><code>--bgcolour</code></h3>
+ <h3><a name="bgcolour"></a><code>--bgcolour</code></h3>
<p>
<strong>Only applies to <code>--structureimage</code>.</strong> Specify a background colour for a structure image. The colour can be specified as a named colour recognised by Java (e.g. <code>"white"</code>, <code>"cyan"</code>) or as a #RRGGBB hash-6-digit-hex-string as used in web pages (e.g. <code>"#ffffff"</code>, <code>"#00ffff"</code>). Note that if you're using a hash in a bash-like shell then you should quote the string to avoid problems with it being interpreted as a comment character.
Next we look at vector image formats, which maintain detail at all resolutions.
</p>
- <h3><a name="vector"></a>Vector image export</h3>
+ <h3><a name="vector"></a>Vector image export (<code>svg</code>, <code>eps</code>, <code>html</code>, <code>biojs</code>)</h3>
<p>
Jalview can export an alignment in Encapsulated PostScript (<code>eps</code>), Scalable Vector Graphics (<code>svg</code>), HTML (<code>html</code>) or BioJSON -- another HTML format (<code>biojs</code>), by using, e.g.
</pre>
</p>
+ <h3><a name="outputbehaviour"></a>Output behaviour</h3>
+
+ <h3><a name="overwrite"></a><code>--overwrite</code></h3>
+
+ <p>
+ By default, Jalview will refuse to overwrite an output file (alignment or image) unless backups are in operation (alignment files only). To force overwriting files, use the <code>--overwrite</code> argument.
+ </p>
+
+ <h3><a name="backups"></a><code>--backups / --nobackups</code></h3>
+
+ <p>
+ Jalview should honour your preferences for backup files of output alignment files. Using <code>--backups</code> or <code>--nobackups</code> forces the behaviour. With no backups set, you will need to use <code>--overwrite</code> to overwrite an existing file. Note that Jalview does not make backup files of exported images.
+ </p>
+
+ <h3><a name="mkdirs"></a><code>--mkdirs</code></h3>
+
+ <p>
+ If you want to output a file into a folder that doesn't yet exist (this might happen particularly when using <code>{dirname}</code> substitutions -- see below), then Jalview will fail to write the file since the parent directory doesn't exist. You can use <code>--mkdirs</code> to tell Jalview to make the new directory (or directories, it will create several nested directories if necessary) before writing the file. <code>--mkdirs</code> is cautious and will generally refuse to make a new directory using a relative path with <code>..</code> in.
+ </p>
<h2><a name="filenamesubstitutionsandbatchprocessing"></a>Filename substitutions and batch processing (<code>--substitutions</code>, <code>--close</code>, <code>--all</code>)</h2>
</p>
- <h2><a name="alloutputwildcard"></a>The all output wildcard: <code>--output "*.ext"</code>, <code>--image "*.ext"</code></h2>
+ <h2><a name="alloutputwildcard"></a>The all output wildcard: <code>--output "*/*.ext"</code>, <code>--image "*/*.ext"</code></h2>
<p>
Purely as an intuitive syntactic sweetener, you can use the <code>--output</code> wildcard <code>*</code> in two places as part of an output path and filename.
git://source.jalview.org / jalview.git / blobdiff