7.2. Αναφορά σεναρίων Python

Αυτό το κεφάλαιο είναι η πλήρης αναφορά για το ενσωματωμένο module Python iqcad του IQcad: κάθε κλάση, μέθοδος, ιδιότητα, decorator και συμβάν, με διαγράμματα κλάσεων σε μορφή κειμένου και πλήρη παραδείγματα.

Για μια εισαγωγή (εκτέλεση σεναρίων, μοντέλο εμπιστοσύνης, προσαρμοσμένες εντολές, η συνολική εικόνα) δείτε Σενάρια Python στο κεφάλαιο 18. Αυτό το κεφάλαιο είναι η αναφορά API στην οποία ανατρέχετε αφού γνωρίζετε τα βασικά.

7.2.1. Εισαγωγή

Το IQcad ενσωματώνει έναν ιδιωτικό, συνοδευτικό διερμηνέα Python 3.12 που διανέμεται στον φάκελο python\ δίπλα στο IQcad.exe. Δεν χρειάζεται καμία εγκατάσταση και δεν απαιτείται ούτε χρησιμοποιείται Python του συστήματος. Κάθε σενάριο εκτελείται με το ενσωματωμένο module iqcad ήδη εισηγμένο, το οποίο εκθέτει ένα αντικειμενοστραφές API σχεδίασης με ρίζα το iqcad.active_drawing, μαζί με ένα σύνολο απλών βοηθητικών συναρτήσεων.

Η αναφορά που ακολουθεί παράγεται από το αρχείο stub τύπων samples\python\iqcad.pyi και αντιστοιχεί ακριβώς σε αυτό. Ρυθμίστε το IDE σας να χρησιμοποιεί αυτό το stub (ή τον συνοδευτικό διερμηνέα) για αυτόματη συμπλήρωση.

7.2.2. Εκτέλεση Python

Πέντε σημεία εισόδου από τη γραμμή εντολών ελέγχουν τον host της Python:

Εντολή	Περιγραφή
`PYTHON <file.py>` (ψευδώνυμο `PY`)	Εκτελεί ένα αρχείο `.py` μία φορά. Ό,τι καταχωρίσει απορρίπτεται μόλις ολοκληρωθεί.
`PYEVAL <expr>`	Υπολογίζει μία έκφραση Python και εμφανίζει το αποτέλεσμα στη γραμμή εντολών (π.χ. `PYEVAL iqcad.active_drawing.name`).
`PYLOAD <file.py>`	Εκτελεί ένα αρχείο και το αφήνει μόνιμο για τη συνεδρία: όσες εντολές `@iqcad.command` ή χειριστές συμβάντων καταχωρίσει παραμένουν ενεργοί μέχρι να κλείσετε το IQcad.
`PYSCRIPTS`	Εμφανίζει τις εντολές που έχουν οριστεί σε Python και είναι καταχωρισμένες αυτή τη στιγμή.
`PYPIP <args>`	Προωθεί τα ορίσματα στο `pip` που εκτελείται μέσα στον συνοδευτικό διερμηνέα.

Προειδοποίηση

Το PYPIP install <pkg> κατεβάζει από το PyPI και επομένως απαιτεί πρόσβαση στο δίκτυο. Πίσω από proxy ή antivirus που παρεμβάλλεται στο TLS, η χειραψία SSL μπορεί να αποτύχει. Εγκαταστήστε από αρχείο wheel εκτός σύνδεσης (PYPIP install C:\wheels\somepkg.whl) ή δώστε τις επιλογές proxy / εμπιστοσύνης του pip (PYPIP install --proxy http://host:port pkg ή --trusted-host pypi.org --trusted-host files.pythonhosted.org).

7.2.2.1. Αυτόματη φόρτωση και εμπιστοσύνη

Κάθε αρχείο .py που τοποθετείται στο %APPDATA%\IQcad\scripts\ φορτώνεται αυτόματα κατά την εκκίνηση. Επειδή ο κώδικας που φορτώνεται αυτόματα εκτελείται χωρίς ερώτηση, το IQcad εμφανίζει έναν διάλογο εμπιστοσύνης περιεχομένου την πρώτη φορά που συναντά ένα σενάριο (και ξανά κάθε φορά που αλλάζει το hash SHA-256 του περιεχομένου του). Ο διάλογος προσφέρει Always, This session ή Never· η επιλογή σας απομνημονεύεται στο %APPDATA%\IQcad\scripts\script_trust.json. Ένα σενάριο που δεν έχετε εμπιστευτεί ποτέ δεν εκτελείται.

7.2.2.2. Απόκριση και Esc

Τα σενάρια εκτελούνται στο νήμα του GUI, οπότε ένας σφιχτός βρόχος μπλοκάρει το περιβάλλον χρήσης για όλη τη διάρκειά του. Σε κάθε βρόχο που μπορεί να διαρκέσει αρκετά, καλείτε περιοδικά το iqcad.yield_(): επεξεργάζεται την ουρά μηνυμάτων ώστε το παράθυρο να παραμένει αποκρίσιμο και επιτρέπει στο Esc να ακυρώσει το σενάριο (εγείροντας ένα KeyboardInterrupt που μπορεί να συλληφθεί). Η μέθοδος γράφεται με κάτω παύλα στο τέλος επειδή το yield είναι δεσμευμένη λέξη της Python.

7.2.2.3. Stubs τύπων

Για αυτόματη συμπλήρωση και έλεγχο τύπων, ρυθμίστε τον επεξεργαστή σας να χρησιμοποιεί το stub samples\python\iqcad.pyi ή τον συνοδευτικό διερμηνέα στο python\.

7.2.3. Το αντικειμενικό μοντέλο

Το module iqcad είναι η ρίζα. Περιέχει τις απλές βοηθητικές συναρτήσεις, τους decorators εντολών/συμβάντων και το δυναμικό χαρακτηριστικό active_drawing. Το active_drawing επιλύεται εκ νέου σε κάθε πρόσβαση (PEP 562) και επιστρέφει το τρέχον Drawing. Το Drawing είναι το εργοστάσιο (factory) για όλα τα υπόλοιπα: δημιουργεί και επιστρέφει αντικείμενα Entity, Surface και Alignment.

iqcad  (module)
|
|-- flat helpers ....... cmd, write_line, point,
|                        add_line/add_circle/add_arc/add_ellipse/
|                        add_rectangle/add_hatch/
|                        add_tunnel_section_line  (return handle str),
|                        create_layer, set_active_layer, zoom_extents
|-- decorators ......... command, on_entity_created,
|                        on_entity_deleted, on_selection_changed,
|                        on / off, unregister_command
|-- yield_() ........... pump UI / allow Esc
|
`-- active_drawing  --->  Drawing   (resolves fresh each access)
                           |
                           |  create/returns
                           |
           +---------------+----------------+
           |               |                |
           v               v                v
        Entity          Surface          Alignment
        (geometry)      (TIN)            (horizontal/vertical)

        add_line/circle/arc/ellipse/rectangle/polyline/
        text/hatch/survey_point/tunnel_section_line  --> Entity
        create_surface / find_surface / surfaces       --> Surface
        create_alignment_from_polyline /
        find_alignment / alignments                    --> Alignment

Σημείωση

Το iqcad.add_line(...) (απλή συνάρτηση) επιστρέφει συμβολοσειρά handle, ενώ το iqcad.active_drawing.add_line(...) (OO) επιστρέφει ένα Entity. Το add_polyline υπάρχει μόνο στο OO API: δεν υπάρχει απλή συνάρτηση iqcad.add_polyline.

7.2.4. Αναφορά κλάσεων

7.2.4.1. Drawing

Λαμβάνεται από το iqcad.active_drawing. Το εργοστάσιο για οντότητες, επιφάνειες και χαράξεις.

Μέλος	Υπογραφή	Επιστρέφει	Περιγραφή
`active_layer`	ιδιότητα (ανάγνωση/εγγραφή)	`str`	Όνομα της τρέχουσας στρώσης.
`name`	ιδιότητα (μόνο ανάγνωση)	`str`	Όνομα σχεδίου.
`layer_names`	ιδιότητα (μόνο ανάγνωση)	`List[str]`	Όλα τα ονόματα στρώσεων.
`add_line`	`add_line(a, b)`	`Entity`	Γραμμή από το σημείο a στο b.
`add_circle`	`add_circle(c, r)`	`Entity`	Κύκλος, κέντρο c, ακτίνα r.
`add_text`	`add_text(pos, text, height)`	`Entity`	Κείμενο στη θέση pos με ύψος height.
`add_polyline`	`add_polyline(pts, closed=False)`	`Entity`	Πολυγραμμή μέσω των pts (μόνο OO).
`add_survey_point`	`add_survey_point(pos, number)`	`Entity`	Σημείο τοπογραφίας με αριθμό number.
`add_arc`	`add_arc(start, mid, end)`	`Entity`	Τόξο τριών σημείων.
`add_ellipse`	`add_ellipse(center, radx, rady, rotation=0.0)`	`Entity`	Έλλειψη με ημιάξονες.
`add_rectangle`	`add_rectangle(c1, c2)`	`Entity`	Ορθογώνιο από απέναντι γωνίες.
`add_hatch`	`add_hatch(points, pattern="ANSI31", angle=0.0, scale=1.0)`	`Entity`	Σκίαση που γεμίζει το όριο points.
`add_tunnel_section_line`	`add_tunnel_section_line(points, closed=False)`	`Entity`	Γραμμή διατομής σήραγγας.
`create_layer`	`create_layer(name, color=...)`	`bool`	Δημιουργεί στρώση· το color είναι δείκτης ACI.
`find_by_handle`	`find_by_handle(h)`	`Optional[Entity]`	Αναζήτηση οντότητας με βάση το handle.
`entities`	`entities()`	`List[Entity]`	Όλες οι οντότητες του σχεδίου.
`selection`	`selection()`	`List[Entity]`	Οι τρέχουσες επιλεγμένες οντότητες.
`zoom_extents`	`zoom_extents()`	`None`	Εστίαση στην έκταση του σχεδίου.
`invalidate`	`invalidate()`	`None`	Επιβολή επανασχεδίασης.
`surfaces`	`surfaces()`	`List[Surface]`	Όλες οι επιφάνειες.
`find_surface`	`find_surface(name)`	`Optional[Surface]`	Αναζήτηση επιφάνειας με βάση το όνομα.
`create_surface`	`create_surface(name, pts)`	`Surface`	Κατασκευή TIN από σημεία `(x, y, z)`.
`alignments`	`alignments()`	`List[Alignment]`	Όλες οι χαράξεις.
`find_alignment`	`find_alignment(name)`	`Optional[Alignment]`	Αναζήτηση χάραξης με βάση το όνομα.
`create_alignment_from_polyline`	`create_alignment_from_polyline(handle, radius=0.0, name="")`	`Alignment`	Κατασκευή χάραξης από οντότητα πολυγραμμής.

7.2.4.2. Entity

Ένα μεμονωμένο αντικείμενο σχεδίου που επιστρέφεται από τις μεθόδους OO add_*.

Μέλος	Υπογραφή	Επιστρέφει	Περιγραφή
`handle`	ιδιότητα (μόνο ανάγνωση)	`str`	Μόνιμο handle.
`type_name`	ιδιότητα (μόνο ανάγνωση)	`str`	`'Line'` \| `'Circle'` \| `'Polyline'` \| `'Text'` \| `'SurveyPoint'` \| …
`layer`	ιδιότητα (ανάγνωση/εγγραφή)	`str`	Όνομα στρώσης.
`color`	ιδιότητα (ανάγνωση/εγγραφή)	`int`	Δείκτης χρώματος ACI.
`points`	ιδιότητα (ανάγνωση/εγγραφή)	`List[Tuple[float, float, float]]`	Σημεία ορισμού.
`delete`	`delete()`	`None`	Αφαιρεί την οντότητα. Κάθε μεταγενέστερη πρόσβαση εγείρει `RuntimeError`.
`get_property`	`get_property(name)`	`bool` \| `int` \| `float` \| `str` \| `None`	Ανάγνωση ιδιότητας με τύπο (π.χ. `'Radius'` κύκλου).
`set_property`	`set_property(name, value)`	`None`	Εγγραφή ιδιότητας με τύπο.

Συνήθη ονόματα για get_property / set_property: κύκλος 'Radius'· έλλειψη 'RadiusX' / 'RadiusY'· κείμενο 'Text' / 'Height'· σημείο τοπογραφίας 'PointNumber' / 'Elevation'.

7.2.4.3. Surface

Μια επιφάνεια TIN που δημιουργείται με το Drawing.create_surface (ή εντοπίζεται μέσω των find_surface / surfaces).

Μέλος	Υπογραφή	Επιστρέφει	Περιγραφή
`name`	ιδιότητα (μόνο ανάγνωση)	`str`	Όνομα επιφάνειας.
`handle`	ιδιότητα (μόνο ανάγνωση)	`str`	Μόνιμο handle.
`elevation_at`	`elevation_at(x, y)`	`Optional[float]`	Παρεμβαλλόμενο Z, ή `None` εκτός του TIN.
`add_point`	`add_point(x, y, z)`	`None`	Εισάγει κορυφή και ανακατασκευάζει το TIN.
`profile_along`	`profile_along(pts)`	`List[Tuple[float, float]]`	Μηκοτομή: λίστα από `(station, z)`.
`volume_to`	`volume_to(other, cell=1.0)`	`Tuple[float, float]`	Προσέγγιση με κάνναβο `(cut, fill)`· όρυγμα όπου η τρέχουσα επιφάνεια είναι πάνω από την other.

7.2.4.4. Alignment

Μια οριζοντιογραφική χάραξη που δημιουργείται με το create_alignment_from_polyline (ή εντοπίζεται μέσω των find_alignment / alignments).

Μέλος	Υπογραφή	Επιστρέφει	Περιγραφή
`name`	ιδιότητα (μόνο ανάγνωση)	`str`	Όνομα χάραξης.
`handle`	ιδιότητα (μόνο ανάγνωση)	`str`	Μόνιμο handle.
`length`	ιδιότητα (μόνο ανάγνωση)	`float`	Συνολικό μήκος.
`start_station`	ιδιότητα (μόνο ανάγνωση)	`float`	Χιλιομετρική θέση αρχής.
`end_station`	ιδιότητα (μόνο ανάγνωση)	`float`	Χιλιομετρική θέση τέλους.
`point_at_station`	`point_at_station(s)`	`Tuple[float, float, float]`	`(x, y, z)` στη χιλιομετρική θέση s.
`direction_at_station`	`direction_at_station(s)`	`float`	Αζιμούθιο στο s, σε ακτίνια.
`elevation_at_station`	`elevation_at_station(s)`	`float`	Υψόμετρο μηκοτομής στο s.
`station_offset_at`	`station_offset_at(x, y)`	`Tuple[float, float]`	`(station, offset)`· απόσταση `-` αριστερά / `+` δεξιά.
`elements`	`elements()`	`List[Dict[str, object]]`	Γεωμετρικά στοιχεία· κλειδιά `kind` / `length` / `start_station` / `radius`.

7.2.4.5. Συναρτήσεις επιπέδου module

Οι απλές βοηθητικές συναρτήσεις και το δυναμικό χαρακτηριστικό active_drawing.

Μέλος	Υπογραφή	Επιστρέφει	Περιγραφή
`active_drawing`	χαρακτηριστικό (μόνο ανάγνωση)	`Drawing`	Το τρέχον σχέδιο· επιλύεται εκ νέου σε κάθε πρόσβαση.
`cmd`	`cmd(s)`	`None`	Εκτελεί μια συμβολοσειρά γραμμής εντολών.
`write_line`	`write_line(s)`	`None`	Εμφανίζει μια γραμμή στη γραμμή εντολών.
`point`	`point(x, y, z=...)`	`Tuple[float, float, float]`	Κατασκευάζει μια πλειάδα (tuple) σημείου.
`add_line`	`add_line(a, b)`	`str`	Απλή γραμμή· επιστρέφει συμβολοσειρά handle.
`add_circle`	`add_circle(c, r)`	`str`	Απλός κύκλος· επιστρέφει συμβολοσειρά handle.
`add_text`	`add_text(pos, text, height)`	`str`	Απλό κείμενο· επιστρέφει συμβολοσειρά handle.
`add_arc`	`add_arc(start, mid, end)`	`str`	Απλό τόξο· επιστρέφει συμβολοσειρά handle.
`add_ellipse`	`add_ellipse(center, radx, rady, rotation=0.0)`	`str`	Απλή έλλειψη· επιστρέφει συμβολοσειρά handle.
`add_rectangle`	`add_rectangle(c1, c2)`	`str`	Απλό ορθογώνιο· επιστρέφει συμβολοσειρά handle.
`add_hatch`	`add_hatch(points, pattern="ANSI31", angle=0.0, scale=1.0)`	`str`	Απλή σκίαση· επιστρέφει συμβολοσειρά handle.
`add_tunnel_section_line`	`add_tunnel_section_line(points, closed=False)`	`str`	Απλή γραμμή διατομής σήραγγας· επιστρέφει συμβολοσειρά handle.
`create_layer`	`create_layer(name, color=...)`	`bool`	Δημιουργεί στρώση (χρώμα ACI color).
`set_active_layer`	`set_active_layer(name)`	`None`	Ορίζει την τρέχουσα στρώση.
`zoom_extents`	`zoom_extents()`	`None`	Εστίαση στην έκταση του σχεδίου.
`unregister_command`	`unregister_command(name)`	`None`	Αφαιρεί μια καταχωρισμένη προσαρμοσμένη εντολή.
`on`	`on(event, func)`	`Callable`	Συνδέει χειριστή συμβάντος με βάση το όνομα.
`off`	`off(event, func)`	`None`	Αποσυνδέει χειριστή συμβάντος.
`yield_`	`yield_()`	`None`	Επεξεργάζεται την ουρά του UI· εγείρει `KeyboardInterrupt` με το Esc.
`show_message`	`show_message(text)`	`None`	Εμφανίζει πλαίσιο μηνύματος.
`confirm`	`confirm(prompt)`	`bool`	Ερώτηση Ναι/Όχι· `True` αν επιβεβαιωθεί.
`input_string`	`input_string(prompt, default="")`	`Optional[str]`	Εισαγωγή κειμένου· `None` αν ακυρωθεί.
`select_file`	`select_file(title="", filter="", save=False)`	`str`	Επιλογέας αρχείου· `''` αν ακυρωθεί.

7.2.5. Decorators και συμβάντα

7.2.5.1. Προσαρμοσμένες εντολές

Διακοσμήστε μια συνάρτηση με @iqcad.command για να καταχωρίσετε μια νέα εντολή IQcad. Φορτώστε την με PYLOAD (ή τοποθετήστε την στον φάκελο αυτόματης φόρτωσης) και μπορείτε να την πληκτρολογείτε στη γραμμή εντολών όπως κάθε ενσωματωμένη εντολή.

@iqcad.command("NAME", aliases="N", category="Tools",
               description="What it does")
def handler(*args):
    ...

Προειδοποίηση

Τα ορίσματα των εντολών φτάνουν ως συμβολοσειρές. Μετατρέψτε τα μόνοι σας (int(args[0]), float(args[1])).

Αφαιρέστε μια καταχώριση με iqcad.unregister_command("NAME").

7.2.5.2. Συμβάντα

Τρεις decorators συμβάντων καταχωρίζουν χειριστές που ενεργοποιούνται όταν αλλάζει το σχέδιο:

Decorator	Ο χειριστής λαμβάνει	Ενεργοποιείται όταν
`@iqcad.on_entity_created`	`fn(entity)` – ένα `Entity`	Δημιουργείται μια οντότητα.
`@iqcad.on_entity_deleted`	`fn(handle)` – ένα handle `str`	Διαγράφεται μια οντότητα.
`@iqcad.on_selection_changed`	`fn(drawing)` – το `Drawing`	Αλλάζει η επιλογή.

Οι χειριστές μπορούν επίσης να συνδεθούν και να αποσυνδεθούν ρητά με iqcad.on(event, func) και iqcad.off(event, func).

Σημείωση

Οι χειριστές εκτελούνται σύγχρονα στο νήμα του GUI. Μια εξαίρεση μέσα σε χειριστή καταγράφεται στη γραμμή εντολών και δεν είναι μοιραία. Δεν υπάρχουν ακόμη on_entity_modified, ούτε συμβάντα κύκλου ζωής σχεδίου ή εντολών.

7.2.6. Διάλογοι

Τέσσερις συναρτήσεις διαλόγων επιπέδου module ζητούν είσοδο από τον χρήστη. Είναι κοινές με τον host της Pascal (δείτε Σενάρια Pascal). Όταν εκτελούνται χωρίς γραφικό περιβάλλον – ή όπου δεν υπάρχει εγκατεστημένος πάροχος GUI – επιστρέφουν ασφαλείς προεπιλογές ώστε ένα σενάριο χωρίς επιτήρηση να μη μπλοκάρει ποτέ: το confirm επιστρέφει False, το input_string επιστρέφει None και το select_file επιστρέφει ''.

Συνάρτηση	Υπογραφή	Επιστρέφει	Περιγραφή
`show_message`	`show_message(text)`	`None`	Εμφανίζει πλαίσιο μηνύματος με το text.
`confirm`	`confirm(prompt)`	`bool`	Ερώτηση Ναι/Όχι· `True` αν ο χρήστης επιβεβαίωσε.
`input_string`	`input_string(prompt, default="")`	`Optional[str]`	Εισαγωγή κειμένου μίας γραμμής· `None` αν ακυρωθεί, αλλιώς η συμβολοσειρά.
`select_file`	`select_file(title="", filter="", save=False)`	`str`	Επιλογέας αρχείου· `''` αν ακυρωθεί. Το filter είναι `Caption\|Mask` διαχωρισμένο με κάθετο (π.χ. `"CSV files\|.csv"`)· το save* επιλέγει διάλογο Open ή Save.

import iqcad

iqcad.show_message("Starting import.")
if iqcad.confirm("Proceed?"):
    name = iqcad.input_string("Layer name", "Design")
    if name is not None:
        path = iqcad.select_file("Open points file", "CSV files|*.csv", False)
        if path:
            iqcad.write_line("import %s onto %s" % (path, name))

7.2.7. Παραδείγματα

Πλήρη παραδείγματα σεναρίων διανέμονται στο samples\python\:

samples\python\01_primitives.py – σχεδίαση γεωμετρίας με το API.
samples\python\02_command.py – καταχώριση προσαρμοσμένης εντολής.
samples\python\03_events.py – σύνδεση χειριστών συμβάντων.
samples\python\04_surface.py – επιφάνειες TIN: δημιουργία, ερωτήματα, μηκοτομή, όγκος.
samples\python\05_alignment.py – χαράξεις από πολυγραμμή.
samples\python\06_civil_workflow.py – χιλιομέτρηση κατά μήκος χάραξης με ταυτόχρονη δειγματοληψία επιφάνειας (το κορυφαίο παράδειγμα).

7.2.7.1. Επιφάνειες

Δημιουργήστε ένα TIN από αρχικά σημεία, κάντε παρεμβολή σε αυτό, πάρτε μια μηκοτομή και στη συνέχεια συγκρίνετε δύο επιφάνειες ως προς τον όγκο (04_surface.py):

import iqcad

d = iqcad.active_drawing

eg = d.create_surface("EG", [
    (0, 0, 10.0), (50, 0, 11.0), (50, 40, 12.5),
    (0, 40, 10.5), (25, 20, 11.2),
])

z = eg.elevation_at(25, 20)            # float, ή None εκτός του TIN
eg.add_point(25, 40, 11.8)             # ανακατασκευάζει το TIN

for station, pz in eg.profile_along([(0, 20), (50, 20)]):
    iqcad.write_line("STA %.3f  Z %.3f" % (station, pz))

fg = d.create_surface("FG", [
    (0, 0, 11.0), (50, 0, 12.0), (50, 40, 13.5),
    (0, 40, 11.5), (25, 20, 12.2),
])
cut, fill = eg.volume_to(fg, cell=1.0) # όρυγμα όπου το EG είναι πάνω από το FG
iqcad.write_line("cut=%.2f  fill=%.2f" % (cut, fill))

7.2.7.2. Χαράξεις

Κατασκευάστε μια χάραξη από πολυγραμμή (απαιτείται ακτίνα συναρμογής για 3+ κορυφές) και στη συνέχεια υποβάλετε ερωτήματα σε αυτή (05_alignment.py):

import iqcad

d = iqcad.active_drawing

# Το add_polyline υπάρχει μόνο στο OO API· κρατήστε το handle για τη δημιουργία της χάραξης.
ph = d.add_polyline([(0, 0), (100, 0), (100, 50), (160, 50)], False).handle
al = d.create_alignment_from_polyline(ph, 20.0, "CL-1")

iqcad.write_line("len=%.3f  STA %.3f..%.3f" % (
    al.length, al.start_station, al.end_station))

x, y, z = al.point_at_station(50.0)
d_rad = al.direction_at_station(50.0)
s, off = al.station_offset_at(50.0, 5.0)   # απόσταση -αριστερά / +δεξιά

for el in al.elements():
    iqcad.write_line("%s len=%.3f R=%.3f" % (
        el["kind"], el["length"], el["radius"]))

7.2.7.3. Συνδυασμένη ροή εργασιών πολιτικού μηχανικού

Το κορυφαίο παράδειγμα: προχωρήστε βηματικά τη χιλιομέτρηση κατά μήκος μιας χάραξης και πάρτε δείγμα της επιφάνειας εδάφους σε κάθε χιλιομετρική θέση (06_civil_workflow.py):

import iqcad

d = iqcad.active_drawing

surf = d.create_surface("EG", [
    (-20, -20, 10.0), (180, -20, 14.0), (180, 80, 16.0),
    (-20, 80, 11.0), (80, 25, 13.0),
])

ph = d.add_polyline([(0, 0), (100, 0), (100, 50), (160, 50)], False).handle
al = d.create_alignment_from_polyline(ph, 20.0, "CL-1")

step = 10.0
s = al.start_station
while s <= al.end_station + 1e-6:
    x, y, z = al.point_at_station(s)
    gz = surf.elevation_at(x, y)           # None εκτός του TIN
    iqcad.write_line("STA %.1f  surf=%.3f" % (
        s, gz if gz is not None else float('nan')))
    s += step

7.2.8. Διάλογοι και πλαίσια μηνυμάτων

Τα σενάρια μπορούν να εμφανίσουν διάλογο παραμέτρων ή πλαίσιο μηνύματος μέσω του ίδιου UI που κατασκευάζει ο host και χρησιμοποιεί το SDK προσθέτων (επομένως δεν υπάρχει εξάρτηση από Tk/Qt).

Το iqcad.create_dialog(title) επιστρέφει ένα αντικείμενο διαλόγου· περιγράψτε τα πεδία, καλέστε execute() και έπειτα διαβάστε τις τιμές:

dlg = iqcad.create_dialog("Draw a shape")
dlg.add_choice("shape", "Shape", ["Rectangle", "Circle"], 0)
dlg.add_float("size",  "Size (m)", 10.0, decimals=2)   # min=0, max=0 → χωρίς όρια
dlg.add_text ("layer", "Layer name", "SHAPES")
dlg.add_color("color", "Color", 0x00B400)              # 0x00BBGGRR
dlg.add_bool ("filled","Filled?", False)
if dlg.execute():
    shape  = dlg.get_choice("shape")   # δείκτης επιλεγμένου στοιχείου
    size   = dlg.get_float("size")
    layer  = dlg.get_text("layer")
    color  = dlg.get_color("color")
    filled = dlg.get_bool("filled")

Δημιουργοί πεδίων: add_text, add_multiline, add_int(…, min=0, max=0), add_float(…, min=0.0, max=0.0, decimals=3), add_bool, add_choice(key, label, options_list, default_index=0), add_file(…, filter='', save=False), add_folder, add_color. Συναρτήσεις ανάγνωσης: get_text (επιστρέφει επίσης το κείμενο της επιλεγμένης επιλογής), get_int, get_float, get_bool, get_choice (δείκτης), get_color. Το execute() επιστρέφει False αν ο χρήστης ακυρώσει.

Το iqcad.message_box(text, caption="", buttons=iqcad.MB_OK, icon=iqcad.MB_ICON_NONE) εμφανίζει πλαίσιο μηνύματος και επιστρέφει το κουμπί που πατήθηκε. Κουμπιά: MB_OK, MB_OKCANCEL, MB_YESNO, MB_YESNOCANCEL· εικονίδια: MB_ICON_NONE/INFO/WARNING/ERROR/QUESTION· αποτελέσματα: MB_RESULT_OK/CANCEL/YES/NO (ένα πλαίσιο που κλείνει χωρίς επιλογή επιστρέφει MB_RESULT_CANCEL).

if iqcad.message_box("Delete selection?", "Confirm",
                     iqcad.MB_YESNO, iqcad.MB_ICON_QUESTION) == iqcad.MB_RESULT_YES:
    pass   # … συνέχεια με τη διαγραφή

7.2.9. Ζωντανές φόρμες

Ενώ ένας διάλογος είναι modal, μια ζωντανή φόρμα είναι ένα μη modal παράθυρο εργαλείου, που ανήκει στον host και παραμένει ανοιχτό: κατασκευάζετε στοιχεία ελέγχου, κρατάτε τα handles τους, τα τροποποιείτε κατά την εκτέλεση και αντιδράτε στις ενέργειες του χρήστη μέσω ενός αντικειμένου χειριστή. Είναι η όψη, για τα σενάρια, των ζωντανών παραθύρων εργαλείων του SDK προσθέτων.

Το iqcad.create_form(title, handler=None) επιστρέφει μια ζωντανή φόρμα. Κατασκευάστε τη με add_button, add_label, add_text, add_multiline, add_int, add_float, add_bool, add_choice, add_color, add_file, add_folder, add_list (καθώς και begin_row / end_row, find_control) και έπειτα καλέστε show(). Κάθε add_* επιστρέφει ένα αντικείμενο στοιχείου ελέγχου με μεθόδους πρόσβασης get_* / set_*, set_caption / set_enabled / set_visible, καθώς και τις λειτουργίες λίστας append_line / clear / item_count / get_selected / set_selected. Η φόρμα προσφέρει επίσης hide(), close(), is_visible() και set_title().

Ο προαιρετικός handler είναι οποιοδήποτε αντικείμενο του οποίου τις μεθόδους on_button_clicked(key), on_value_changed(key) και on_form_closed() καλεί ο host (στο κύριο νήμα) όταν ο χρήστης αλληλεπιδρά με τη φόρμα:

class Handler:
    def __init__(self, form):
        self.form = form
    def on_button_clicked(self, key):
        if key == "add":
            n = self.form.find_control("n").get_int()
            self.form.find_control("log").append_line("Added: %d" % n)
            self.form.find_control("status").set_text("Last added: %d" % n)

form = iqcad.create_form("Form demo")
form.add_label("status", "Click Add to append a value")
form.add_int("n", "Value", 1, 0, 1000)
form.add_button("add", "Add")
form.add_list("log", "Log")
form.handler = Handler(form)        # ή περάστε handler= στο create_form
form.show()

Το iqcad.create_panel(title, handler=None) είναι ίδιο με το create_form αλλά προσαρτά το πάνελ στο κύριο παράθυρο — εμφανίζεται ως καρτέλα στη δεξιά λωρίδα προσάρτησης αντί για αιωρούμενο παράθυρο. Ο δημιουργός, τα αντικείμενα στοιχείων ελέγχου και η διεπαφή του χειριστή είναι ακριβώς τα ίδια· διαφέρει μόνο ο περιέκτης:

panel = iqcad.create_panel("Form demo", handler)   # προσαρτημένο δίδυμο του create_form

7.2.10. Κορδέλα και μενού

Τα iqcad.add_ribbon_button(group, command, caption, hint='', icon='', large=True) και iqcad.add_menu_item(submenu, command, caption) προσθέτουν στοιχεία GUI που εκτελούν μια καταχωρισμένη εντολή — ένα κουμπί στην καρτέλα κορδέλας Plugins και ένα στοιχείο στο μενού Plugins. Τα σενάρια εμφανίζονται κάτω από μία ενιαία ομάδα/υπομενού Scripts· το icon είναι απόλυτη διαδρομή προς αρχείο PNG (παραλείψτε το για γενικό εικονίδιο). Δείτε Συνεισφορές σε κορδέλα και μενού.

@iqcad.command("GREET")
def greet():
    iqcad.message_box("Hello!", "Greet", iqcad.MB_OK, iqcad.MB_ICON_INFO)

iqcad.add_ribbon_button("Demo", "GREET", "Greet", hint="Say hello", large=True)
iqcad.add_menu_item("Demo", "GREET", "Greet")

7.2.11. Περιορισμοί και συμβουλές

Τα ορίσματα εντολών είναι συμβολοσειρές. Το @iqcad.command περνά κάθε όρισμα ως str· μετατρέψτε σε int / float μέσα στη συνάρτησή σας.
Το ``elevation_at`` επιστρέφει None εκτός του TIN. Ελέγχετε πάντα το αποτέλεσμα πριν το χρησιμοποιήσετε σε αριθμητικές πράξεις.
Ακτίνα συναρμογής χάραξης. Το create_alignment_from_polyline με radius=0 (η προεπιλογή) κατασκευάζει ευθείες εφαπτόμενες μέσω κάθε κορυφής, ακόμη και σε πολυγραμμές με 3 ή περισσότερες κορυφές. Δώστε μη μηδενική ακτίνα (τουλάχιστον 0.01) μόνο αν θέλετε οι εσωτερικές γωνίες να στρογγυλευτούν με τόξα.
Πρόσημο απόστασης. Το station_offset_at επιστρέφει απόσταση που είναι αρνητική προς τα αριστερά και θετική προς τα δεξιά ως προς τη φορά της χάραξης.
Περιορισμένη κάλυψη συμβάντων. Σήμερα υπάρχουν μόνο τα συμβάντα δημιουργίας οντότητας, διαγραφής οντότητας και αλλαγής επιλογής. Δεν υπάρχουν ακόμη on_entity_modified, ούτε συμβάντα κύκλου ζωής σχεδίου ή εντολών.
Χωρίς εκτέλεση στο παρασκήνιο / ασύγχρονη εκτέλεση. Τα σενάρια εκτελούνται στο νήμα του GUI· χρησιμοποιήστε το iqcad.yield_() ώστε οι μεγάλοι βρόχοι να παραμένουν αποκρίσιμοι και να ακυρώνονται με Esc.