JAL-629 More docs

diff --git a/help/help/html/features/clarguments-basic.html b/help/help/html/features/clarguments-basic.html
index 8b64625..19406b4 100644 (file)
--- a/help/help/html/features/clarguments-basic.html
+++ b/help/help/html/features/clarguments-basic.html
@@ -414,30 +414,104 @@
   </p>
 
   <h3><a name="image"></a><code>--image</code></h3>
+  To export the open alignment window as an image, use the <code>--image</code> argument, which will give an image of the alignment and annotations as it appears (or would appear if not in <code>--headless</code> mode) in the alignment window if it was large enough for the whole alignment, including colour choice and features.
+  <p>
+  <pre>
+  jalview --open examples/plantfdx.fa --colour gecos-blossom --features examples/plantfdx.features --annotations examples/plantfdx.annotations --image plantfdx.png --headless
+  </pre>
+  </p>
+
+  <p>
+  This by default produces a PNG image of screen or webpage resolution, which you may 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="bitmap"></a>Bitmap image types (<code>png</code>)</h3>
+
+  <p>
+  Bitmap images are composed of an array of pixels.  Bitmap images with a low resolution that are blown up to a larger size appear "blocky", so it is important to get the resolution for your purpose correct.  Older screens only require a modest resolution, whilst newer HiDPI screens look better with a higher resolution.  For print you will want an even higher resolution although in this case you would probably want to use a vector image format.  In general creating a bitmap image that has a large resolution means you can scale the image down if needed, although if you are running a batch process this will take more time and resources.
+  </p>
+  <p>
+  Jalview only produces a PNG bitmap image type.  This is a high-colour lossless format which can also use lossless compression so is suitable for alignment figures.
+  </p>
+  <p>
+  Let's increase the resolution of the PNG image:
+  </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.
   <pre>
+  jalview --open examples/uniref50.fa --colour gecos-ocean --image mypic.png --scale 5.5 --headless
   </pre>
+  which will produce a PNG image 5.5 times larger (and more detailed) than without the <code>--scale</code> argument.
   </p>
+  <p>
+  However, since you won't necessarily already know the size of an alignment's exported image you can specify either an exact width or height (in pixels) with either one of the
+  <code>--width</code> and <code>--height</code> arguments:
 
-  <h3><a name=""></a><code>--</code></h3>
+  <h3><a name="width"></a><code>--width</code></h3>
 
   <p>
+  Specify an exact width of an exported PNG image with <code>--width</code>:
   <pre>
+  jalview --headless --open https://www.ebi.ac.uk/interpro/api/entry/pfam/PF03760/?annotation=alignment%3Aseed --noshowannotations --colour gecos-sunset --image wallpaper.png --width 3840
   </pre>
   </p>
 
-  <h3><a name=""></a><code>--</code></h3>
+  <h3><a name="height"></a><code>--height</code></h3>
 
   <p>
+  Alternatively specify an exact height with the <code>--height</code> argument:
   <pre>
+  jalview --headless --open https://www.ebi.ac.uk/interpro/api/entry/pfam/PF03760/?annotation=alignment%3Aseed --noshowannotations --colour gecos-ocean --image wallpaper.png --height 2160
   </pre>
   </p>
 
-  <h3><a name=""></a><code>--</code></h3>
+  <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:
+  <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>
+
+  <p>
+  Next we look at vector image formats, which maintain detail at all resolutions.
+  </p>
+
+  <h3><a name="vector"></a>Vector image export</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>
+  jalview --open examples/uniref50.fa --colour gecos-flower --image printable.eps
+  </pre>
+  The image format can be specified with the <code>--type</code> argument or as a sub-value modifier on the <code>--image</code> value.  If neither is used the <code>type</code> will be guessed from the image file extension.  The following three examples should produce the same contents:
+  <pre>
+  jalview --open examples/uniref50.fa --colour gecos-flower --image printable.eps
+  jalview --open examples/uniref50.fa --colour gecos-flower --image printable.postscript --type eps
+  jalview --open examples/uniref50.fa --colour gecos-flower --image [type=eps]printable.postscript
+  </pre>
+  </p>
+
+  <h3><a name="textrenderer"></a><code>--textrenderer</code></h3>
+
+  <p>
+  In a vector format any text that appears on the page (including residue/base labels) can be saved in the image file either as <code>text</code> or as <code>lineart</code> using the <code>--textrenderer</code> argument.  This is only available for <code>eps</code>, <code>svg</code> and <code>html</code> formats.
+  </p>
+
+  <p>
+  The difference is potentially in the appearance of the file, and definitely in the filesize!  Saving with <code>text</code> requires the font used to display the text characters in the alignment to be present on the viewing platform to look exactly the same.  If it isn't then another suitable font will probably be used.  The filesize using <code>text</code> is relatively small.
+  </p>
+  <p>
+  When using <code>lineart</code> each individual character that appears in the alignment (including names/titles and resisdues/bases) is stored in the image with its own vector lines.  This means that the appearance of the text is retained exactly independent of installed fonts, but the filesize is increased.  You will also be unable to copy what appears to be text as text.
+  </p>
 
   <p>
+  The type of <code>--textrenderer</code> can be specified with an argument following <code>--image</code> or as a sub-value modifier:
   <pre>
+  jalview --open examples/uniref50.fa --colour gecos-flower --image printable.html --type biojs
+  jalview --open examples/uniref50.fa --colour gecos-flower --image [type=eps,textrenderer=lineart]printable.ps
   </pre>
   </p>
 

diff --git a/help/help/html/features/clarguments-intermediate.html b/help/help/html/features/clarguments-intermediate.html
deleted file mode 100644 (file)
index e69de29..0000000