Script Templates

Script Templates

Ready-to-use starting points for writing new scripts. Templates live in setup/templates/ in the repository — copy the one that matches your use case, rename it with Snake_Case_Descriptive_Name.py, and work through the EDIT: and # TODO: markers.

---

Choosing a Template

Template	Document	GUI dialog	Saves settings	Progress bar
any_document_basic.py	Any	No	No	No
any_document_dialog.py	Any	Yes	No	No
part_document_basic.py	CATPart	No	No	No
part_document_dialog.py	CATPart	Yes	No	No
part_document_dialog_persistence.py	CATPart	Yes	Yes	No
part_document_dialog_persistence_progress.py	CATPart	Yes	Yes	Yes
process_document_basic.py	CATProcess	No	No	No
process_document_dialog.py	CATProcess	Yes	No	No
process_document_dialog_persistence.py	CATProcess	Yes	Yes	No
product_document_basic.py	CATProduct	No	No	No

When to use each variant:

• Basic — script runs silently with no user input (e.g. hide all planes, batch export)
• Dialog — script needs one-time inputs from the user that do not need to be remembered
• Dialog + Persistence — script has configurable settings the user will reuse across sessions (e.g. limit values, output paths, toggle options)
• Dialog + Persistence + Progress — same as above, but the operation is slow enough to warrant a progress bar (geometry generation, large batch operations)

---

Template Anatomy

Every template follows the same structure:

1. Metadata Header

'''
    -----------------------------------------------------------------------------------------------------------------------
    Script name:    Your_Script_Name.py
    ...
    -----------------------------------------------------------------------------------------------------------------------
'''

Fill in every field. CatiaMenuWin32 reads Purpose for the button subtitle and Description for the Script Details panel. See Writing Scripts for full header rules.

2. Imports

Standard block at the top. Only add what the script actually uses.

3. Helper Functions (optional)

Place utility functions — geometry helpers, recursive searches, datum creators — between the imports and if __name__ == "__main__":. Keep them pure (no side effects, no global state).

All Part Document templates already include searchHybridBody and create_datum. Additional helpers (searchHybridBodyWithPath, collect_all_names, coordinate maths, get_path) are available in setup/templates/common_functions.py — copy what you need. See Common Functions for the full reference.

4. Entry Point

All CATIA interaction happens inside if __name__ == "__main__":. This is the standard Python pattern that prevents the code running when the file is imported, and is required for the app's hash check to work correctly.

5. Document Type Check

Every template checks the active document type before doing any work and exits with a clear message if the wrong type is open.

6. Dialog Class (dialog templates only)

The ScriptDialog class is defined before if __name__ == "__main__":. It reads saved settings on __init__ and exposes field values as instance attributes for the main block to read after ShowModal().

7. Persistent Data (persistence templates only)

SETTINGS_DIR and SETTINGS_FILE are set at the top of if __name__ == "__main__":. See Writing Scripts#Persistent Data for the full pattern and rules.

---

Markers

Marker	Meaning
EDIT:	Replace this value — it is wrong for your script as-is
# TODO:	Add your logic here
#EDIT:	Inline comment flagging a value that must be changed

All EDIT: text in the header, dialog title, field labels, defaults, and SETTINGS_DIR name must be replaced before the script is usable.

---

Step-by-Step: Starting from a Template

1. Copy the template file to the correct script folder (Part_Document_Scripts/, Process_Document_Scripts/, etc.)
2. Rename it: Snake_Case_Descriptive_Name.py
3. Update the metadata header — Script name, Purpose, Author, Date, Description, dependencies, requirements
4. For persistence templates: change Your_Script_Name in SETTINGS_DIR to match the exact filename (without .py)
5. Add your parameter fields to ScriptDialog.__init__ — duplicate the StaticText + TextCtrl rows and update hardcoded_defaults
6. Update on_reset to set every field back to its hardcoded default
7. Add your field names to get_settings_to_save() (process persistence template) or the inline json.dump dict (part persistence templates)
8. Replace the # TODO: comment in the main block with your script logic
9. Add any pip packages required to setup/requirements.txt
10. Test with CATIA V5 running and confirm the tooltip shows correctly in CatiaMenuWin32

---

Examples

See these scripts for complete real-world implementations of each pattern:

Pattern	Example script
Part — dialog + persistence + progress	Involute Gear Generator
Process — dialog + persistence	Check Operation Parameters Against Limits
Process — basic	Export NC Program Names To CSV
Part — basic	Batch Isolate Geometric Set
Product — basic	Save Child Parts To STEP
Any — dialog	Find And Select By Name