View source for En:Epimgconv

The PC -> EP image converter program can be downloaded as part of the ep128emu package from [https://github.com/istvan-v/ep128emu/releases here].

=Using Epimgconv=
An example for using it:

 epimgconv foo.jpg foo.com

JPG, BMP, PNG, GIF and XPM input file formats are supported.

==Parameters==

NOTE: the following list is not complete or up to date, use the command '''epimgconv --help''' to print the full list of command line options. The most recent version of the program also has a graphical user interface that makes it possible to set any of the parameters and display the resulting converted image with its preview function.

Video mode can be chosen by '''-mode''' parameter, using the next values:

    * 0: 2 colours, normal vertical resolution (not surely black and white but an optimized palette is generated for each lines)
    * 1: 4 colours, normal vertical resolution
    * 2: 16 colours; a picture dithered to 256 colours is being converted into a picture of 16 colours without dither (default setting), normal vertical resolution
    * 3: 16 colours; it generates the same palette as mode 2 but the original picture is being dithered to 16 colours, normal vertical resolution
    * 4: 16 colours; it tries to mix generating palette and dithering but it's very slow, normal vertical resolution
    * 5: 256 colours, normal vertical resolution
    * 6: attribute mode, normal vertical resolution

    * 10: 2 colours (black and white), interlace (not surely black and white)
    * 11: 4 colours, interlace
    * 12: 16 colours; a picture dithered to 256 colours is being converted into a picture of 16 colours without dither, interlace
    * 13: 16 colours; it generates the same palette as mode 2 but the original picture is being dithered to 16 colours, interlace
    * 14: 16 colours; it tries to mix generating palette and dithering but it's very slow, interlace
    * 15: 256 colours, interlace
    * 16: attribute mode, interlace

So '''-mode 0-6''' uses the normal vertical resolution and '''-mode 10-16''' uses the interlace.



'''--help''' prints brief usage information, and the list of all available command line options.

'''-raw 1''' parameter enables to save in raw format (not usable without a separate viewer program), instead of the default .com application format; this way the size also can be larger (if the output format is application, size can be at maximum 46 characters * 288 lines only). '''-outfmt n''' also enables to save in raw format, it can have the following parameters:

* '''-outfmt 0''', '''-outfmt 1''': same as -raw 0 and -raw 1.

*  '''-outfmt 11''', '''-outfmt 31''': Raw format with epcompress -m2 or -m3 compression. [[epcompress]] utility enables to convert between compressed and uncompressed raw format. On the Enterprise, the '''uncompress''' extension included with the epcompress package can be used to decompress and load compressed images.

* '''-outfmt 2''' saves the converted picture into Agsys .crf format which can be used only in mode 1 (4 colours/lines, not interlace); furthermore Agsys cannot load files of large size (-size 36 216 still works but -size 40 240 doesn't). Though Agsys supports palette that changes every lines, the picture may be easier to edit by setting a fix palette with -palres 0 or the parameters -color0..-color3.

* '''-outfmt 3''' saves the picture into ZozoTools format (which uses VL and VS commands). It doesn't support interlace and attribute modes, and fix file size can be at the most 16K. This format sets automatically ''-palres 0'' and EXOS-compatible picture-size (at the most 42x27 characters, height divisible by 9) like ''-outfmt 4''.

* '''-outfmt 4''': PaintBox format; it doesn't support interlace modes either, the file cannot store FIXBIAS, so it has to be set either according to the value given by the converter or you have to use ''-bias 23'' parameter when converting. This format sets automatically ''-palres 0'' and EXOS-compatible picture-size (at the most 42x27 characters, height divisible by 9) as well as ''-outfmt 3''.

* '''-outfmt 5''': Zaxial format, with similar limitations as in the case of PaintBox. This format does store the bias value, however. Attribute mode is not supported by Zaxial, but pictures converted to this mode and saved in Zaxial format can be loaded with the original VLOAD command.


'''-size W H''' enables to set picture size. W = Width in characters, H = Height in lines (interlace: field lines). Being one of the given values 0 or negative, it'll be automatically calculated from the other value and from the size of the picture. E.g.  -size 46 0 means that width is always 46 characters and height is automatically chosen by right of the size of the picture. This way however height could be also too big, so giving a negative value the maximal size can be set. E.g. -size 46 -300 effects the same as -size 46 0, but if the height were bigger than 300 lines, it'll be 300 lines and width will be also reduced.

As default, Epimgconv converts images into the largest possible size, but by using '''-scale X Y''' and '''-offset X Y''' parameters  the image can be enlarged and offset.

'''-scalemode 1''' resizes the picture not in the way that it have the largest size without the cut parts but without the smallest empty (border-coloured) areas. So if the proportion of width and height given by the -size parameter is not fit, there  won't be any border-coloured areas but a part of the picture will be cut sideways or underneath and above. 

'''-color0 n ... -color7 m''' parameters can set fix palette colours (actually setting of avoiding using certain colours is not available). As ''-mode -0'' and ''-mode 10'' parameters don't result a black-and-white picture, ''-color0 0 -color1 255'' parameters are needed to be given to reach black-and-white pictures. The colours can also be given in #RGB format, for example #000 is black and #773 is white.

'''-bias''' parameter sets fixbias - maybe better quality is available than by automatically selected colours. The colours can be given in #RGB format as well, e.g. #331 means bias=31.

If the .com file is too large (>47.75K), it'll be automatically compressed; so EXOS (being lucky) can load it though it starts much slowlier. Using '''-nocompress 1''' parameter, automatic compression of "large" programs can be turned off.

Parameter '''-nointerp 1''' turns off interpolation while resizing a picture (e.g. converting from 32x32 to 512x512 2 colour interlace format without interpolation - this way all the pixels became a square of size 16x16.)

'''-palres 0''' disables palette changing each line (default: '''-palres 1'''), so the palette will be the same in the whole picture. It generally gets quality worse so it might seem not to be very useful, but this way the converted file can get somewhat smaller and it might be easier to use in some other programs.


IstvanV

=Suggestions, tips=
I used the following methods and combined them:

* attribute mode results the best quality and then the 4 colour mode;
* I picked pictures containing not too complex structures;
* I cut the better part from the picture but in the way that its composition remain pretty;
* I looked for pictures where it's useful that there are lots of colours in the horizontally separated parts;
* I picked pictures of strong colours and of many, diverse colours.

The better conversions were where these factors turned up the best way.


Endi

=Description of the EPimgconv/IVIEW file format=

'''000h-00Fh: header'''

* 000h:           0
* 001h:           049h (EXOS file type)
* 002h:           video mode change resolution in lines (0: mode is the same on the whole image)
* 003h:           FIXBIAS change resolution (0: bias is the same on the whole image)
* 004h:           palette change resolution (0: the palette is the same on the whole image)
* 005h:           interlace mode flags
    bit 7: 2x vertical resolution (the upper field is the first one)
    bit 4: pixel data interlace
    bit 3: attribute interlace
    bit 2: palette interlace
    bit 1: FIXBIAS interlace
    bit 0: video mode interlace
* 006h-007h:      height in lines (in the case of interlace, the height of a field)
* 008h:           width in characters (46 is the maximum that can be displayed by NICK)
* 009h:           border color
* 00Ah:           type of compression (0: none, 1: epcompress -m2, 3: epcompress -m3, other values are reserved)
* 00Bh:           number of animation frames, 0 and 1 mean a simple static non-interlaced image. In the case of interlace, the value is given in fields, and is always even and greater than or equal to 2
* 00Ch:           animation speed, the number of times each frame should be repeated. Both 0 and 1 mean the maximum possible speed, 50 fps for non-interlaced modes, and 25 fps for interlace
* 00Dh:           attribute change resolution in lines (0: attributes are stored independently for each line)
* 00Eh:           0 (reserved for future versions)
* 00Fh:           0

'''010h-: image data'''

   video mode 0 (LPT mode & 07Eh)
   video mode 1 (animation and interlace mode only)
   ...
   FIXBIAS 0 (16 colour and attribute modes only)
   FIXBIAS 1 (animation and interlace mode only)
   ...
   palette 0 (not included in 256 colour mode, 2 or 4 colours in 2 or 4 colour modes, and 8 colours otherwise)
   palette 1 (animation and interlace mode only)
   ...
   attribute adat 0 (attribute mode only)
   attribute adat 1 (animation and interlace mode only)
   ...
   pixel data 0
   pixel data 1 (animation and interlace mode only)
   ...

In the case of a compressed format, there are two separate compressed data blocks, one for the video mode, fixbias, and palette data, and the other for the attribute and pixel data. The format of a compressed data block is as follows:

* +000h: uncompressed size (always non-zero), lower byte
* +001h: uncompressed size, upper byte
* +002h: compressed size (= N, always non-zero), lower byte
* +003h: compressed size, upper byte
* +004h - +(004h + N - 1): raw compressed data, see the Z80 decompressor code included with [[epcompress]] for details

=Version history=
'''22 12 2016''': graphical user interface and support for TVC video modes (-mode 7 to 9 and 17 to 19).

'''13 11 2016''': the image converter program has been made a part of the ep128emu 2.0.10 package at GitHub and SourceForge.

'''03 09 2011''': added -outfmt 6 (raw output format) following Zozosoft's suggestion. It is currently buggy in interlace mode, the pixel data of the second field is off by 8 bytes.

'''22 11 2008''': Minor changes only:
* Attribute mode: if ''-quality 9'' and ''-palres 1'' is set, fixbias is searched with a different algorithm; this doesn't always result a better quality but if lossless conversion is possible, it'll be surely found and bias value won't be changed if a border-coloured area stretches above and underneath.
* Minor bug fixed: pictures of higher saturation and too light or too dark colours were handled incorrectly so the conversion wasn't lossless.
* The package contains ''imgsave.lua'' and ''uncompress.ext'' utilities and source code of some earlier versions.

'''11 11 2008''': Zaxial designer format is also supported, and this format can be loaded using the original "VLOAD" command in attribute mode. The conversion became faster in 16 colour modes (2, 3, 4, 6), which is significant first of all using -mode 4. -mode 2 and 3 are also noticeably faster if -quality 9 is set. Further changes: dither worked sometimes wrong while working with too light and too dark parts - it could be detected mostly in 16 colour modes at '-palres 0' - the new version attempts to fix it.

'''07 11 2008''': New parameters: -palres; -outfmt 3, -outfmt 4: Now Zozotools and Paintbox formats are also supported.

'''31 10 2008''': Giving a 0 or negative value after -size parameter makes the computer reckon or sets the maximal possible size.

'''30 10 2008''': New parameters: -scalemode 1 and -outfmt 2 (saving into Agsys file format).

'''29 10 2008''': Handling compressed format, mode/bias/palette and attr/pixel datas are stored separately (actually both of them are compressed). Thanks to the ordering of the palette and attributes, compression efficiency also got somewhat better.

The downloadable package also contains the actual version of IVIEW.


'''24 10 2008''': Datas are stored by type, not by field; automatically compressed .com files already run under EP64 as well; the header contains also the number of frames.


'''20 10 2008''':

Setting VRES bit.

2 colour mode doesn't use a definite black-and-white palette any more as default but an optimized palette is selected in each lines, like in the 4 colour mode. The former black-and-white mode can be set by using -color0 0 -color1 255 parameters;

New parameter: -outfmt. 


'''19 10 2008''': Pictures of any sizes between 1x1 and 8192x8192 are accepted; the internal compressor became faster and has somewhat better efficiency; Programs run also with EP64 (automatically compressed ones not yet). New parameters: -nointerp and -nocompress. 


'''07 06 2008''': -color0-7, -bias parameters also can be given; if the .com file is >48K, it'll be compressed.


'''02 06 2008''': Attribute and interlace mode options.


'''31 05 2008''': First version, no attribute and interlace modes, only the black-and-white mode was with interlace.

=Links and more=
* [[Iview guide]] (a very short summary of beta version)
* [http://www.ep128.hu/Ep_Util/Prg/Paintbox_2.rar download Paintbox 2]
* [http://www.ep128.hu/Ep_Util/ZozoTools.htm Zozotools 1.9 Hungarian guide] [http://www.ep128.hu/Ep_Util/Prg/ZozoTools19.rar download]
* [http://www.ep128.hu/Ep_Util/Prg/Agsys.rar download Agsys 1.1]
* [https://github.com/istvan-v/ep128emu/releases download ep128emu, the package includes EPimgconv, IVIEW and EPcompress]
* [http://www.ep128.hu/Ep_Util/Zaxial.htm Zaxial Hungarian guide] [http://www.ep128.hu/Ep_Util/Prg/Zaxial.rar download]


[[hu:Epimgconv]]