Module functions

Module: digi3d

Functions available directly in the digi3d module.

current_view

current_view() -> DrawingView

Returns the active DrawingView, or None if there is none. This is the usual entry point for a script. If the active window is the photogrammetric window, it returns the open drawing window.

Opening a drawing

open_drawing(path, code_table=None, scale=None, register_increment=None, equidistance=None,
             text_height=None, tolerance=None, z_correction=None, sigma=None, crs_wkt=None,
             references=None) -> DrawingView

Opens a drawing file in a new drawing window and returns its DrawingView. Does the same as the open drawing dialog, without displaying it. If the file does not exist, the format creates it.

Digi3D.AI opens only one drawing at a time: if one is already open, the function raises RuntimeError. Close the open drawing with DrawingView.close() before opening another drawing.

Argument Type Description
path str Drawing file path. The folder must exist.
code_table str Code table path. The file must exist.
scale float Pattern display scale.
register_increment float Registration increment.
equidistance float Contour interval.
text_height float Text height.
tolerance float Generalization tolerance.
z_correction float Z correction.
sigma float Sigma.
crs_wkt str Drawing window coordinate system, in WKT.
references list[str] Reference files to load. If references is omitted, the reference files saved with the drawing are loaded. A file that was not saved is saved with the drawing, just as when you load that file. With Store the reference files in a .reference_files.json file disabled, Digi3D.AI neither reads nor saves references in the reference files file.

Omitted arguments take the last values used in the open drawing dialog. Supplied arguments become the last used values, just as with the dialog; if the drawing cannot be opened, Digi3D.AI restores the previous values. Format options are the last ones used with that format.

Opening without dialogs

open_drawing, open_project, load_model, and open_photogrammetric_file do not display any dialogs, so a script or MCP client does not wait for the user to respond. When Digi3D.AI would ask the user a question, the function takes the response shown in the table and writes a notification starting with Warning: to the script output:

Situation Response
A reference file does not exist. It is not loaded; the rest of the drawing opens.
The code table cannot be loaded. The drawing does not open.
A transformation between two coordinate systems must be selected and none is saved. The file is not loaded. Open it once from Digi3D.AI to select the transformation; the saved one is used afterward.
Several formats can read the file. The file is not loaded.
The file has no coordinate system. The result is the same as canceling the coordinate system selection dialog.
The file layers or tables must be selected. The file is not loaded.
The photogrammetric project has no coordinate system. It is loaded with a local system, without creating the .prj file.
The drawing opened by open_drawing has an associated photogrammetric project or photogrammetric model file. The project is not loaded and the model is not opened.
Any other message with buttons. The function chooses No, cancel, or abort, depending on the message buttons.

If open_drawing fails, the exception message includes the warnings. Startup commands run by the code table and the drawing when the window opens also receive the responses in the table.

Some dialogs cannot yet be avoided and still wait for the user: the license notification, the coordinate system prompt for a conical camera model whose aerial triangulation has none, and the coordinate system selection for a GeoPackage with several systems.

import digi3d

view = digi3d.current_view()
if view is not None:
    view.close()
view = digi3d.open_drawing(r"C:\Proyectos\hoja2.bin", code_table=r"C:\Proyectos\tabla.tab")

Photogrammetric window and projects

photogrammetric_view

photogrammetric_view() -> PhotogrammetricView | None

Returns the active photogrammetric window, or None if there is none.

open_photogrammetric_file

open_photogrammetric_file(path) -> PhotogrammetricView

Opens a photogrammetric model file (.d3d) in a new photogrammetric window and returns it. Raises ValueError if the file is not .d3d, and RuntimeError if Digi3D.AI cannot open it.

With Store the photogrammetric project or the photogrammetric model as a reference file enabled, if a drawing window is open and the Photogrammetric project pane has no project loaded, open_photogrammetric_file saves the model file path in the reference files file of the drawing file belonging to the last drawing window that had focus, unless that drawing file is read-only.

open_project

open_project(path, images_url=None) -> bool

Loads a photogrammetric project in the project pane, like the pane Load button, without displaying any dialogs. Returns False if the project was not loaded; the reason appears as a notification starting with Warning: in the script output. If the project has no coordinate system, the function loads it with a local system, without creating the .prj file, as shown in the Opening without dialogs table.

Parameter Type Description
path str Path of the project file, or http or https URL of a project published in Azure Blob Storage or on a server that answers byte-range requests (the Range header), with or without the shared access signature (SAS) query.
images_url str or None URL of the folder of the project images, with its own SAS if it needs one. None or an empty string means the images are in the project folder.

images_url is valid only if path is an http or https URL; if it is not and images_url is neither None nor an empty string, the function raises ValueError.

With a URL, the function downloads the project to a local copy. If path has no query, images_url is None or empty and a saved credential of that project exists, Digi3D.AI uses the URLs, queries and published image extension of that credential. If path has a query or images_url contains a URL, Digi3D.AI uses the URLs and queries supplied in those arguments and takes only the published image extension from the saved credential. If there is neither a query nor a credential, it loads the URL without a query. Digi3D.AI saves the queries encrypted in the current Windows user registry, and the pane's progress message omits the query from the project URL. See Publishing a photogrammetric project in Azure Blob Storage and loading it from a URL.

If it loads the project, the function saves its path as the last project in the pane, like the Load button. With a URL, it saves the URL without the query. With Store the photogrammetric project or the photogrammetric model as a reference file enabled, if a drawing window is open and the drawing file of the last drawing window that had focus is not read-only, it also saves the path in the reference files file of that drawing file.

project

project() -> dict | None

Returns the project loaded in the project pane, or None if there is none:

Key Type Description
file str Project file path.
viewpoint str Viewpoint selected in the pane.
viewpoints list[str] Project viewpoints.
models list[dict] For a model project, the models in the selected viewpoint: strip (strip), name (name), and loadable (whether it can be loaded).
photos list[str] For a photo project, the photo names.

load_model

load_model(name, new_window=False) -> bool

Loads a model from the project, like clicking a model in the project pane. In a photo project, the model name is izquierda-derecha, using the names of two different photos.

  • If new_window=False and the active photogrammetric window was opened with neither a point cloud model nor a stereoscopic orthophoto model, the requested model replaces the model in that window and loads in the background after the script finishes. Check model_name in a later script.
  • If no window is open, with new_window=True, or if the active photogrammetric window was opened with a point cloud or stereoscopic orthophoto model, opens a new photogrammetric window before returning control to the script. Point cloud and stereoscopic orthophoto windows do not load another model in the background.

Raises RuntimeError if no project is loaded, and ValueError if the project does not contain that model in the selected viewpoint or the pane shows the model disabled. Returns False if loading could not be started.

With Store the photogrammetric project or the photogrammetric model as a reference file enabled, when the active photogrammetric window finishes loading the model, Digi3D.AI saves the project path and model name in the reference files file of the open drawing file, unless that drawing file is read-only.

import digi3d

if digi3d.open_project(r"C:\Proyectos\vuelo.d3dprj"):
    modelos = digi3d.project()["models"]
    digi3d.load_model(modelos[0]["name"])

# Project published in Azure Blob Storage, with the images in another folder.
digi3d.open_project(
    "https://cuenta.blob.core.windows.net/vuelos/vuelo1/vuelo1.d3dprj?sv=…&sr=c&sp=r&sig=…",
    images_url="https://cuenta.blob.core.windows.net/fotos/vuelo1/?sv=…&sr=c&sp=r&sig=…")

Messages and notifications

Function Description
music(type=MusicType.Beep) Plays one of the standard sounds (MusicType).
print_statusbar(message) Writes a message to the status bar.
show_ballon(title, body, icon=BallonType.Info, time=1000) Displays a temporary information balloon (BallonType).
progress(value=-1) Updates the progress bar (percentage).
ask_question(question) Displays a modal Yes/No dialog.
Returns True or False.
show_info(message) Displays a modal dialog with information for the user.

Results and tasks panes

Function Description
show_results(show=True) Shows or hides the results pane.
clear_results() Clears the results pane.
add_result(message, scroll=True, update=True) Adds a line to the results pane.
get_results() Returns the contents of the results pane (str).
show_tasks(show=True) Shows or hides the tasks pane.
clear_tasks() Clears the tasks pane.
add_task(task) Adds a task to the tasks pane.

File dialog

ask_file(load, filetypes, title=None) -> str | None

Displays an open/save file dialog and returns the selected path, or None if canceled.

Argument Type Description
load bool True to open, False to save.
filetypes list[tuple] List of (descripción, extensión) pairs, e.g. [("AutoCAD DWG", "*.dwg")].
title str Dialog title (optional).

Geometry utilities

Function Returns Description
same_coordinates(a, b) bool Indicates whether two coordinates are identical, taking the active sigma into account. Accepts (x,y,z), (x,y), or a single value.
non_connected(geometries) list Returns unconnected endpoints: a list of (geometría, índice_de_vértice) whose start/end vertex does not share a node with any other.
get_intersections(geometry, geometries) dict Vertices of geometry that coincide with vertices of other geometries: {(x, y): {geometría: índice_de_vértice}}.

Example

import digi3d

view = digi3d.current_view()

digi3d.show_results(True)
digi3d.add_result(f"La ventana tiene {len(view)} geometrías")

if digi3d.ask_question("¿Continuar?"):
    digi3d.music(digi3d.MusicType.End)

See also