Register Python callback functions that will be called by Instant Terra Pro during certain operations, in particular all file read and write operations.
How to register a Python callback function?
When launching the application, Instant Terra Pro will search for the Documents/Instant Terra/instant_terra.py file.
If this file exists, it is executed.
In this Python file, you must first import the InstantTerraApplication class using the following lines:
import sys
sys.path.append("C:/Program Files (x86)/Wysilab/InstantTerra")
from wysilab.instant_terra_application import InstantTerraApplication;
Then there are up to 21 callback functions that can be registered through this class:
# Application
InstantTerraApplication.callback_application_closed = "application_closed"
# Project
InstantTerraApplication.callback_before_project_loaded = "before_project_loaded"
InstantTerraApplication.callback_after_project_loaded = "after_project_loaded"
InstantTerraApplication.callback_before_project_saved = "before_project_saved"
InstantTerraApplication.callback_after_project_saved = "after_project_saved"
# Painted masks
InstantTerraApplication.callback_before_painted_mask_loaded = "before_painted_mask_loaded"
InstantTerraApplication.callback_after_painted_mask_loaded = "after_painted_mask_loaded"
InstantTerraApplication.callback_before_painted_mask_saved = "before_painted_mask_saved"
InstantTerraApplication.callback_after_painted_mask_saved = "after_painted_mask_saved"
InstantTerraApplication.callback_before_painted_mask_deleted = "before_painted_mask_deleted"
InstantTerraApplication.callback_after_painted_mask_deleted = "after_painted_mask_deleted"
# Image and mesh import
InstantTerraApplication.callback_before_image_file_imported = "before_image_file_imported"
InstantTerraApplication.callback_after_image_file_imported = "after_image_file_imported"
InstantTerraApplication.callback_before_mesh_file_imported = "before_mesh_file_imported"
InstantTerraApplication.callback_after_mesh_file_imported = "after_mesh_file_imported"
# Image and mesh export
InstantTerraApplication.callback_before_image_file_exported = "before_image_file_exported"
InstantTerraApplication.callback_after_image_file_exported = "after_image_file_exported"
InstantTerraApplication.callback_before_mesh_file_exported = "before_mesh_file_exported"
InstantTerraApplication.callback_after_mesh_file_exported = "after_mesh_file_exported"
# Component import
InstantTerraApplication.callback_before_component_library_imported = "before_component_library_imported"
InstantTerraApplication.callback_after_component_library_imported = "after_component_library_imported"
# Component export
InstantTerraApplication.callback_before_component_library_exported = "before_component_library_exported"
InstantTerraApplication.callback_after_component_library_exported = "after_component_library_exported"
A callback function is registered by providing the name of a function as a character string.
Callback function parameters
The callback function associated with the "application closed" event must not take any parameters.
All other callback functions must receive a single parameter which is the full name (directory + file name + extension) of the file concerned by the operation in progress, for example the name of the project to open or the name of the file in which to export .
Return value of callback functions
The callback functions associated with the "application closed" and "after..." events do not need to return a return value. The return value is ignored.
The callback functions associated with "before..." events have the possibility of canceling the operation in progress, for example the opening of a project, or the export of a mesh or a color map.
The operation is as follows:
- If the callback function returns nothing, the operation is authorized.
- If the callback function returns a character string, Instant Terra Pro displays this character string in a window, and cancels the operation.
Example:
import sys
sys.path.append("C:/Program Files (x86)/Wysilab/InstantTerra")
from wysilab.instant_terra_application import InstantTerraApplication
def before_project_loaded(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to load the following project: " + path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
This function asks the user if he authorizes the opening of the project:
- If the user clicks Yes, the function returns nothing, so the operation continues normally.
- If the user clicks No, the function returns a character string. This channel is displayed by Instant Terra Pro:
Then the operation, in this case the opening of the project, is canceled.
The different callbacks:
| Callback name | The callback function is called when... | Settings | Return value |
|---|---|---|---|
| callback_application_closed | application is closed | None | None |
| callback_before_project_loaded | before the opening of a .terrain project | The full name of the .terrain file | If the callback function returns no value, the operation is authorized. If the callback returns a string, this string is displayed in a window by instant Terra Pro then the operation is cancelled. |
| callback_before_project_saved | before saving a .terrain project | ||
| callback_before_painted_mask_loaded | before a painted mask is loaded | The full name of the file to import | |
| callback_before_painted_mask_saved | before a painted mask is saved this callback is not called if the painted masks have not been modified |
The full name of the file to save | |
| callback_before_painted_mask_deleted | before a painted mask file is deleted, because the corresponding Painted mask node has been deleted, at the time of the saving of the project | The full name of the file to delete | If the callback function returns no value, the operation is authorized. If the callback returns a string, this string is displayed in a window by instant Terra Pro, the file is not deleted but the project is saved. |
| callback_after_painted_mask_deleted | after a painted mask file is deleted, because the corresponding Painted mask node has been deleted, at the time of the saving of the project | ||
| callback_before_image_file_imported | before an image file is imported | The full name of the file to import | If the callback function returns no value, the operation is authorized. If the callback returns a string, this string is displayed in a window by instant Terra Pro then the operation is cancelled. |
| callback_before_mesh_file_imported | before a file of type mesh is imported | ||
| callback_before_image_file_exported | before an image file is exported | The full name of the file to export | |
| callback_before_mesh_file_exported | before a file of type mesh is exported | ||
| callback_before_component_library_imported | before a .terralib component library file is imported | The full name of the .terralib file | |
| callback_before_component_library_exported | before a .terralib component library file is exported | ||
| callback_after_project_loaded | once a .terrain project has been opened | The full name of the .terrain file | None |
| callback_after_project_saved | once a .terrain project has been saved | ||
| callback_after_painted_mask_loaded | once the painted mask file has been loaded | The full name of the mask file | |
| callback_after_painted_mask_saved | once the painted mask file has been saved this callback is not called if the painted masks have not been modified |
||
| callback_after_image_file_imported | once an image file has been imported | The full name of the file to import | |
| callback_after_mesh_file_imported | once a file of type mesh has been imported | ||
| callback_after_image_file_imported | once an image file has been exported | The full name of the file to export | |
| callback_after_mesh_file_imported | once a file of type mesh has been exported | ||
| callback_after_component_library_imported | once a .terralib component library file has been imported | The full name of the .terralib file Settings | |
| callback_after_component_library_exported | once a .terralib component library file has been exported |
When an operation fails or is canceled by the user,
we will have a callback call "before" callback call "after".
A "before" callback can be called several times. This does not mean
that Instant Terra Pro will read the entire file multiple times,
but simply that Instant Terra Pro will access the file multiple
times. For example, when importing an image file, Instant Terra Pro
can access the file one or more times to read its header, then once
more to read the rest of the file.
Important: the independence of callbacks
Each callback function must be entirely autonomous, that is to say not depend on the rest of the content of the file. The reason for this is that each callback function is called regardless of any context.
Example:
ifrom my_module import my_class
def my callback():
my_class.Do()
Error, unable to access my_class which was imported outside of my_callback.
def my callback():
from my_module import my_class
my_class.Do()
The code is correct.
a = 2
def my callback():
from my_module import my_class
my_class.Do(a)
Error, unable to access variable a which was declared outside of my_callback.
def my callback():
from my_module import my_class
a = 2
my_class.Do(a)
The code is correct.
def my function():
...
def my callback():
my_function()
Error, unable to access my_function. To call a function, it is essential to put it in another module and to import the module inside the callback function.
Recommendation
The easiest way is to have callback functions that do exactly two lines:
- A line to import the class or function to call
- A second to call the imported function
In case of error executing the Python script
In the event of an error executing the Python script, the error is displayed by Instant Terra:
Note, the window may be hidden by others, in particular by the "Splash screen" window of Instant Terra Pro.
If the "Splash screen" window of Instant Terra Pro remains displayed for a long time with the message "Executing Python script instant_terra.py", check with Alt+Tab if there is not an error window which appeared and which is not visible.
In some cases, Alt+Tab does not display the window containing the error message. You must then use Windows Task Manager, find the Instant Terra process:
It is then possible to open the contextual menu on the Python script execution line, and choose Bring to foreground.
Is it possible to modify the file that is read by Instant Terra Pro?
Yes. Documents/Instant Terra/instant_terra.py is the default file, but you can change it.
To do this, use the menu Edit > Preferences > Global settings…
A dialog window appears:
Click on Custom file, then enter a Python file name. For example, it is possible to use a file stored in a shared directory, which allows all Instant Terra users to use the same file.
Complete example
Here is a complete example which displays a message for each operation, and which allows the user to cancel each operation.
Note that each callback function is independent and imports everything it needs.
You can use this example as a starting point to create your own file.
import ctypes
import sys
sys.path.append("C:/Program Files (x86)/Wysilab/InstantTerra")
from wysilab.instant_terra_application import InstantTerraApplication
def application_closed():
import ctypes
ctypes.windll.user32.MessageBoxW(0, "Application closed", "Python script called from Instant Terra", 0)
def before_project_loaded(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to load the following project: " + path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_project_loaded(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "The following project has been loaded: " + path, "Python script called from Instant Terra", 0)
def before_project_saved(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to save the following project: " + path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_project_saved(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "The following project has been saved: " + path, "Python script called from Instant Terra", 0)
def before_painted_mask_loaded(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to load the following painted mask: " + path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_painted_mask_loaded(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "The following painted mask has been loaded: " + path, "Python script called from Instant Terra", 0)
def before_painted_mask_saved(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to save the following painted mask: " + path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_painted_mask_saved(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "The following painted mask has been saved: " + path, "Python script called from Instant Terra", 0)
def before_image_file_imported(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to import the following image file : "+ path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_image_file_imported(path):
import ctypes
ctypes.windll.user32.MessageBoxW(0, "The following image file has been imported: " + path, "Python script called from Instant Terra", 0)
def before_mesh_file_imported(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to import the following mesh file : "+ path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_mesh_file_imported(path):
import ctypes
ctypes.windll.user32.MessageBoxW(0, "The following mesh file has been imported: " + path, "Python script called from Instant Terra", 0)
def before_image_file_exported(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to export the following image file : "+ path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_image_file_exported(path):
import ctypes
ctypes.windll.user32.MessageBoxW(0, "The following image file has been exported: " + path, "Python script called from Instant Terra", 0)
def before_mesh_file_exported(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to export the following mesh file : "+ path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_mesh_file_exported(path):
import ctypes
ctypes.windll.user32.MessageBoxW(0, "The following mesh file has been exported: " + path, "Python script called from Instant Terra", 0)
def before_component_library_imported(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to import the following component library file: " + path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_component_library_imported(path):
import ctypes
ctypes.windll.user32.MessageBoxW(0, "The following component library file has been imported: " + path, "Python script called from Instant Terra", 0)
def before_component_library_exported(path):
import ctypes
result = ctypes.windll.user32.MessageBoxW(0, "Do you want to export the following component library file: " + path + "?", "Python script called from Instant Terra", 4)
if result == 7:
return "The user has canceled the action"
def after_component_library_exported(path):
import ctypes
ctypes.windll.user32.MessageBoxW(0, "The following component library file has been exported: " + path, "Python script called from Instant Terra", 0)
# Application
InstantTerraApplication.callback_application_closed = "application_closed"
# Project
InstantTerraApplication.callback_before_project_loaded = "before_project_loaded"
InstantTerraApplication.callback_after_project_loaded = "after_project_loaded"
InstantTerraApplication.callback_before_project_saved = "before_project_saved"
InstantTerraApplication.callback_after_project_saved = "after_project_saved"
# Painted mask
InstantTerraApplication.callback_before_painted_mask_loaded = "before_painted_mask_loaded"
InstantTerraApplication.callback_after_painted_mask_loaded = "after_painted_mask_loaded"
InstantTerraApplication.callback_before_painted_mask_saved = "before_painted_mask_saved"
InstantTerraApplication.callback_after_painted_mask_saved = "after_painted_mask_saved"
InstantTerraApplication.callback_before_painted_mask_deleted = "before_painted_mask_deleted"
InstantTerraApplication.callback_after_painted_mask_deleted = "after_painted_mask_deleted"
# Image import
InstantTerraApplication.callback_before_image_file_imported = "before_image_file_imported"
InstantTerraApplication.callback_after_image_file_imported = "after_image_file_imported"
InstantTerraApplication.callback_before_mesh_file_imported = "before_mesh_file_imported"
InstantTerraApplication.callback_after_mesh_file_imported = "after_mesh_file_imported"
# Image export
InstantTerraApplication.callback_before_image_file_exported = "before_image_file_exported"
InstantTerraApplication.callback_after_image_file_exported = "after_image_file_exported"
InstantTerraApplication.callback_before_mesh_file_exported = "before_mesh_file_exported"
InstantTerraApplication.callback_after_mesh_file_exported = "after_mesh_file_exported"
# Component import
InstantTerraApplication.callback_before_component_library_imported = "before_component_library_imported"
InstantTerraApplication.callback_after_component_library_imported = "after_component_library_imported"
# Component export
InstantTerraApplication.callback_before_component_library_exported = "before_component_library_exported"
InstantTerraApplication.callback_after_component_library_exported = "after_component_library_exported"
ctypes.windll.user32.MessageBoxW(0, "Application started", "Python script called from Instant Terra", 0)