From 5d574591163c13b4409e6cc745303e92e1836071 Mon Sep 17 00:00:00 2001 From: Ben Soares Date: Fri, 12 May 2023 17:15:07 +0100 Subject: [PATCH] JAL-629 More docs --- help/help/html/features/clarguments-basic.html | 80 +++++++++++++++++++++++- 1 file changed, 77 insertions(+), 3 deletions(-) delete mode 100644 help/help/html/features/clarguments-intermediate.html diff --git a/help/help/html/features/clarguments-basic.html b/help/help/html/features/clarguments-basic.html index 8b64625..19406b4 100644 --- a/help/help/html/features/clarguments-basic.html +++ b/help/help/html/features/clarguments-basic.html @@ -414,30 +414,104 @@

--image

+ To export the open alignment window as an image, use the --image argument, which will give an image of the alignment and annotations as it appears (or would appear if not in --headless mode) in the alignment window if it was large enough for the whole alignment, including colour choice and features. +

+ 

+  jalview --open examples/plantfdx.fa --colour gecos-blossom --features examples/plantfdx.features --annotations examples/plantfdx.annotations --image plantfdx.png --headless
+
+

+ +

+ 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). +

+ +

Bitmap image types (png)

+ +

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

+

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

+

+ Let's increase the resolution of the PNG image: +

+ +

--scale

+ We can increase the size of the PNG image by a factor of S by following the --image argument with a --scale S 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. 

+  jalview --open examples/uniref50.fa --colour gecos-ocean --image mypic.png --scale 5.5 --headless
+ which will produce a PNG image 5.5 times larger (and more detailed) than without the --scale argument.

+

+ 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 + --width and --height arguments: -

--

+

--width

+ Specify an exact width of an exported PNG image with --width: 

+  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

-

--

+

--height

+ Alternatively specify an exact height with the --height argument: 

+  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

-

--

+

+ You can specify two or all of --scale, --width and --height 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 --image value: + 

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

+ +

+ Next we look at vector image formats, which maintain detail at all resolutions. +

+ +

Vector image export

+ +

+ Jalview can export an alignment in Encapsulated PostScript (eps), Scalable Vector Graphics (svg), HTML (html) or BioJSON -- another HTML format (biojs), by using, e.g. + 

+  jalview --open examples/uniref50.fa --colour gecos-flower --image printable.eps
+
+ The image format can be specified with the --type argument or as a sub-value modifier on the --image value. If neither is used the type will be guessed from the image file extension. The following three examples should produce the same contents: + 
+  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
+
+

+ +

--textrenderer

+ +

+ In a vector format any text that appears on the page (including residue/base labels) can be saved in the image file either as text or as lineart using the --textrenderer argument. This is only available for eps, svg and html formats. +

+ +

+ The difference is potentially in the appearance of the file, and definitely in the filesize! Saving with text 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 text is relatively small. +

+

+ When using lineart 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. +

+ The type of --textrenderer can be specified with an argument following --image or as a sub-value modifier: 

+  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

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