Requirements for version 1.2.2:
=======================================================================
* Windows 98, 98SE, 2000 or Windows XP. May also work in Win95 - not
  tested.
* MaxIm DL version 3.07 or later (tested with 3.09)


=======================================================================
INSTALLATION
=======================================================================

1. Run the DeBloomer install file; it will offer to copy itself to the 
   default MaxIm DL installation folder, which is:

   C:\Program Files\Diffraction Limited\MaxIm DL 3\

   If necessary, change this to the location where you installed
   MaxIm DL 3.07 or later.

2. Start MaxIm DL, and click the Plug-in | Add/Remove Plug-in... menu item.
   Click the Browse button and locate the plug-in (navigate to the MaxIm
   DL program folder, and highlight DeBloomer.dll), and click Open. This
   takes you back to the Add/Remove Plug-in dialog; click Close. 

   Note: MaxIm DL will register the DLL with Windows for you. If you
   download an upgrade, the installation process is similar. Unzip to
   the MaxIm DL folder, remove the plug-in, then add it back in. Removing
   then adding properly registers the new version with Windows.


QUICK START
=======================================================================

1. Automatic: make sure that "Automatic limits" is checked

1b. Manual:  Set blooming limit to a value below bloomed pixels;
             Set star limit to about 2-3000 above background.

2. Verify that the following settings are active/set as suggested:

   - "Star rounding active" checked.
   - "Fuzzy fill active" checked.
   - Fuzzy distance set to 4-6
   - Iterations set to 1
   - Noise factor set to 20-40

3. Click the DeBloom button.

ADVANCED: To get the roundest possible stars, use the star rotation
features. This copies the left and right portions of the star to the
top and bottom portions that are mangled by bloomed pixels. Settings:

   - Click the More Options button:
     - "Fix stars by rotation" checked.
     - "Rotate without showing stars first" un-checked.
     - Minimum star size set to 5
     - Star factor set to 15

For more on using star rotation to fix blooms, please go to:

http://www28.pair.com/rwodaski/downloads/debloom/rotation.htm


Evaluating results of deblooming
=======================================================================

Observe the results you get. The following suggestions will help you
make changes to the settings to improve your results:

* Stars have flat tops and bottoms

  - Lower the star limit by 100-500.
  - Make sure "Star round active" is checked.
  - Use advanced star rotation, described above and in the full
    product documentation.

* Portions of bloom remain (sometimes these will be disconnected 
  portions!), or faint ghosting of the blooms can be seen.

  - Lower the Bloom limit by 2500 to 5000 to capture more bloomed
    pixels. (TIP: Pass the cursor over bloomed pixels to make sure
    you know how bright the dimmest bloomed pixels are, and use a
    Bloom limit lower than the dimmest bloomed pixel.)

* Blooming unaffected

  - Could be that the blooming limit is above the typical boom value.
    To correct, make the blooming limit about 3-5000 below the typical
    bloom value.

* Small stars still have blooms, big star blooms removed OK.

  - Click More Options button:
    - Set Scan Length to a smaller number (e.g., 5).

* Little spikes above/below stars, often in pairs like little legs at
  bottom.

  - Use advanced star rotation, described above and in the full
    product documentation.
  - Try using/increasing fuzzy fill.

Features:
=======================================================================
* Completely automatic mode available
* Also supports fine-tuning of blooms visually if desired
* Operates on one image, a portion of an image, or on all open images
* Optimized for the kinds of blooms you deal with every day, from 
  small to large, with all kinds of cameras
* Options for improving roundness of bloomed stars
* Supports multiple iterations on each image
* Variable smoothing of bloom edges
* Auto-detect of blooming limit
* Auto-detect of star limit
* Setting for matching noise level to image's noise level
* Additional options for fine-tuning blooming results (scan length, 
  scan booster)
* Ability to create a map of blooms and stars to help with troubleshooting 
  tough images
* Auto-increment when performing iterations (to increase aggressiveness 
  with each iteration)
* Supports scripting. See end of this document for information on 
  supported properties and methods.
* Graphic analysis of low end of histogram to help set values.
* Ability to evaluate star fix-up visually, one star at a time, if desired.

Recent changes during beta testing:
=======================================================================

(Please read the main descriptions further below for more details!)

* Added the ability to show the extent of blooming in the Rotation
tool. You can show bloomed pixels in bright red, or halftone red.

* Revised the layout of the Rotation tool to make it more flexible and
easier to understand/use.

* Enhanced the Range settings so it is easier to change.

* Revised the code for the centering pop-up to make it faster. For those
who are wondering why I used a manual centering technique, it's not that
I don't try to automate this (the centering you see going in to the
pop-up is the best guess). The bigger the bloom, the harder it is to 
find the center of the star reliably. I use the unbloomer portion of the
star to find a center, but it's just not reliable. The manual centering
method gives you the ability to refine centering, as well as to tailor
the portion of the star used for the rotation (bigger/smaller buttons).

* Added a "Star on", "Star off" button to the centering pop-up, as well
as crosshairs. The cross hairs helps to identify when stars are centered
for rotation; the on/off button lets you quickly see exactly what to
expect from the rotation/centering operation.

* Added a pop-up window that allows you to center the rotated (left and
right) portions of the star, as well as to enlarge/reduce the area that is
rotated. This feature isn't fully documented yet. Turn off "Rotate without
showing stars" to see this manual fine-tuning feature.

* Added "Star factor" and "Fix by rotation." Fix by rotation fixes damaged 
tops and bottoms of stars by rotating the star image and merging that
with the original star image. Lower values are accepted; higher values
are rejected. This has the effect of fixing the lost tops and bottoms
with the left and right sides of the star. The Star factor determines how
far out from the center of the star the rotation applies. Larger numbers
are more aggressive.

* Added an "Analyze" button. It displays a graphic of the low end of
the image histogram, along with some numeric data. The key piece of
information is the value at which the histogram increases most
rapidly. Typically, this is the background level. You can use this tool
to help understand where to set the star limit.

* Added Left Adjust and Right Adjust, values that can help avoid 
ghosting above and below bloomed stars.

* Added a user-settable Star Adjustment value, so that you can control
the default/suggested value for star limit.

* Added major new error checking features.

* Scan length, Scan booster, Auto increment, and Create bloom map have
been moved to a "new options" dialog.

* Fully automatic operation now available: "Automatic limits" checkbox
will set blooming limit and star limit for you. The automatic settings
may not always work, but they provide a good starting point, especially
for new users.

* Star limit suggested setting is back down to 2-3k above background
level. Click on "Star limit" text to get a suggested value.

* You can click on Blooming limit and Star limit text to get
suggested values. (The cursor changes to an up arrow).

* "Fix star tops/bottoms" has been changed to "Star rounding active"

* Several entry boxes are gray. They still work, but they are gray
because they are seldome required.

* The Auto increment setting has been changed dramatically. It now uses
a value of 100 as the default. Larger numbers are more aggressive; small 
numbers are less aggressive.

* The algorithm behind "Fix star tops/bottoms" has been changed 
drastically to make it more natural. If you are doing multiple iterations,
the fix only applies to the last iteration.

* A checkbox has been added: "Fuzzy fill active". When checked, it will
smooth out the rough edges of the bloom near stars. Use the new
parameter "Fuzzy distance" to specify how many pixels the fuzziness 
should cover. Good values are 3-8. The smaller/tighter your stars, the
smaller the distance should be.

* Fill distance is gone. Values other than 1 just did not provide useful
results.

* If you use iterations, you can now use MaxIm's UNDO feature.

* There is a button to reset to default values. Given the new features
and changes in this version, I strongly suggest you click it before
you try working on your first image!


IMPORTANT STUFF TO KNOW
=======================================================================

FEEDBACK: I am interested in getting copies of any images for which you
are unable to get good results. The default settings for the program
should provide good results on most images, but if they don't I want
to know about it so I can try to fix it. Feel free to ZIP up problem
images and email them to me at ronw@nwlink.com.

NOTE: Some problems are very difficult to deal with automatically, and
will require some minor hand touch-up in Photoshop. This mostly 
includes situations where the bloom covers a star, an abrupt change
in brightness of nebulosity, or other features. The software does as
much as it can to reduce the impact of such things, but there will
always be some that aren't dealt with yet! I'll try to add support
for different kinds of situations whenever possible, hence my desire
to receive images that cause trouble.


OPERATION
=======================================================================

To use the plug-in, click on the Plug-in | New Astro Debloomer menu item.
This opens a setup dialog with the following options. The most critical
items are emphasized (Blooming Limit and Star Limit):

------------------------------------------------------------------------
Blooming Limit - All pixels brighter than this value are assumed to be
bloomed pixels. It is VERY IMPORTANT that you get this number right!!!
Use the Information window to pass the cursor over some blooms and get an
idea of how bright they are. Generally, you want to set this value to
at least 1000 ADU less than the typical bloom value. It may work well
even if you set it as much as 10000 less! Experiment.

TIP: Click on "Blooming limit" text to get a suggested value.
------------------------------------------------------------------------


------------------------------------------------------------------------
Star Limit - This is a very sensitive value. It determines what the 
program considers a star. All pixels brighter than this number, and 
dimmer than the Blooming Limit, are considered to be stars. This program
attempts to keep stars round, in part by using this number. This number
should be at least 1000 units brighter than the background, and may be
larger than that. If the number is too small, the program will make
errors in judgment. If the number is too large, stars may wind up with
squarish tops and bottoms. For calibrated images, 3000 seems to be a 
good number, so I'll be changing the default at some point.

CHANGE: The Star Limit is by far the most dominant factor in achieving 
good bloom removal; you can optimize bloom removal in many cases just 
by making sure that your Bloom Limit is reasonable and then adjusting 
the Star Limit.

TIP: Click on "Star limit" text to get a suggested value.
------------------------------------------------------------------------


Fuzzy distance - Determines how far away from the bloom the program
should apply smoothing. Only applies if "Fuzzy fill active" checkbox
is checked.

Iterations - The number of times the program must process the image to
get a good result. For very small blooms, one interation will be good.
FOr average blooms, two iterations is usually the ticket. For very
severe blooms, larger numbers of iterations may be required.

Noise factor - Allows you to tailor the noise level in the data that
fills in the blooms. Larger numbers make for greater noise. The
idea is to match the noise level to the noise level already
present in the image, so that blooms are more seamless.

Checkboxes:

Apply to all open images - applies the deblooming operation to each
open image in turn.

Star rounding active - boosts brightness at the top and bottom of
large stars to help alleviate chopped look from aggressive bloom
removal. If you do more than one iteration, this effect will
only be applied on the last iteration. This prevents the fix from
softening the tips of blooms, allowing blooms to be properly
recognized in subequent iterations. NOTE: This option provides mild
star rounding; for more aggressive/advanced star rounding, try using
star rotation instead.

Fuzzy fill active - When checked, the program will smooth out rough
edges of the bloom. This helps to keep stars round.

Automatic limits - When checked, the program will calculate its best
guess for the Blooming limit and Star limit for each image processed.
Ideal for processing dissimilar images. It's also a great way to get
close on your first attempt. You can then tweak these two settings
to get best possible results.

More Options button reveals these additional options:
----------------------------------------------------------------------
Scan Length - (was Star Size) this is the value for a typical star, in 
pixels. In practice, I have found that the default value of 9 works for 
all kinds of stars, large and small, so you may not need to change this. 
It could go away if it doesn't prove useful. However, as with all of 
these, feel free to try various settings to see if the improve/ruin 
your results!

Scan booster - (was Star reduction factor) This value increases or
decreases the Scan Length value when scanning for stars. A large value
will help root out larger blooms, but may compromise stars by lopping
off tops and/or bottoms a bit.

Auto increment - Determines how aggressively the program should hunt
down and destroy blooming during iterations after the first one. The
default setting has been changed to 100. This parameter increases the
Star Limit in each iteration. Values over 100 increase the star limit
more aggressively; values under 100 have less impact.

Star limit adjust - When you ask DeBloomer to automatically set or
suggest the value for Star limit, it find the average background
value and adds this number to it. This allows you to customize the
automatic setting for your typical images.

Left Adjustment - When filling in the bloomed pixels, adjusts the 
starting value for the left edge of the bloom by the amount specified.
For example, if the left edge is slightly brighter due to flaring of
the bloom or whatever cause, you can enter a negative number here
to prevent a dim, broad bright fill for the bloom.

Right Adjustment - same as above, but for the right side of the bloom.

NOTE: Left and Right adjustment values are never saved to the registry.
These values are typically suited only to one image at a time, and 
could be annoying if you forgot to change them back.

Create bloom map - instead of removing blooms, the image is scanned
and a map of blooms and stars is created. The blooms will be
bright, and the stars will be gray. If you are having trouble with
settings or in getting bloom removal done right, you can use a
map to help figure out what's going wrong. Are the stars that the
program is identifying too large? Raise the star limit. Is 
blooming overly agressive because stars are too small? Lower the
star limit. Is there a complete failure to find any blooms? The
Blooming limit is probably too high. And so on.

Fix by rotation - When checked, the debloomer will make a copy of a
star, rotate it 90 degrees, and then use that to fix up the top and
bottom edges of the star. Typically, the blooms run right through the
star, obliterating the data for the tops and bottoms. When rotation
is on, the left and right edges of bloomed stars are used to fix 
up the tops and bottoms. Keep an eye out for small, nearby stars 
that get copied at the same time! Replacement stars are displayed 
for evaluation (if "Rotate without showing stars first" is left
unchecked). This gives you the choice of applying rotation for each 
star. You can set a larger or smaller "Min. star size" to determine
the smallest star presented for evaluation. During evaluation, you
can adjust the x,y coordinate of the rotation and the size of the
rotated image.

Rotate without showing stars first - Performs star rotation to fix up
blooms nears stars without showing you the rotated star first. In 
other words, this turns on automatic mode. NOTE: Blooming makes it
difficult to accurately find star centers, so most images will look
their best if you use visual evaluation. Use this setting with
caution!

Offset fill source by fuzzy fill distance - Normally, DeBloomer uses
the pixels immediately adjacent to the bloom as the source location
for determining the fill that replaces the bloom. If this checkbox is
checked, DeBloomer will look away from the bloom for the fill values.
The only time you should need to check this is when you are doing
something that DeBloomer is not designed for: removing blooms from
combined images instead of single images. When you combine, the
bloom values get highly variable and it is impossible to find the
exact limits of the bloom. A side effect of this is that the program
picks up "hot" pixels for the fill, leading to streaks that look
like un-removed bloom. Checking this box will force the program to
search further away for fill pixels. If blooms are near the edge of
the image or drag rectangle, this solution may fail, however.

Min. star size - When performing rotation, this is the smallest star
that will be shown to you for evaluation. A value of 3-4 will show 
lots of stars; a value of 8 will show only larger stars.

Star factor - determines how far out from the center of the star the 
debloomer will make changes when "Fix by rotation" is checked. A value
of 15 or 16 is typically a good match for most cameras, but smaller or
larger values may be required for some stars. You can set this value 
interactively while visually evaluating rotation results.

Rotation Adjustments dialog
----------------------------------------------------------------------
(This dialog appears during star evaluation when "Fix by rotaion" is
active and "Rotate without showing stars first" is unchecked.)

Yes - Applies the current rotation adjustments to the displayed star.

No - No rotation is applied to the displayed star.

Yes to all - Applies rotation adjustments to all stars automatically.
If "Remember adjust" is checked, the current x, y, and Star factor 
settings are used. If it is unchecked, x=0, y=0, and star factor is
unchanged for all subsequent stars.

No to all - No rotation is applied to this and all subsequent stars.

Minimum star size - Same as "Min. star size" on "More options" dialog.
Allows you to change the minimum star size if you decide that too
many or too few stars are appearing for evaluation.

? - Click for an explanation of why manual evaluation is used in
addition to automatic:

"Why use manual centering for rotation?

"Bloomed pixels obliterate a major portion of a star. This makes it 
very, very difficult to locate the star center accurately. The software 
does do its best to find the star center, but manual centering is still 
available as an option for those cases where the blooming makes it 
impossible to locate the star center automatically. The worse the 
blooming, the harder it is to find star centers accurately."

Cross hairs on - When checked, cross hairs are added to the evaluation
image. The cross hairs mark the center of the rotated star image.

Paste adjust section:
----------------------------------------------------------------------
This section controls the X/Y position of the rotated star image that
is pasted over the bloomed star to make it round at top and bottom.

Up, < (Left), > (Right), Down buttons - Adjust the position of the rotated
star image in the indicated directions. X and Y values that result are
displayed in the title bar of the Rotation Adjustments window.

Remember adjustments - When checked, the X, Y, and Bigger/Smaller values 
from the current star are carried forward to the next star.

Display options, Show all - Shows the star and the rotated data together.

Display options, Hide paste - hides the rotated data that is pasted onto
the star (the rotated data). Useful for comparing original and fixed
versions.

Display options, Hide star - hides the star, and shows the rotated data.
Useful when working with the Source centroid adjustments, desribed below.

>> button - Displays additional options described below.

Source centroid adjust section:
----------------------------------------------------------------------
This section controls how the rotated image is extracted from the
source image. If blooming is especially bad, this section will allow you
to change how the program extracts the rotation data by adjusting the
centroid of the extraction, and the size of the extraction.

Bigger - Expands the size of the rotated star image. If too large,
excess background will be copies. If too small, the rotated image
will be smaller than the star size. The initial value is controlled
by the "Star factor" setting on the "More options" dialog. The current
value of Star factor is displayed in the title bar of the Rotation 
Adjustments window. 

Smaller - Shrinks the size of the rotated star image. See "Bigger" for
more details.


SCRIPTING
=======================================================================
You can create an instance of the DeBloomer plug-in for use in
scripting.

To create an object in Visual Basic:

    Set debloomer = CreateObject("DeBloomer.Plugin")

For most applications, automated bloom and star limits are best. The
following sample code sets the settings and calls the call:

Dim myDoc as Object    ' You must declare it as an Object type!
Set myDoc = CreateObject("MaxIm.Document")
myDoc.OpenFile "C:\somefolder\myimage.fit"
fixAllBlooms(myDoc)
' The document is left in a changed state, but is not saved.
' You can now save the document or do whatever else you need to do.

' Sub called above:
Public Sub fixAllBlooms(inDoc As Object)
    Dim fltr as Object

    Set fltr = CreateObject("DeBloomer.Plugin")
    ' Save changed settings to registry so they will be loaded
    '   the next time DeBloomer is run manually?
    If savingSettings Then
        fltr.saveSettings = True
    End If

    ' Set up options; note data types!
    '   numbers are Doubles; checkboxes are Integers.
    fltr.bloomLimit = CDbl(frmBloomRemoval.txtBloomLimit)
    fltr.starLimit = CDbl(frmBloomRemoval.txtStarLimit)
    fltr.fuzzyDistance = CDbl(frmBloomRemoval.txtFillDistance)
    fltr.iterations = CDbl(frmBloomRemoval.txtBloomIterations)
    fltr.noiseFactor = CDbl(frmBloomRemoval.txtNoiseFactor)
    fltr.starRounding = CInt(frmBloomRemoval.chkFixTopBottom.Value)
    fltr.fuzzyActive = CInt(frmBloomRemoval.chkFuzzy.Value)
    fltr.autoLimits = CInt(frmBloomRemoval.chkAuto.Value)
    fltr.starSize = CDbl(frmBloomRemoval.txtStarSize)
    fltr.AutoIncrement = CDbl(frmBloomRemoval.txtBloomIncrement)
    fltr.starAdjustment = CDbl(frmBloomRemoval.txtStarAdjust)
    fltr.leftAdjustment = CDbl(frmBloomRemoval.txtLeftAdjust)
    fltr.rightAdjustment = CDbl(frmBloomRemoval.txtRightAdjust)
    fltr.fixByRotation = CInt(frmBloomRemoval.chkRotate.Value)
    fltr.displayRotatedStars = CInt(frmBloomRemoval.chkNoStars.Value)
    fltr.minStarSize = CDbl(frmBloomRemoval.txtMinStarSize)
    fltr.starFactor = CDbl(frmBloomRemoval.txtStarFactor)
    
    ' Perform deblooming.
    fltr.deBloom inDoc

    ' Clean up object we created.
    Set fltr = Nothing
End Sub


Properties:

debloomer.saveSettings As Boolean
----------------------------------
When set to True, the settings you set in script are saved to the 
Windows registry, and will be the settings used for all subsequent
deblooming operations, manual or scripted, until the settings are 
changed. When set to false, settings are only valid for the 
current session.

debloomer.bloomLimit As Double
----------------------------------
Same as the Blooming limit in the plug-in.

debloomer.starLimit As Double
----------------------------------
Same as the Star limit in the plug-in.

debloomer.fuzzyDistance As Double
----------------------------------
Same as Fuzzy distance in the plug-in.

debloomer.iterations As Double
----------------------------------
Same as Iterations in the plug-in. Number of passes to make with
each image.

debloomer.noiseFactor As Double
----------------------------------
Same as the Noise factor in the plug-in.

debloomer.applyAll As Integer
----------------------------------
Same as the "Apply to all open images" checkbox in the plug-in.

debloomer.starRounding As Integer
----------------------------------
Same as the "Star rounding active" checkbox in the plug-in.

debloomer.fuzzyActive As Integer
----------------------------------
Same as the "Fuzzy fill active" checkbox in the plug-in.

debloomer.autoLimits As Integer
----------------------------------
Same as the "Automatic limits" checkbox in the plug-in.

debloomer.fixByRotation As Integer
----------------------------------
Same as the "Fix by rotation" checkbox in the plug-in.

debloomer.starFactor As Integer
----------------------------------
Same as "Star factor" in the plug-in.

debloomer.starAdjustment As Double
----------------------------------
The automatic star limit measures the background level, and then adds
this value to the background to determine the star limit. You can
adjust this value up or down to suit your typical images. The default
is 3500, which may be too low for some cameras, and too high for
others.  If the star limit is too low, you will get partial bloom
removal, ghosts of blooms, etc. If the star limit is too high, the
bottoms of stars will be slightly flattened.

debloomer.leftAdjustment As Double
----------------------------------
When filling in the bloomed pixels, adjusts the starting value for
the left edge of the bloom by the amount specified.

debloomer.rightAdjustment As Double
----------------------------------
When filling in the bloomed pixels, adjusts the starting value for
the right edge of the bloom by the amount specified.

debloomer.displayRotatedStars as Integer
----------------------------------
Same as "Rotate without showing stars first" checkbox.

debloomer.minStarSize as Double
----------------------------------
Same as "Min. star size" in the plug-in.

Methods:

debloomer.deBloom(inDoc As Object)
----------------------------------
Takes a Maxim.Document object as its arguement. Specifies the
document that is to be debloomed. Returns nothing. Note that
you must declare the object as object, not as a MaxIm DL
Document!



=======================================================================

Thanks!

Ron Wodaski
ronw@nwlink.com
425-844-0323
