Robotic Telescope - Processing Command Reference

After requested observations are taken and available in the Completed Observations Queue they can be processed in a variety of ways with the #process command. This allows observers to improve their images without the need to use special software on their own computers.

Here is how it works:

• The #process command takes as input one or more image ID numbers and a list of processing "steps". Some processing steps have parameters that must also be provided.
• Any Completed Observations except special observations can be used as the input for a process operation. The split process operation can be used to split multi-image special observations into individual image IDs so that they can be processed.
• Any previously Completed Processing Requests can be used as the input for a new process operation.
• Processing requests are queued and appear on the Queued Processing Requests page. They are completed in sequence when the telescope is not busy. This generally means any time during the day or on cloudy nights. When the telescope is not busy, requests are usually completed within a minute or two.
• When the processing request is completed, the observer is sent a message with a link to the results (which include new fits and jpeg images). The completed requests appear on the Completed Processing Requests page. The jpeg image is also sent to the observer.
• The jpeg image is automatically contrast-stretched to make a recognizable image, except if the image was contrast-stretched as part of the processing operation, in which case it is linear stretched.
• Except for image stacking and making a colour image, up to 10 processing steps can be included in the same request.

Command format:

#process id=xxx steps=step1,step2... step1=value step2=value comment=yyy

where:

• id - this the image ID number that is used as the input for the processing operation. In the case of the "stack" and "makecolour" operations, more than one id is needed and they are to be listed one after another separated by a comma (eg. id=123,456,789).
• steps (or step) - this is the list of processing steps separated by commas (up to 10) from the list described below. They are processed in order. For example: 'steps=gradient,flip,mirror'.
• step1=value, step2=value - some "steps" require parameters. They are provided by using the same name as the step name. For example: "steps=rotate rotate=90" rotates the image by 90 degrees.
• comment - this adds your comment to the processing request. If more than one word is needed, enclose the whole parameter in double-quotes (eg. "comment=sharpening image").

Example:

An example processing request is:

#process id=3227 steps=gradient,rotate,crop rotate=180 crop=90,90

The telescope replies with:

The requested processing operation on ID 3227 (object=NGC2403) is in my queue as ID 3244

When the request is completed, it sends the message:

Your processing request ID 3244 is done: http://www.ap.smu.ca/bgosm/processedid.php?id=3244

(and an image)

List of available processing steps:

• flip
• mirror
• flatten
• gradient
• rotate
• crop
• resize
• fftfilter
• kernelfilter
• stack
• colour
• saturation
• balance
• stretch
• plain
• negative
• split

flip - this operation "flips" the image in the vertical axis.

mirror - this operation "mirrors" the image in the horizontal axis.

flatten - this operation attempts to automatically flatten the sky background in an image. The success of this operation depends on how much of the field is occupied by the astronomical object vs. the sky - too much object and not enough sky can confuse the algorithm and make the image worse.

Important Note: Since the "flatten" algorithm models the sky background in order to flatten it, any abrupt background changes will cause poor results. Abrupt changes can occur near the edges of images due to the image alignment part of an earlier stack or colour step. In these cases, you should precede the "flatten" step with a "crop" step to trim the edges of the image first. For example:

#process id=xxx steps=crop,flatten crop=95,95

gradient - this operation attempts to automatically remove a gradient in the sky background of an image. A gradient can be caused by light pollution, light scatter from the Moon, etc. The success of this operation depends on how much of the field is occupied by the astronomical object vs. the sky - too much object and not enough sky can confuse the algorithm and make the image worse.

Important Note: Since the "gradient" algorithm models the sky background in order to remove the gradient, any abrupt background changes will cause poor results. Abrupt changes can occur near the edges of images due to the image alignment part of the stack or colour steps. In these cases, you should precede the "gradient" step with a "crop" step to trim the edges of the image first. For example:

#process id=xxx steps=crop,gradient crop=95,95

rotate - this "rotates" the image by the specified angle (from -360 to 360 degrees). Negative angles rotate counter-clockwise and positive angles rotate clockwise. For example, the format required to rotate an image clockwise by 45 degrees is:

#process id=xxx steps=rotate rotate=45

crop - this "crops" an image to the specified "width" and "height" (in percent of the original image size) with the upper left corner specified by "left" and "top". This can be used, for example, to crop an image if the target is small or to trim the edges of an image after a "stack" or "colour" operation. If only the "width" and "height" are specified, the cropped area is located at the centre of the image. Values from 10 to 100 percent are valid for left, top, width and height. The values specified must refer to a rectangle contained entirely within the original image, otherwise an error is reported.

For example, to crop an image (centered) to a width of 90% and height of 70% of the original image's size use:

#process id=xxx steps=crop crop=90,70

For example, to crop an image to a width of 60% and height of 40% positioned so the left corner is 10% from the left and 20% from the top use:

#process id=xxx steps=crop crop=10,20,60,40

resize - this "resizes" an image to the specified width and height (in pixels). This is usually used to make the image smaller for posting to the web. If only the width is specified, the height is automatically calculated to maintain the same aspect ratio as the original image. Pixel values from 32 to 4096 are valid for width and height.

For example, to resize an image to 1500x1200 pixels use:

#process id=xxx steps=resize resize=1500,1200

For example, to resize an image to 1024 pixels wide (and with the height automatically determined) use:

#process id=xxx steps=resize resize=1024

fftfilter - this "filters" an image using a 2D Fast Fourier Transform (FFT). It can be used to sharpen or blur images. Sharpening can enhance otherwise invisible details or make stars smaller. Blurring can help reduce noise in an image. The format required is:

#process id=xxx steps=fftfilter fftfilter=mode,level

where:

mode - "sharpen" to sharpen an image (enhances higher frequency details in an image) or "blur" to blur an image.

level - "mild", "medium", or "hard" specify the aggressiveness of the filter. A hard filter has more of the specified effect (sharpen or blur) than a mild filter.

kernelfilter - this "filters" an image using kernel type filters. There are nine different filter types which each alter the image differently - see the descriptions of each below. The format required is:

#process id=xxx steps=kernelfilter kernelfilter=type   OR

#process id=xxx steps=kernelfilter kernelfilter=type,value

Filter types:

stack - This combines (stacks) up to 10 images of the same object (and usually taken through the same filter). This has the effect of improving the quality of the image by reducing image noise and improving image detail. Before the images are stacked, they are aligned with each other using the stars in each image. The "stack" operation cannot be combined with other operations.

The method of stacking is set by the "stack" option as either "average" or "median" - if there is no "stack" option, average is used. The input images are specified with the "id" parameter with each image id given separated by a comma. Examples of the required format are:

#process id=2407,2049,2601 steps=stack stack=average 

#process id=1245,1246 steps=stack stack=median

colour - this makes a colour image from either three (red, green, and blue) or four (luminance, red, green, and blue) filtered images of the same object. Before the images are used, they are aligned with each other using the stars in each image. The "colour" operation cannot be combined with other operations. The input images used to form the colour image are specified with the "id" parameter as a list of image id's in the order R,G,B or R,G,B,L separated by commas. Examples of the required format are:

Make a colour image from red, green, and blue images:

#process id=2407,2049,2601 steps=colour

Make a colour image from red, green, blue, and luminance, images:

#process id=1245,1246,1267,1280 steps=colour

saturation - this adjusts the colour saturation (in percent) of a colour image. A saturation value of less than 100 reduces the colour saturation and a value of greater than 100 increases the colour saturation. If set to 0, the image becomes monochromatic. The largest valid value is 1000. The required format is:

#process id=xxx step=saturation saturation=value

balance - this adjusts the red, green, and blue colour balance (in percent) of a colour image. A balance value of less than 100 reduces the intensity of specified colour - a value of greater than 100 increases the colour's intensity. Valid colour balance values are 1 to 500%. An example of the required format is below (increases red balance, reduces blue balance but leaves the green balance the same):

#process id=xxx steps=balance balance=150,100,80

stretch - this stretches the contrast of an image in four modes: linear, using a logarithmic function, using a gamma function, or using an arcsinh function.

For the linear, log, and gamma stretch types, the input range is from the darkest to brightest pixel in the image. For the arcsinh stretch, the input range can be controlled - see below. The output range is always 0 to 65535. 

The linear stretch type can be used to expand the current range of image values to cover the whole 0 to 65535 range. An example for the required format is:

#process id=xxx steps=stretch stretch=linear

The log stretch type greatly enhances the fainter parts of an image and de-enhances the brighter parts. An example for the required format is:

#process id=xxx steps=stretch stretch=log

The gamma stretch type either enhances fainter parts (gamma values less than one) or brighter parts (gamma values greater than one) of the image depending on the gamma value. Valid values of gamma are from 0.05 to 20. An example for the required format is::

#process id=xxx steps=stretch stretch=gamma,0.1

Important Note: Since the above stretch types operates on the faintest to brightest pixel in the image, any black edges (darker than the real sky background) near the edges of images (usually caused by the image alignment part of a earlier stack or colour step) can cause an undesired result. In these cases, you should precede the "stretch" step with a "crop" step to trim the edges of the image first. For example:

#process id=xxx steps=crop,stretch crop=95,95 stretch=log

It is usually a good idea to follow a log or gamma stretch with a subsequent linear stretch to use the full 0 to 65535 output range.

The arcsinh stretch type is a special mode that enhances fainter parts of the image depending on the power value. It has the following parameters:

base - the base value (as a percentage of the full output range) which is used to control the gray level of the sky background (0 to 100). A value of 6 works well.

power - controls the relative effect of the stretch operation. Valid values of power are from 0.01 to 20. A value of 5 works well for most astronomical objects.

minimum - used to set the brightness level that becomes black. The algorithm computes a histogram of the image (excluding the outer 5% of the image) which it uses as follows:

minimum >= 0: the percentage (0 to 100 as an integer) of the pixels of the histogram that becomes black
minimum = -1: means black becomes the median of the pixel values (this is usually close to the sky background)
minimum = -2: means black becomes 1/4 from the bottom of the sorted pixel values
minimum = -3: means black becomes 1/8 from the bottom of the sorted pixel values
minimum = -4: means black becomes 1/16 from the bottom of the sorted pixel values
minimum = -5: means black becomes 1/32 from the bottom of the sorted pixel values
minimum = -6: means black becomes 1/64 from the bottom of the sorted pixel values

maximum - used to set the brightness level as a percentage of the sorted pixel values from 0 to 100 that become white. A value of 100 ensures that no pixels become over-exposed (more than they already are). Lower values effectively increase the contrast, but will cause some parts of the image (usually the brighter stars) to become over-exposed.

An example that works well for most astronomical objects is:

#process id=xxx steps=stretch stretch=arcsinh,6,5,-1,100 

plain - this causes the imaging annotation (text and observatory logos) to be omitted from the created jpeg image.

negative - this causes the created jpeg image to be negative image. This image format can make it easier to see faint features, particularly when printed on paper.

split- this splits a special observation, which can contain up to 10 images in one or more filters, into separate new Completed Processing Requests. These new requests can be used in subsequent processing requests. The Comment field is updated to include the new image ID numbers. Additionally, if you view the original image ID, links are provided for the individual fits and jpeg image files. The "split" operation cannot be combined with other operations.