Balloon Analysis#

from pathlib import Path
from dessia_drawing.core import Drawing
from drawing_tools.config.default_language_configs import DEFAULT_ENGLISH_CONFIG, DEFAULT_FRENCH_CONFIG
from drawing_tools.featured_drawing import FeaturedDrawing

_DATA_DIR = Path("data/json")
drawing = Drawing.from_json(str(_DATA_DIR / "2902060102_--A_DEF01_LH SUPPORT ACCUMULATOR ASSEMBLY.json"))
featured_drawing = FeaturedDrawing(drawing, language_configs=[DEFAULT_FRENCH_CONFIG, DEFAULT_ENGLISH_CONFIG])
featured_sheet = featured_drawing.sheets[1]
featured_view = featured_sheet.views[2]

featured_view.plot_data_balloons().plot()
featured_view.plot_data_balloon_flags().plot()
featured_sheet.plot_data_balloons().plot()
featured_sheet.plot_data_balloon_flags().plot()

Analyze balloon symbols (callouts) in technical drawings: detect parent/child groups, identify multiplicator and for-info flags, and extract view repetitions.

Access#

Balloons are analyzed at the view level and exposed as cached_property:

# Per view
featured_view.balloons        # list[Balloon]
featured_view.balloon_count   # int

# Aggregated across all views of a sheet
featured_sheet.balloons       # list[Balloon]

Visualization is available at both levels:

featured_view.plot_data_balloons().plot()       # single view
featured_view.plot_data_balloon_flags().plot()   # flag symbols highlighted

featured_sheet.plot_data_balloons().plot()       # all views on the sheet
featured_sheet.plot_data_balloon_flags().plot()   # flag symbols highlighted

Note

All visualization methods shown in this guide at the view level (plot_data_balloons, plot_data_balloon_flags) have an equivalent at the sheet level on FeaturedSheet. See Display & Report Methods for the complete list of display and report methods.

Pipeline#

The ViewBalloonAnalyzer runs a four-step pipeline per view:

  1. Extract: Collect TypeBalloon symbols from the view annotations

  2. Group: Build a proximity graph and assign parent/child/isolated roles

  3. Assign flags: Detect multiplicator (X3) and for-info (PM/FM) symbols, assign to nearest balloon

  4. Assign repetitions: Read the view title’s repetition count (e.g. “VALABLE 6 FOIS”)

Grouping#

Balloons are grouped based on spatial proximity. Visualizations use color-coded highlights:

  • Blue: parent balloon (has leader arrows)

  • Green: child balloon (no arrows, linked to a parent)

  • Orange: isolated balloon (standalone)

Grouping Criteria#

Two balloons are considered groupable if they meet all three criteria:

  1. Similar size: Diameter difference < 10%

  2. Close enough: Distance between centers < 3 x average radius

  3. Almost aligned: Horizontal OR vertical misalignment < 1 x average radius

Group Status#

Each balloon receives a group status after analysis:

  • “parent”: Has leader arrows and is the group’s reference balloon

  • “child”: No leader arrows, linked to a parent (inherits the parent’s leaders via effective_leader_count)

  • “isolated”: Standalone balloon, not part of any group

  • “undefined”: Edge case — group has 0 or multiple parents

View Repetition#

When a view title contains a repetition count (e.g. “VALABLE 2 FOIS”, “VALID 2 TIMES”), all balloons in that view inherit this value via balloon.repetition. The plot_data_balloons() visualization shows this as a “Rep” label below each balloon.

Source: 2902060102 LH SUPPORT ACCUMULATOR ASSEMBLY, Sheet 1 — COUPE C2-C2 REDRESSEE (5 balloons, all with Rep 2)

Flag Detection#

Multiplicator (X3) and for-info (PM/FM) flags are detected and assigned to their nearest balloon. The plot_data_balloons() view shows the flags on each balloon.

Multiplicator Flags#

Indicate that a balloon reference appears multiple times in the assembly.

  • Pattern: X3, x12, 14X, 21x (letter X + digits, case-insensitive)

  • Filtering: Only horizontal text; must be within 3x the nearest balloon’s diameter

  • Properties: balloon.multiplicator (int | None), balloon.multiplicator_symbol (Symbol | None)

For-Info Flags (PM/FM)#

Mark balloons as informational — different verification rules apply.

  • PM = Pour Memoire / FM = For Memory

  • Detection: Two text elements “PM”+”FM”, or single element “PM”, “PM/FM”, “PR/FM”

  • Properties: balloon.has_for_info_flag (bool), balloon.for_info_flag_symbol (Symbol | None)

Balloon Properties#

Property

Type

Description

text_content

str

The balloon’s text (e.g. “024”, “101”)

center

Point2D

Center position

diameter / radius

float

Balloon size

leader_count

int

Number of leader arrows directly attached

effective_leader_count

int

Effective leaders (own for parent/isolated, parent’s for children)

group_status

str

“parent”, “child”, “isolated”, or “undefined”

parent_balloon

Balloon | None

Reference to parent (None for parent/isolated)

multiplicator

int | None

Multiplier value (e.g. 3 for “X3”)

has_for_info_flag

bool

True if PM/FM flag is attached

repetition

int | None

Repetition count from the view title

drawing_address

str

Drawing grid address

Examples#

Access balloons per view:

from drawing_tools.sheet.featured_sheet import FeaturedSheet

for featured_view in featured_sheet.views:
    if featured_view.balloons:
        print(f"{featured_view.view.name} ({featured_view.balloon_count} balloons):")
        for balloon in featured_view.balloons:
            print(f"  '{balloon.text_content}' — {balloon.group_status}")

Find parent/child groups:

for featured_view in featured_sheet.views:
    parents = [b for b in featured_view.balloons if b.group_status == "parent"]
    for parent in parents:
        children = [
            b for b in featured_view.balloons
            if b.group_status == "child" and b.parent_balloon is parent
        ]
        if children:
            print(f"Parent '{parent.text_content}': {[c.text_content for c in children]}")

Find flagged balloons:

with_mult = [b for b in featured_sheet.balloons if b.multiplicator is not None]
for_info = [b for b in featured_sheet.balloons if b.has_for_info_flag]

Visualization Script#

python scripts/balloons.py