PCS version 5.10 R

Douglas Little / d.m.l
(www.leonik.net/dml/sec_pcs.py)

executables:

	TOS/68000:		pcs5-68k.ttp
	TOS/68030+FPU:	pcs5-030.ttp
	TOS/68040-60RC:	pcs5-0x0.ttp
	
	TOS notes: 		FreeImage *does* use floating point on 68k, so it can be very slow at some things like resizing 
					images, even if you are using a fast Atari or emulator. 
					Plain 68030 w/o FPU or 040LC/060LC systems should just use pcs5-68k.ttp since gains are mainly FPU-driven
					The 030 version can use 68881/2 instructions which require emulation on an 040/060RC chip, and will still
					work on those chips if the emulation driver is installed. However the 0x0 version avoids those instructions
					and will run without emulation. I haven't speed-tested both on my 040 to see which is quicker but it's
					probably best just to use the 0x0 version on 040/060 RC chips.
					'-m 3' is very slow and memory hungry, and it's probably useless trying it on a 8mhz 68k. Last test showed
					a claim of 21mb for a dual-field image using the PC version!


	Win32/Cygwin:	pcs5.exe + Cyg DLLs 

	Win32 notes: 	bundled DLLs allow exe to work without Cygwin, but installing Cygwin is best solution


suggested field/dither settings to try (* = defaults):
	
	[ST]	-cd st  -f 2  -dt 2  -dl 3		lace mode (3375 cols) with hatch-dither, hatch-lace (near stable, 60 pseudo-greys)
			-cd st  -f 2  -dt 1  -dl 4 *	lace mode (3375 cols) with prng-dither, hatch-lace (near stable, quasi-continuous)
			-cd st  -f 2  -dt 0  -dl 0		lace mode (3375 cols) with hatch-lace only (near stable, 15 pseudo-greys)
			-cd st  -f 1  -dt 2  -dl 4		native mode (512 cols) with simple hatch (stable, 15 pseudo-greys)
			-cd st  -f 1  -dt 1  -dl 5		native mode (512 cols) with prng dither (stable, grainy)

	[STE]	-cd ste -f 2  -dt 2  -dl 3		lace mode (29791 cols) with hatch-dither, hatch-lace (some flicker, 29 pseudo-greys)
			-cd ste -f 2  -dt 1  -dl 4 *	lace mode (29791 cols) with prng-dither, hatch-lace (stable, near-continuous)
			-cd ste -f 2  -dt 0  -dl 0		lace mode (29791 cols) with hatch-lace only (near stable, 15 pseudo-greys)
			-cd ste -f 1  -dt 2  -dl 4		native mode (4096 cols) with simple hatch (stable, 15 pseudo-greys)
			-cd ste -f 1  -dt 1  -dl 5		native mode (4096 cols) with prng dither (stable, grainy-continuous)


suggested error-diffusion settings to try:

	[ST/E]	-f 1 -dt 0 -et 2 -el 100		spatial [2] 'floyd-steinberg' error diffusion, 100% error quotient, single-field image
			-f 2 -dt 0 -et 2 -el 100		spatial [2] 'floyd-steinberg' error diffusion, 100% error quotient, dual-field image
			-f 2 -dt 0 -et 1 -el 50 -ei	8	field [1] error diffusion, 50% error quotient, 8 field iterations
			-f 2 -dt 0 -et 3 -el 60 -ei	4	multimode [3] error diffusion, 60% field error, 40% spatial error, 4 field iterations
	
	
	hints: 

	* always test settings on [greytest.png] and check the appearance of the 'grey bands'. 
	* make changes incrementally and watch the effect. don't change several settings at once!
	* when TESTING lace/dither settings against [greytest.png], don't use -m 3 mode (@)
	* interlacing modes exist only to reduce flicker but it's easier to see effects of other settings without it (-lt 0)
	* more difficult images will look better if you trade some flicker for colour accuracy. i.e. flicker suppression
	  compete with colour reduction techniques! (this is partly what FIELD diffusion does anyway - turns error into flicker
	  for individual affected pixels)

	(@) -m3 is a powerful approximator, but NOT input-accurate and the grey bands in [greytest.png] will look terrible

	
	lace/dither hints:
	
	* colour depth and interlace mode (i.e. fields = 2) interact with dithering - adjust dither level to suit.
	* excessive dither level will look obvious - prefer less if uncertain.
	* some dither and lace types may interact and produce visual patterns, test combinations before use!
	* some lace types may look better on different kinds of display
	* some lace types and dithering will use up colours faster than others (anything which causes colour 
	  alternation horizontally will use up colours faster) - so there are lace types which avoid this but
	  have some other issues instead. 

	  
	error diffusion hints:
	
	* dithering and SPATIAL error diffusion may conflict, since they both 'stipple' the image in different ways. 
	  i.e. if using SPATIAL error diffusion, suggest no dithering (-dt 0)
	* dithering is ok with FIELD diffusion, since FIELD mode does not stipple at all
	* dithering with MULTIMODE error diffusion - this is a hybrid of FIELD and SPATIAL together - likely better without dithering
	* using FIELD or MULTIMODE error diffusion is pointless on single-field images, since these rely on complementary fields!
	* SPATIAL and MULTIMODE diffusion use up colours faster than FIELD mode alone, just like dithering.
	
	
commands:

	pcs5 [options] [-o <outfile>] [infile(s)]
	
	infile:
	
		the input filename can be a single filename, either PNG or JPG format, or a GLOB/wildcard (e.g. *.PNG).
		it may include an absolute or relative path. 

		note: be careful with slashes and long filenames on filesystems which care about those things! TOS and
		DOS use different slashes from Linux/OSX/posix. Cygwin accepts both, but can still be fussy and complain!
	
	-?
	-h
	--help

		(very) basic help
		
	-v
	--verbose
	
		encourage detailed output

	-q
	--quiet
	
		suppress most output

	-k
	--wait-key
	
		wait for keypress on completion

	-dg
	--diagnostics
	
		enable diagnostic output (image analysis)
		
		this will emit a series of PNG files corresponding to different
		stages of conversion, different components of the image, error measurements
		and any filters generated while processing the image.


	-f <#fields 1 or 2>
	--fields <#fields 1 or 2>
		
		specify number of fields in image, either 1 or 2
		single-field images use less space and don't flicker, but don't extend the native colour bit depth

			
	-cd <#bits per channel>

   -colour-depth <#bits per channel>

		specify the *native* bit depth of the target display system. 
		currently accepts two modes using any of the following tokens:
			4, ste, 4096, 12bit (DEFAULT)
			3, st, stf, stfm, 512, 9bit
		
		
	-m <method#>"
	--method <method#>
	
		specify colour reduction method
		0 = simple linear sampler
		1 = scanline subdivision sampler (DEFAULT)
		2 = linear congruential sampler
		3 = bin balancing solver (expensive - requires FPU)
		
		method 0 is mainly provided for completeness, it can't cope well with difficult
		images but the algorithm is very simple and it's useful for testing other
		settings against testcards - all of the conversion 'problems' will show in an 
		obvious way. the other methods tend to hide problems as much as possible
		
		method 1 is similar to that used by PCS3 and PCS4 - dividing up each scanline
		and sampling pixels in a reasonably 'fair' order within the scan. it produces
		good scan-to-scan coherence but streaking tends to occur towards the left edge
		of the display because most of those colours are borrowed from the previous line.
		
		method 2 yields good results in most cases and like methods 0 & 1, will always 
		accurately convert images which do not use more than the available colour slots.
		it divides the whole display up and samples all pixels in 'fair' order, so 
		streaking will not concentrate on the left of the display. streaks can however move
		to the rest of the display if the image is difficult enough!
		
		method 3 yields the best results most of the time on difficult images, but may not 
		maintain the same colours fed by the input image - all of the colours are generated
		through arbitration and colour merging and what goes in is not what comes out. 
		simpler images may be modified because of this even if there is no shortage of
		colours with which to generate the image. 'greytest.png' will not convert accurately 
		in this mode, for example.

		as a general rule, 3 works best. however it's wise to try methods 1,2 and 3 on 
		each image, especially if you see problems in the output. there isn't a mode that 
		is best for all images but there is a best mode for each individual image.

		mode 3 is impractical if you are running this tool on an 8mhz ST - don't even 
		bother trying that. it's too expensive.
				

	-lt <type#> 
	--lace-type <type#>	
	
		specify the interlace technique used to generate 'in-between' colours. the interlace
		step is decoupled from the dithering step because interlacing should yield zero mean
		intensity variation between fields.
		
		note: some modes can consume more colours than normal, and may impact image quality. the
			  typical trade is image reproduction vs flicker reduction! maximum accuracy is
			  achieved without interlacing and without dithering, but generally the results are
			  more pleasing/natural looking (bearable!) with both.
		
		0 = no interlacing. one entire field is offset by one half colour-step. significant flicker.
		1 = horizontal scan interlacing. pots minimum pressure on colour allocator within each
			scan when dithering is not used, because it does not itself imply dithering, while 
			still achieving zero mean intensity variation between fields. shimmer artifacts but
			likely will cause bad flicker on an interlaced (composite/TV) display.
		2 = vertical scan interlacing. similar to horizontal but puts more pressure on the colour
			allocator even when dithering is not used since it causes intensity alternation every
			horizontal pixel. shimmer artifacts, stable on an interlaced (composite/TV) display.
		3 = checker interlace (DEFAULT). minimize flicker/shimmer on all displays, but puts
			same additional pressure on colour allocator as mode #2
		
		
	-dt <type#>
	--dither <type#>
	
		specify dithering method
		0 = off
		1 = stochastic (DEFAULT)
		2 = hatch
		
		dithering uses periodic colour offsets to approximate the intended colour. it is not the 
		same as error diffusion, although it has a similar effect. the results do look different
		and error diffusion is technically more correct. on low resolution images however 
		dithering can sometimes look less offensive than error diffusion because it does not
		affect neighbour pixels. try both to see what works best for a given image and/or other 
		settings.
				
		stochastic mode offsets each colour with 'noise'. this can make the image look grainy
		but does limit the amount of speckle/noise to the least significant colour bit
		(or whatever the dither magnitude is set to). error diffusion can generate much more speckle
		if the colour errors are large, but the results are often better on the whole (especially for
		higher resolution images which can absorb the noise less intrusively).

		hatch mode just offsets each alternate pixel +/- the configured amount, producing a halftone
		effect. this interacts with the interlace mode which does the same, but the levels used by 
		each are scaled according to their job, so they do not 'conflict'.

		note: the dither units are implemented in a modular way to make it easier to add new ones


	-dl <level>  
	--dither-level <level>
	
		dither level (or 'magnitude') sets the strength of the dithering. larger values will break
		up gradients more effectively but will make the image more noisy. smaller values will have
		less impact, breaking up only edges between colour levels.
		
		note: excessive dithering consumes more colours, and can therefore impact image quality and
		lead to flickery areas or horizontal streaks.
		
		DEFAULT = 4 (seems to be the best compromise for most cases)
		
		
	-et <type#>
	--error-type <type#>
	
		specify error diffusion type
		0 = off (DEFAULT)
		1 = field
		2 = spatial
		3 = multimode (combined field + spatial)
	
		FIELD diffusion means colour errors scraped from one field partially pushed into the other
		field to compensate. since errors will be encountered on this field as well, it is useful
		to iteratively 'bounce' the error between fields a few times to give the error a chance
		to settle down. FIELD diffusion does not stipple/dither. It relies on field interlace to
		compensate for the errors. This also means it only works on dual-field images.

		SPATIAL diffusion is just floyd-steinberg error diffusion, where error from each pixel is
		propagated into neighbouring pixels to get dealt with again. It produces a stippling/
		dithering effect which can be unsightly on low resolution images but it does give a good
		approximation of the original image even if palette reduction has been less than stellar.
		It is generally not helpful to use this kind of diffusion with dithering since the
		stippling effects just combine and can look ugly. i.e. pick one or the other.
		
		MULTIMODE diffusion does both - part of the error gets diffused into the opposite field,
		and part gets pushed into neighbouring pixels. The ratio of how much gets pushed where
		is specified by the --error-level argument (see notes on that argument)
				

	-el <%age 1-100>
	--error-level <%age 1-100>
	
		specify error diffusion amount

		FIELD/SPATIAL diffusion:
		
		100 = 100%, or whole error diffused	from each pixel to other field and/or pixels
		50 = 50%, or half of error diffused	from each pixel to other field and/or pixels

		MULTIMODE diffusion:

		with multimode diffusion, this specifies the amount of error to diffuse in FIELD mode
		with the remaining error diffused in SPATIAL mode. i.e. 100% of the error is always
		diffused but the ratio of FIELD:SPATIAL is specified with this setting.

		DEFAULT = 50

	
	-ei
	--error-iters	
		
		specify number of FIELD/MULTIMODE error iterations
		
		this is only meaningful with field/multimode diffusion (and only in dual-field images), where 
		a portion of the colour error is diffused/propagated into the opposite field.

		more iterations means the error gets more chances to bounce from field to field, and settle
		down to a reasonable minimum. however the error may never settle down enough to give a good
		result and excessive bounces just cost more time. 
		
		with 1 iteration, FIELD error will only be applied to the 2nd field, since the 1st field will
		not see any feedback.
		
		each iteration processes N fields, where N is typically 1 or 2. so 2 iterations on a 2-field
		image means a total of 4 field reductions.

		DEFAULT = 1		
		
		
	-pfmg <float gamma>
	--pfm-gamma <float gamma>
	
		relative gamma curve used to process perception filter mask before it is applied to the error
		term during colour allocation. the effect on the filter mask can be seen in the diagnostic
		output image 'pcfmask.png'. 
		
		large values (g > 1.0) will boost contrast and darken the mask, increasing error tolerance in 
		less contrasted areas of the image.
		
		small values (0.0 < g < 1.0) will reduce contrast and lighten the mask, pushing error more
		towards edges and small islands of colour.
		
		gamma affects relative error scoring, not overall error permitted. it just moves error around.
		see --pfm-influence and --pfm-source for additional control.
		
		DEFAULT = 1.0


	-pfmi <float influence>
	--pfm-influence <float influence>

		influence of the perception filter mask on error calculation. a value of 0 will completely ignore
		the mask. values near one (e.g. 0.999) will apply the mask fully. this is the easiest way to
		control the effect of the mask, especially if the mask is user defined.

		DEFAULT = 0.999

		
	-pfms <maskfile.png>
	--pfm-source <maskfile.png>
			
		user defined perception filter mask - red component of image is used as the mask. this allows
		a user to create a specific mask to control error tolerance in different parts of the image.
		use darker areas to increase error tolerance, white areas minimise colour error.
		
		note: mask is still subject to --pfm-gamma and --pfm-influence before application to the error term!	

		
	-y <size>
	--ysize <size>
	
		specify output display height
		default = 200

		
	-s <format>
	--storage <format>
	
		specify output format
		
		0  = standard PCS (plane-by-plane RLE compressed)
		1  = (reserved...)
		2  = PCS with display data emitted directly to file, uncompressed
		3  = raw display data only (.PCR) - no PCS header etc.
		4+ = (reserved...)


	-o <outfile>

		specify output file path and name (but will be renamed to .pcs automatically)
		default = [infile.pcs]
		