SharpCap Collimation Overlay

An IronPython script for SharpCap Pro that automatically detects a defocused star's donut pattern and draws overlay circles to aid collimation of reflector telescopes. It measures the offset between the outer ring (primary mirror) and inner shadow (secondary mirror) in real time, showing you exactly how far off collimation is and which direction to correct.

Requirements

• SharpCap Pro 4.1+ (scripting requires Pro license)
• A connected camera with live preview running
• A bright, defocused star visible in the field of view

Quick Start

1. Connect your camera in SharpCap and start live preview
2. Point at a bright star and defocus until you see a clear donut shape
3. Open the scripting console: Tools > Scripting Console
4. In the console: File > Run Script and select collimation_overlay.py
5. The overlay appears immediately. Click the Coll Settings toolbar button to open the settings palette.

Settings Palette

Click the Coll Settings toolbar button (or type settings() in the console) to open the settings palette. All changes apply live to the overlay in real time.

Display Tab

• Enable Overlay — master on/off toggle
• Detection Circles / Centering Crosshairs — choose between fitted circles or full-diameter crosshairs (mutually exclusive)
• Overlay Details — detailed stats panel (top-left)
• Bottom Numerical Details — X/Y offset readout bar
• Correction Arrows — directional arrows showing which way to adjust

Colors Tab

• Color pickers for all overlay elements (outer circle, inner circle, crosshairs, offset line, text, background)
• Line widths for circles, crosshairs, and offset lines
• Font sizes for info panel, bottom bar, and arrow labels

Detection Tab

• Algorithm — choose the outer edge detection method (see Detection Algorithms)
• Gradient Window — pixel averaging window for gradient-based algorithms (higher = smoother, less sensitive to rings)
• Number of Rays — radial rays cast for edge detection (more = accurate, slower)
• Brightness Threshold — % of peak brightness that defines the donut edge
• Smoothing Factor — exponential smoothing across frames (0 = none, 0.9 = very smooth)
• Tracking validation parameters (radius change limits, center jump limits, stale frame limit)

Performance Tab

• Analysis Interval — analyze every Nth frame (higher = faster but less responsive)

Bottom Buttons

Button	Action
Reset	Reset all settings to defaults
Restart	Full detection restart — clears all tracking and re-searches for the donut
Save	Save current settings to collimation_settings.cfg (persists across sessions)

Detection Algorithms

The script offers three outer edge detection algorithms, selectable from the Detection tab. The inner edge detection (secondary mirror shadow) is the same for all — a simple dark-to-bright threshold crossing that works reliably because the shadow edge is sharp.

Algorithm	Best For	How It Works
Edge to Dark (default)	Stars with prominent diffraction rings	Finds the steepest brightness gradient where the brightness drops below the threshold. Ignores dips between bright diffraction rings.
Steepest Gradient	Clean donuts, dim stars	Finds the single sharpest brightness drop along each ray. Simple and fast, but can latch onto diffraction ring edges.
Threshold Crossing	High-contrast donuts with clean edges	Finds the last point where brightness crosses below the threshold. Very simple and reliable when edges are well-defined.

Tip: If the outer circle wobbles or appears offset on a well-collimated star, try switching algorithms. "Edge to Dark" handles diffraction rings best; "Steepest Gradient" may work better for dim or noisy images.

The Gradient Window setting controls how many pixels are averaged when computing brightness gradients. A larger window (10-15) smooths over diffraction ring structure; a smaller window (3-5) is more precise for clean edges.

Reading the Overlay

Element	Meaning
Red circle	Outer edge of the donut (primary mirror light cone)
Green circle	Inner edge of the donut (secondary mirror shadow)
Yellow crosshair	Center of the outer circle
Green crosshair	Center of the inner circle
Cyan dashed line	Offset vector between the two centers
Cyan arrows	Direction the inner circle needs to move to become concentric
Bottom bar	X and Y offset with correction direction and color-coded severity
Info panel	Full stats: offset in px/%, direction, radii, quality rating

Quality Ratings

Rating	Offset	Meaning
EXCELLENT	< 2%	Nearly concentric
GOOD	< 5%	Minor offset
FAIR	< 10%	Noticeable offset
POOR	< 20%	Significant offset
BAD	> 20%	Major collimation needed

Offset percentage is relative to the outer circle radius.

Tips for Best Results

Star Selection and Brightness

• Choose a bright, isolated star — the script locks onto the brightest object in the frame, so avoid crowded fields or double stars.
• Ideal brightness: Use SharpCap's histogram to check. The peak should land somewhere in the middle third of the histogram (roughly 80-180 on a 0-255 scale). This gives the detector plenty of contrast to work with.
• If the histogram peak is bunched up at the far right, the star is saturated — reduce exposure or gain. If it barely rises above the left side, increase exposure or gain.
• Brighter stars (mag 1-3) are easier to work with since they produce a strong, well-defined donut at shorter exposures.

Defocus Amount

• Defocus the star until the donut is clearly visible with a dark center and a bright ring. You should be able to see the secondary mirror shadow distinctly.
• Ideal donut size: Aim for roughly 100-300 pixels in diameter. The overlay info panel shows the detected outer radius — multiply by 2 for diameter.
• Too small (under ~30px diameter) and the script can't resolve the inner/outer edges. Too large and you lose brightness and contrast.
• A good starting point: defocus until the donut is about 1/4 to 1/3 the width of your frame.

Using SharpCap Features to Improve Detection

• Frame stacking / live stacking: If your donut appears noisy (especially at lower gain or with a dim star), enabling SharpCap's frame stacking can smooth out the noise and give the detector cleaner edges.
• Planet/disk stabilization: If seeing conditions cause the donut to bounce around the frame, SharpCap's stabilization feature can help keep it steady, which improves tracking accuracy and reduces jitter in the overlay.
• ROI (Region of Interest): Setting a smaller ROI around the star in SharpCap speeds up both capture and analysis, letting the script process frames faster.

Troubleshooting

"Searching for donut..." never goes away

• No star visible: Ensure a bright star is in the field of view and the camera is capturing.
• Star not defocused enough: The star needs to show a clear donut shape with a visible dark center. A focused or slightly defocused star that appears as a bright dot will not be detected.
• Star too dim: Increase exposure or gain. The peak brightness must be above 25 (on a 0-255 scale) for detection to trigger. Check the histogram — the peak should be clearly separated from the background noise.
• Star too small: The donut must be at least ~30px in diameter. If it's smaller, defocus more or increase focal length/magnification.
• Donut fills the entire frame: The script needs some dark background around the donut. If the bright ring extends to the frame edges, the edge detection can't find the outer boundary.

Outer circle doesn't match the donut edge well

• Try a different algorithm: Open the settings palette, go to the Detection tab, and switch between algorithms. "Edge to Dark" handles diffraction rings best; "Steepest Gradient" may work better for dim or clean images.
• Adjust Gradient Window: Increase to 12-15 for heavy diffraction rings, decrease to 3-5 for clean edges.
• Adjust Brightness Threshold: If the outer circle is too small, lower the threshold; if too large, raise it.
• Donut is not circular: If the donut is significantly elongated (astigmatism, tilt), the circle fit will be an approximation. The script assumes circular symmetry.

Detection is jittery or unstable

• Poor seeing or low signal-to-noise is the most common cause. Try increasing exposure or enabling stabilization.
• If the donut is noisy, frame stacking can help smooth things out.
• Increase the Smoothing Factor to 0.7-0.85 for more stable tracking (Detection tab in settings palette).

Star moves too far or overlay is lost

• Click Restart in the settings palette, or type restart() in the console. This clears all tracking and re-searches for the donut.
• Re-running the script also works — it automatically cleans up the previous instance.
• Consider enabling SharpCap's stabilization to keep the star centered, or use a tracking mount.

Detection locks onto the wrong feature

• If there are multiple bright objects in the frame, the script will find the brightest one. Center your target star and reduce the field of view or increase zoom if needed.
• Use restart() or click Restart in the palette after repositioning.

Overlay is slow or laggy

• Set a smaller ROI in SharpCap to reduce the area the script needs to analyze.
• Increase Analysis Interval to 3-5 in the Performance tab (analyze fewer frames).

Script errors on startup

• Ensure you have SharpCap Pro (scripting is a Pro feature).
• Ensure a camera is connected and live preview is running before executing the script.
• Run debug() in the console for a full diagnostic dump — paste the output when reporting issues.

Toolbar button doesn't appear

• The button API varies across SharpCap versions. If the button fails to create, the console will show a warning. Use settings() in the console instead.
• Re-running the script automatically removes old buttons before adding new ones.

Still having issues?

If the troubleshooting steps above don't resolve your issue:

1. Type debug() in the SharpCap scripting console and press Enter
2. Wait a couple of seconds for it to complete
3. Copy the entire output (everything between the ==== lines)
4. Post it to the SharpCap forum along with a description of what you're seeing

The debug() output includes your script version, camera settings, detection state, a fresh analysis of the current frame (ray counts, edge spread, brightness profiles), and all configuration — everything needed to diagnose the problem remotely.

Console Commands

Type these in the SharpCap scripting console:

Command	Action
settings()	Open the settings palette
restart()	Full detection restart (same as Restart button)
reset_tracking()	Clear tracking and re-detect the donut
debug()	Full diagnostic dump (version, camera, detection state, live analysis, brightness profiles)
debug_on() / debug_off()	Toggle per-frame debug logging
stop()	Fully stop overlay and remove toolbar button
save_config() / load_config()	Manually save or reload settings
reset_config()	Reset all settings to defaults

Re-running the script automatically cleans up the previous instance (handler, buttons, settings form).

How It Works

1. Hooks into SharpCap's BeforeFrameDisplay event to run on every displayed frame
2. Gets the frame bitmap via GetFrameBitmap() and locks pixel data with LockBits
3. Finds the donut center using a brightness-weighted centroid
4. Casts radial rays outward from the center, detecting inner edges (dark-to-bright) and outer edges (using the selected algorithm)
5. Fits circles to each set of edge points using the Kasa algebraic least-squares method
6. Rejects outlier points and refits iteratively for higher accuracy
7. Applies exponential smoothing across frames to stabilize the overlay
8. Draws the overlay using SharpCap's GetAnnotationGraphics() API (with GetDrawableBitmap() fallback)