Margin Detector

Configures how the outside margins of an open book are detected in the Burst Book activity.

Remarks

The Margin Detector defines the logic and thresholds used to identify the left and right margins of a book in a photograph, enabling precise splitting of two-page images and improving the accuracy of downstream dewarping and cropping.

Margin detection is essential when processing photographs of open books, as it determines where each page begins and ends, even in the presence of gutters, curved pages, or inconsistent backgrounds. The settings in this class allow you to tune margin detection for a wide variety of book layouts, lighting conditions, and photographic artifacts.

How Margin Detection Works

1. The input image is divided into horizontal cells spanning the height of the book.
2. Each cell is analyzed to find regions that meet the configured margin criteria (width, noise, alignment, etc.).
3. Detected margin hits are grouped and scored for confidence and straightness.
4. The most likely left and right margin lines are selected for use in page splitting and dewarping.

Configuration Guidance

• Adjust margin width, noise tolerance, and alignment error to match your book and photographic setup.
• Use stricter settings for clean, high-contrast images; relax thresholds for books with curved pages, shadows, or imperfect backgrounds.
• Review diagnostic images to verify margin detection and fine-tune settings as needed.

Diagnostic Artifacts

When diagnostics are enabled, Margin Detector produces the following artifacts to assist with configuration and troubleshooting:

• Margins:
  Annotated images showing detected margin lines and hits.
• Log Messages:
  Warnings or errors if margin detection fails or confidence is low.

These artifacts are available in the diagnostics viewer and are essential for tuning margin detection in challenging scenarios.

Usage Notes

• Margin Detector is typically used as a property of Burst Book and similar activities that process book photographs.
• Proper configuration is critical for accurate page extraction, especially when books are not perfectly flat or lighting is uneven.
• If margin detection fails, review the diagnostic images and adjust property values for your specific use case.

Properties

Name	Type		Description
Minimum Width	String	►	The minimum width required for a region to be considered a valid margin. ConverterUnit Value Converter Default16pt The 'Minimum Width' property sets the smallest allowable width for a detected margin region, helping to filter out narrow gaps or noise that do not represent true book margins. Configuration Guidance Specify the width using unit-aware values (e.g., 16pt, 0.25in, 6mm). Increase this value to ignore thin or spurious regions that may be caused by page curvature, shadows, or printing artifacts. Decrease this value if valid margins are being missed due to narrow book edges or tightly bound pages. Impact Only regions wider than this threshold are considered as potential margins. Setting this value too high may cause valid margins to be ignored; too low may allow noise to be detected as margins. > Example: > For most books, a value of 16pt (about 0.22 inches) is a good starting point.
Maximum Noise	Double	►	The maximum amount of noise tolerated in the margin region, expressed as a percentage of black pixels. ConverterPercent Converter Default5% Min0% Max100% The 'Maximum Noise' property controls how much non-background content (such as text, specks, or shadows) is allowed within a margin region for it to be considered valid. Configuration Guidance Enter a decimal value between 0 and 1 (e.g., 0.05 for 5%). Lower values require cleaner, emptier margins; higher values tolerate more noise or content in the margin area. Increase this value if valid margins are being missed due to minor marks, dust, or page edge artifacts. Impact Margins with a higher percentage of black pixels than this threshold are ignored. Too low a value may cause margins to be missed; too high may allow noisy or printed areas to be detected as margins. > Example: > For most clean book photographs, 0.05 (5%) is sufficient. For older or marked books, try 0.10 (10%).
Maximum Inset	String	►	The minimum distance from the edge of the book to the page margin, used to avoid detecting margins too close to the edge. ConverterUnit Value Converter Default3in The 'Maximum Inset' property defines how far from the outer edge of the book a margin must be found to be considered valid. This helps prevent false margin detection caused by shadows, book curvature, or the edge of the photograph. Configuration Guidance Specify the inset using unit-aware values (e.g., 3in, 75mm). Increase this value to require margins to be further from the book edge, which can help avoid edge artifacts. Decrease this value if valid margins are being missed near the book's edge. Impact Margins detected closer to the edge than this value are ignored. Too high a value may exclude valid margins; too low may allow edge noise to be detected as a margin. > Example: > For most books, 3in is a good starting point. For smaller books, reduce this value accordingly.
Maximum Alignment Error	Double	►	The maximum allowable error in the straightness of a detected margin line. Default6 Min1 Max100 The 'Maximum Alignment Error' property sets the tolerance for how much a detected margin can deviate from a straight line. This helps ensure that only well-aligned, consistent margins are used for page splitting and dewarping. Configuration Guidance Enter a value in pixels (e.g., 6). Lower values require straighter margins; higher values allow for more curvature or irregularity. Increase this value if valid margins are being rejected due to book curvature or camera angle. Impact Margins with alignment error above this threshold are ignored or flagged. Too low a value may reject valid but slightly curved margins; too high may allow poor-quality margins. > Tip: Use diagnostic images to review margin alignment and adjust this value for your specific book and setup.
Minimum Confidence	Double	►	The minimum confidence required for a detected margin to be accepted. ConverterPercent Converter Default75% Min0% Max100% The 'Minimum Confidence' property specifies the lowest confidence score a detected margin must achieve to be used for page splitting and dewarping. Confidence is based on the consistency and clarity of margin detection across the image. Configuration Guidance Enter a decimal value between 0 and 1 (e.g., 0.75 for 75%). Lower this value if valid margins are being rejected due to low confidence, such as in noisy or low-contrast images. Raise this value to require only the most reliable margins to be used. Impact Margins with confidence below this threshold are ignored or flagged for review. Too high a value may cause valid margins to be missed; too low may allow unreliable margins. > Example: > For most scenarios, 0.75 (75%) is a good balance between reliability and flexibility.

Used By

Burst Book