## ppmcentre version 2.04

### A tool for processing planetary images by Anthony Wesley

### Usage

    	ppmcentre [ options ] files or directories

ppmcentre processes image files, it's primary objective is to find and centre the dominant object in each frame to make life easier for processing by Registax or other astronomy image-stacking programs.

With no file or directory arguments ppmcentre will process all image files in the current directory that it understands. If you name a directory, then all image files in that directory will be processed.

Support file formats are:

BMP
  8 bit greyscale and 24 bit colour, uncompressed
FIT
  8 and 16 bit greyscale images

### Downloading ppmcentre

Please select the version you want, or download the source code and see the compile.* scripts to see how to build ppmcentre.

- ppmcentre.exe Version 2.04 (MS Windows Commandline version)
- ppmcentre-2.04.tar (source code for linux and Windows)

### Command Switches and Parameters

ppmcentre is a commandline program for either linux (x86 and x86_64) or MS Windows (x86 only).

You control ppmcentre's behaviour by giving one or more switches with optional parameters on the command line.

All switches start with -

Any parameter not starting with - is assumed to be either an image file or the name of a directory containing image files. Switches and files are processed in the order that they appear in the command line, so it would be normal to provide all the switches first and then follow with the list of files or directories to be processed.

The supported options are:

-width=W
  Creates output images of width W by cropping the input image after centering. This is useful in cases where the object (probably a planet) only takes up a small portion of the image frame.

  NOTE: W MUST be an even number, and to be safe you should also make it a multiple of 4.

  NOTE: When image rescaling is specified, W is interpreted as relative to the original image size (i.e. without rescaling).

  Default: Width of input image (no cropping)

-height=H
  Creates output images of height H by cropping the image height after centering.

  NOTE: H MUST be an even number, and to be safe you should also make it a multiple of 4.

  NOTE: When image rescaling is specified, W is interpreted as relative to the original image size (i.e. without rescaling).

  Default: Height of original image (no cropping).

-cutx=X
  After locating the object in the image ppmcentre cuts it out and moves it to the centre. cutx specifies the horizontal size of this cutout, default value is 360 pixels.

  This cutout size should be large enough to contain your object, but keeping it small speeds up other processing (rescaling, smoothing, gamma) as they apply only to the region inside the cutout.

-cuty=Y
  cuty specifies the vertical size of the cutout, default value is 360 pixels. (See also cutx for more information)

-cut=N
  This is a shortcut to set a collection of parameters to the same value. Sets -width=N -height=N -cutx=N -cuty=N

-minpixels=M
  Specifies the minimum number of pixels which must pass the threshold for this file to be processed, default value 250.

  If your target image is very small you may want to decrease this value.

-threshhold=T
  T specifies the minimum brightness for a pixel to be considered part of the object in the range 0-255 (0=Black, 255=White).

  Default value 40

-outdir=D
  Specifies where ppmcentre will write its output files.

  Without this switch ppmcentre will write it's output into the same directory as its input, but this will fail unless you also specify -overwrite.

  D can be either a relative directory, or an absolute directory. A relative directory is one that doesn't start with a directory separator (/ or \ depending on your O/S).

  e.g. If you use -outdir=output (relative path) then ppmcentre will create a directory named output under the directory holding the input images.

  If you use -outdir=\out (MS Windows absolute path) or -outdir=/out (UNIX absolute path) then this is taken as a top-level directory name, and not relative to the input images.

  In all cases ppmcentre will create the output director(ies) as required, or die with a complaint if it doesn't have permission to do so.

  NOTE: This behaviour is different to earlier versions of ppmcentre which would by default overwrite their input. Now you have to specify -overwrite to get the old behaviour if you really want it :-)

-noprotect (FITS file format only)
  This option was added to counter silly programs that want to automatically scale the brightness of the image data when FITS file format is used.

  By default when ppmcentre creates a FIT output file it adds two special pixels (black & white) in the bottom left corner to stop histo-stretching by other programs. This switch turns this feature off.

-overwrite
  By default ppmcentre will not overwrite an existing output file unless you specify this parameter.

-upscale=N
-upscale=N/M
  Resamples the image UP by a factor of N and then DOWN by a factor of M. e.g. 3/2 makes the image 1.5 times larger, and 1/2 makes the image half original size. The image as a whole becomes a factor of N/M larger in both dimensions.

  NOTE: -width,-height,-cutx and -cuty always refer to the dimensions of the SOURCE image (i.e. before rescaling).

  NOTE: If the image is scaled up by more than a factor of 2 then an implicit smoothing operation is enabled (see next option). This is not supported on colour images, and so you can't resample colour images by more than a factor of 2 unless you disable the smoothing.

  Synonyms: -rescale -resample -upsample

-nosmooth
  Disables smoothing after upscaling. Smoothing is normally required to prevent artifacts showing up after stacking with registax.

  Smoothing is ON by default, and you should not turn it off unless you know what you are doing.

  Smoothing is not applied to an image if the scaling factor is <= 2

  Smoothing is not supported on colour images in this version.

-gamma=g
  Adjusts the gamma of the image to g. g should be between 0.3 and 1.5. Gamma values < 1 make the image darker.

  Gamma adjustments are not supported on colour images.

-inputfilter
-inputfilter=F
  Applies a noise reduction filter to the input image before any processing. The parameter F specifies a threshhold between 0.0 and 1.0.

  For each pixel in the input image we calculate a difference value D:

  D = (P-A)/A

  P is the value of the pixel we are considering and A is the modified average of its 8 neighbors.

  A is computed by taking the 8 neighbors and replacing the brightest pixel value with the darkest pixel value. This is done in recognition that most noise will artificially increase pixel values and inflate the average value. Dark pixel values are more likely to be reliable than bright values.

  If D is greater than F then the pixel P is too bright, and we replace P with A.

  If D is less than -F then the pixel is too dark, and we replace P with the value (P+A)/2.

  This filter can be applied multiple times by giving the option more than once. e.g. '-inputfilter -inputfilter' applies the filter twice.

  The default values for F is 0.2. If you want to change this then specify a replacement value with the first filter iteration.

  NOTE: Filtering is not supported on colour images.

-qestimator
-qestimator=min,max
  Enables the quality estimation function. Every image that is processed will also be assessed for image quality, and a file named Quality.txt is written in the current directory at the end of the processing run which lists each output filename and it's computed quality.

  The quality for an image is calculated by generating a series of downsampled images and summing the computed quality of each of those smaller images. This allows the algorithm to reject noise.

  The series of downsampled images is controlled by the two parameters min and max. They represent the smallest and largest divisor that will be used to generate the downsampled images. All integer divisor values between min and max are used.

  The default values are min=3 and max=5, leading to three downsampled images (divisors 3,4,5). You can adjust min and max to accommodate images that are much larger or smaller than normal.

  The quality of each downsampled image is calculated by the sum of squares of differences between adjacent horizontal and vertical pixels. This exaggerates the differences and locates sharp gradients in the image, usually a sign of good quality. Only pixels which have values greater than the background level are considered (see -threshhold);

  Note: The algorithm used here is the same as the gradient algorithm used in Registax, however the implementation used here in ppmcentre allows the algorithm to be examined by the user (via -qwrite) and fine-tuned using the min and max parameters.

  You may find it useful to use the quality estimation function of ppmcentre to "pre-sort" all your frames so you can then select only those that are good enough to load into registax for alignment and stacking.

-qwrite
  This is a debugging option that you might find useful when trying to determing the optimal values for min and max qestimator parameters.

  With this switch enabled ppmcentre will write all the downsampled images that are generated as part of the qestimator function. The images are written in the current directory as 8bpp monochrome PPM format, and are named sample_N.ppm with N being the sample level.

  i.e. in the default case with min=3 and max=5, three images will be generated, sample_3.ppm, sample_4.ppm and sample_5.ppm.

  These images are overwritten for each file that is processed, so if you are using this switch then it only makes sense to process one file.

-renumber
-renumber=first
-renumber=last
  This switch is used in conjunction with -qestimator.

  After all files have been processed, ppmcentre will sort the output files according to their computed quality from best -> worst and then renumber all the output files accordingly.

  For this to work it a requirement that the output filenames contain a number as part of their name, e.g. 00234.bmp.

  The renumbering algorithm locates the numeric portion (either the first or last numeric portion) and changes only that part of the filename, leaving the rest of the filename alone.

  The renumbered part of the filename will start with the letter q followed by that files ranking in the quality list, highest quality will have rank 0.

  e.g. An output file named C:\tmp\00234-red.fit may end up as C:\tmp\q00368-red.fit after renumbering.

(C)Copyright 2005 Anthony Wesley, Canberra Australia