prevnext   » SZS: Wiimms SZS Toolset » wimgt: Wiimms Image Tool » wimgt copy

wimgt copy

Copy and convert an image from 'source' to 'dest'. Multiple sources can be used, if 'dest' is a directory or contains at least one %-pattern. Wildcards and pipe characters are parsed.

This is an alternative for the ENCODE and DECODE commands. The default destination file format is selected by scanning the file extension of the destination. Option --transform may override this. Option --overwrite is set implicitly.

If SOURCE starts with colon (:), then it may be a generic image instead of a real file.


1.   Syntax

wimgt COPY source dest
wimgt COPY source... [-d|-D] dest

2.   Options

Option Param Description
--no-wildcards Disable wildcard parsing and use each filename exactly as specified.
--in-order Process the input files in order of the command line and don't delete duplicates.
-i --ignore Ignore non existing source files without warning.
-d --dest path Define a destination path (directory/file). The destination - means: write to standard output.

The path may contain escape sequences: %Q is replaced by the fully qualified source name. %P and %F are replaced by the source path or by the filename. %N and %E are replaced by source filename without extension or by the source extension. Finally, %T is replaced by the default extension of the destination format.

A '?' direct behind '%' in %E and %T conversions avoid that the same extension is used twice in row.

-D --DEST path Like --dest, but create the directory path automatically.
-E --esc char Define an alternative escape character for destination files. The default is '%'. For Windows batch files it is a good choice to set '-E$'.
-o --overwrite Overwrite already existing files without warning and ignore option --number.
--number If a file already exist, append a number directly before the file extension to make the filename unique. If other numbered files already exist (ignoring case), use the maximum existing index+1. --num is a short cut.
-r --remove-dest Remove already existing files before creating it. If set, --overwrite is ignored. --rm-dest is a short cut.
-u --update Update only existing files and don't create new files. If set, --overwrite and --remove-dest are ignored.
-p --preserve Preserve file times (atime+mtime) while converting or copying files.
-a --all If source and destination file are the same, the file is only written on modifications (transform, patch, ...). If --all is set, then the file is always written.
--n-mipmaps num Force the number of mipmaps. Values between 0 and 20 are allowed. Value OFF (default) disables this option. If enabled, options --max-mipmaps and --mipmap-size are ignored. The creation of mipmaps stops if the width or the height of the mipmap becomes 0. --n-mm is a short cut.
--max-mipmaps num Control the automatic mipmap creation. Values between 0 and 20 are allowed and the default is 4. The mipmap creation for an image stops, if the set number is reached. This option is ignored, if --n-mipmaps is enabled. --max-mm is a short cut.
--mipmap-size num Define the minimal width and minimal height of a generated mipmap. Any value >0 is allowed. The default is 8. This option is ignored, if --n-mipmaps is enabled. --mm-size is a short cut.
--pre-convert Convert the image before the image format for the destination file is selected. This results in a perhaps worser graphic and is only useful to control graphic conversions.
-P --patch mode1.mode2...=file This option specifies patch mode list and a file, separated by an equal sign. Mode is a point separated list of the keywords: TOP (T), BOTTOM (B), VCENTER (V), INS-TOP (IT) and INS-BOTTOM (IB) for the vertical alignment, LEFT (L), RIGHT (R), HCENTER (H), INS-LEFT (IL) and INS-RIGHT (IR) for the horizontal alignment, COPY (CP), BACKGROUND (BG), FOREGROUND (FG) and MIX (MX) as color calculation mode and SHRINK (SH), GROW (GR) and LEAVE (LV) as image size mode.

Abbreviations are allowed. The default is VCENTER.HCENTER.MIX.LEAVE or in short form V.H.MX.LV. If this option is used multiple times all patch files will be used in the entered order.

If FILE starts with colon (:), then it may be a generic image instead of a real file.

--mipmaps If reading a source, scan for mipmaps and load them too. For PNG files, files named with #=1.. are searched. This is the default. --mm is a short cut.
--no-mipmaps If reading a source, ignore mipmaps. This disables not the creation of mipmaps (see -n-mipmaps). --no-mm is a short cut.
--fast-mipmaps If resizing an image, use the old fast resize algorithm (default until v1.64a) instead of the new smart one. Both algorithms differ only, when creating a mipmap for images with odd width or odd height. The old algorithm is faster (factor 2-4) than the default algorithm, but the new algorithm creates better resized images. --fast-mm is a short cut.
--cmpr-default rgb1[,rgb2] Define 2 colors for the case, that all 16 pixels of a CMPR block are transparent. The default is to calculate an average color of all transparent pixels. Before v2.04 white was used.

2 RGB values (hex values with 6 digits each) are expected as parameter. If optional RGB2 is missed, a copy of RGB1 is used. As first step, both colors are converted to RGB565 colors C1 and C2 and sorted, so that C1<C2 (mandatory for CMPR). If C1 and C2 are identical, the least significant bit of green is cleared for C1 and set for C2.

Use parameter '0' to force black, '-1' to force white, or '-' to reset to auto calculation.

-x --transform list Convert image formats. A comma separated list with terms is expected. A term have the syntax '[SRC=]DEST'. It means: convert SRC format into DEST format. If SRC= is not set, the destination format is used for all source formats. This makes only sense as last rule. If DEST is empty no transformation is done for the source. Examples: 'TPL' or 'GRAY' or 'BTI.IA8' or 'TPL.I4+I8=IA8,TEX=,CMPR'

SRC and DEST are tuples of file, image and palette formats and of 2 more attributes. All parts are optional and separated by points, the order is irrelevant.

Allowed file formats are: TPL, TEX, BTI, BREFT-IMG (=BTIMG), PNG (import). Allowed image formats are: I4, I8, IA4, IA8, RGB565 (=R565), RGB5A3 (=R3), RGBA32 (=R32), C4, C8, C14X2, CMPR. Allowed palette formats are: P-IA8 (=P8), P-RGB565 (=P565), P-RGB5A3 (=P3). Attributtes are PALETTE, NO-PALETTE, GRAY, COLOR, ALPHA and NO-ALPHA.

All terms are managed as list. For each graphic the list is iterated until the first SRC tuple of a term matches the graphic. Then the destination tuple is used for the transformation.

The command wimgt TEST prints a clearly arranged readable table as result of this option.

--strip If creating a PNG file, don't add comments about creator and source formats.

3.   Description

The command wimgt COPY converts image files from one format to another. The user can change the file format, the image format and, if supported for image format, the palette format.

The basic syntax is very easy:

 wimgt copy <SRC_FILE> <DEST_FILE>
All tools look always into the source file to determine the formats. These source formats are the defaults for the destination formats. The destination formats can be overwritten by scanning the destination file name and by the option --transform (short: -x).

To change the file format, choose an adequate file extension:

 wimgt copy source.tpl dest.png
 wimgt copy source.tpl dest.tex
In the first example, the file source.tpl is copied to dest.png and the destination file format is PNG. The second command does the same, but creates a TEX0 file.

The option --transform (short: -x) overides all other settings. It accept file, image and/or palette formats a point separated list:

 wimgt copy source.png dest.tex --transform cmpr
 wimgt copy source.png dest.tex --transform tpl
 wimgt copy source.png dest.tex --transform tpl.cmpr
The first example create a TEX0 file, the other 2 examples a TPL file ignoring the file extension. If no image format is set (second example), the source image is analyzed to find a good one.

The copy command will not overwrite existing files. Add --overwrite (short: -o) to allow overwriting. The option --remove (short: -r) can also used to remove an existing file before writing to it. The impact of both options differs in two points: --remove removes soft and hard links and resets the access rights of the new file to the defaults.

 wimgt copy source.tpl dest.png --overwrite
 wimgt copy source.tpl dest.tex --remove