mapteksdk.data.io module

Functions for importing and exporting data.

exception ImportMissingInputError

Bases: Exception

One or more inputs required to import the file are missing.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

import_any(path, unit=None, coordinate_system=<mapteksdk.data.io._Unspecified object>)

Import any format supported by the application’s import framework.

Unlike other import functions, the inputs aside from path may be ignored if the import of the file at path does not require that input.

Parameters:

• path (str | pathlib.Path) – Path to the file to import.

• unit (DistanceUnit | None) – The unit to use for the import. If None (default), this indicates that the import of this format does not require a unit (e.g. The file always stores the values in metres or the file contains non-spatial data which units do not apply to, such as colour maps).

• coordinate_system (CoordinateSystem | _Unspecified | None) – The coordinate system to use for the import. This should be set to None to provide “no coordinate system”. This is unspecified by default, which indicates that the import of this file format does not require a coordinate system (e.g. The coordinate system is stored within the file or the file contains non-spatial data which coordinate systems do not apply to, such as colour maps).

Returns:

Sequence of ImportedObject named tuples with one item per imported object.

Return type:

Sequence[ImportedObject]

Raises:

• FileNotFoundError – If the file at path does not exist.

• ImportMissingInputError – If the import of the file at path requires an input which has not been supplied. Note that this will be raised in cases where the import requires an additional input which cannot be provided through this function.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

Notes

This delegates the import of common image formats to the pillow library instead of using the application’s importer for image formats.

import_00t(path, unit=DistanceUnit.METRE)

Import a Maptek Vulcan Triangulation file (00t) into the project.

Parameters:

• path (str | Path) – Path to file to import.

• unit (DistanceUnit) – The unit used when exporting the file.

Returns:

The ID of the imported object.

Return type:

ObjectID

Raises:

• FileNotFoundError – If the file does not exist.

• TypeError – If path cannot be converted to a pathlib.Path. If the unit is not an instance of DistanceUnit.

• RuntimeError – If there is a problem importing the file.

Notes

The imported object is not automatically placed inside a container. A call to project.add_object() is required to add it to a container.

export_00t(object_id, path, unit=DistanceUnit.METRE)

Export a Surface to a Vulcan Triangulation (00t).

Parameters:

• object_id (ObjectID[Surface]) – The ID of the surface to export.

• path (str | Path) – Where to save the 00t.

• unit (DistanceUnit) – Unit to use when exporting the file.

Raises:

• TypeError – If the unit is not a DistanceUnit.

• RuntimeError – If there was a problem exporting the file.

Notes

Changed in version 1.4 - This function no longer returns a value. Prior to 1.4, this would return True on success and raise an exception on failure (It could never return False).

import_bmf(path, unit=DistanceUnit.METRE)

Import a Maptek Block Model File (bmf) into the project.

Parameters:

• path (str | pathlib.Path) – Path to file to import.

• unit (DistanceUnit) – Unit to use when importing the file.

Returns:

The ID of the imported object.

Return type:

ObjectID

Raises:

• TypeError – If path could not be converted to a pathlib.Path. If the unit is not an instance of DistanceUnit.

• FileNotFoundError – If the file does not exist.

• RuntimeError – If there is a problem importing the file.

Notes

The ObjectID returned by this function is type hinted as ObjectID[BlockProperties, DataObject] because all supported block models are expected to inherit from BlockProperties and DataObject. This means autocompletion should only suggest properties which are shared by all block models. The type hint may be incorrect if the bmf contains a block model not supported by the SDK.

export_bmf(object_id, path, unit=DistanceUnit.METRE)

Export a block model to a Maptek Block Model File (bmf).

Parameters:

• object_id (ObjectID[BlockProperties | DataObject]) – The ID of the block model to export as a bmf.

• path (str | Path) – Where to save the bmf file.

• unit (DistanceUnit) – Unit to use when exporting the file.

Returns:

True if the export was a success. This never returns false - if the import fails an exception will be raised.

Return type:

bool

Raises:

• TypeError – If unit is not a DistanceUnit.

• RuntimeError – If there was a problem exporting the file.

Notes

Changed in version 1.4 - This function no longer returns a value. Prior to 1.4, this would return True on success and raise an exception on failure (It could never return False).

import_bdf(path, unit=DistanceUnit.METRE)

Import a block model definition from a bdf file.

Parameters:

• path (PathLike | str) – The path to the bdf file to import.

• unit (DistanceUnit)

Returns:

• ObjectID[BlockModelDefinition] – Object ID of the imported block model definition. This will not be placed in the project. Use Project.add_object() to set its path in the project.

• unit – The unit to read the imported bdf in. This is metres by default.

Raises:

• FileNotFoundError – If the file does not exist or is a directory.

• FileCorruptError – If the file is not a bdf file or the file is corrupt.

• RuntimeError – If an unknown error occurs.

Return type:

ObjectID[BlockModelDefinition]

export_bdf(oid, path, unit=DistanceUnit.METRE)

Export a block model definition into a bdf file.

Parameters:

• oid (ObjectID[BlockModelDefinition]) – Object ID of the block model definition to export.

• path (PathLike | str) – Path to the file to export the block model definition to.

• unit (DistanceUnit) – Unit to export the BDF in. This is metres by default.

Raises:

• TypeError – If oid is not a block model definition object.

• RuntimeError – If an unknown error occurs.

• ValueError – If unit is not supported by the connected application.

import_maptekobj(path)

Import a Maptek Object file (maptekobj) into the project.

Parameters:

path (str | Path) – Path to file to import.

Returns:

The ID of the imported object.

Return type:

ObjectID

Raises:

• FileNotFoundError – If the file does not exist.

• RuntimeError – If there is a problem importing the file.

• TypeError – If path cannot be converted to a pathlib.Path object.

export_maptekobj(object_id, path)

Export an object to a Maptek Object file (maptekobj).

Unlike 00t and bmf any object (even containers) can be exported to a maptekobj file.

Parameters:

• object_id (ObjectID[DataObject]) – The ID of the object to export.

• path (str | Path) – Where to save the maptekobj file.

Returns:

True if the export was a success. This never returns false - if the import fails an exception will be raised.

Return type:

bool

Raises:

RuntimeError – If there was a problem exporting the file.

Notes

Changed in version 1.4 - This function no longer returns a value. Prior to 1.4, this would return True on success and raise an exception on failure (It could never return False).

import_hgt(path)

Import a HGT file.

This format was used by NASA’s Shuttle Radar Topography Mission.

Parameters:

path (str | PathLike) – The path to the HGT file to read.

Returns:

The grid surface imported from the hgt file.

Return type:

ImportedObject

Raises:

• ValueError – If path does not have the .hgt extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_kml(path)

Import a KML file.

KML stands for Keyhole Markup Language.

Parameters:

path (str | PathLike) – The path to the KML file to read.

Returns:

A container containing all of the imported objects.

Return type:

ImportedObject

Raises:

• ValueError – If path does not have the .kml extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_obj(path, *, coordinate_system=None, unit=DistanceUnit.METRE)

Import from an .obj file.

This file type is used to exchange 3D models intended for visualization, 3D printing, and extended reality applications. The data consists of sets of adjacent triangles that together define a tessellated geometric surface.

More details can be found on the US Library of Congress Reference page for the format here: https://www.loc.gov/preservation/digital/formats/fdd/fdd000507.shtml

Parameters:

• path (str | os.PathLike) – The path to the .obj file to read.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

• unit (DistanceUnit) – The unit the file is stored in. This is metres by default.

Returns:

A container containing the imported objects.

Return type:

Sequence[ImportedObject]

Raises:

• ValueError – If path does not have the .obj extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_shp(path, coordinate_system=None)

Import an ESRI shapefile.

A shapefile stores non-topological geometry and attribute information for the spatial features in a data set.

All shapes within the file will be merged into a single object.

For more details, see the ESRI documentation for the format: https://www.esri.com/content/dam/esrisites/sitecore-archive/Files/Pdfs/library/whitepapers/pdfs/shapefile.pdf

Parameters:

• path (str | PathLike) – The path to the .shp file to read.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

Returns:

The imported object. All shapes in the shapefile will be merged into a single object.

Return type:

ImportedObject

Raises:

• ValueError – If path does not have the .shp extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_ply(path)

Import a Stanford University PLY file.

PLY files are designed to provide a format that is simple and easy to implement but general enough to be useful for a wide range of models.

This will import the basic geometry defined in the importer, but because the format is too general any other information in the file may not be imported.

Parameters:

path (str | os.PathLike) – The path to the file to import.

Returns:

The imported object. Depending on how the geometry is defined in the file, this will either be a Surface, Scan or a PointSet.

Return type:

ImportedObject

Raises:

• ValueError – If path does not have the .ply extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_3dv(path, *, coordinate_system=None)

Import a 3dv file.

This imports files in the Optech gridded ASCII scan format

Parameters:

• path (str | PathLike) – The path to the file to import.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

Returns:

The imported scan.

Return type:

ImportedObject

Raises:

• NoScanDataError – If the scan file contains no scan data (e.g. It is image-only).

• ValueError – If path does not have the .3dv extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_3dp(path)

Imports a Maptek 3dp file.

The scan format used by Maptek’s 4400 series of scanners. Any scan in PointStudio can be exported as a 3dp which means 3dp files may not come from scanners.

Parameters:

path (str | PathLike) – The path to the file to import.

Returns:

The imported scan.

Return type:

ImportedObject

Raises:

• NoScanDataError – If the scan file contains no scan data (e.g. It is image-only).

• ValueError – If path does not have the .3dp extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_r3s(path)

Imports a Maptek r3s file.

This is the scan format used by Maptek Gen 3 Scanners. Scans cannot be exported in this format, so they always come from a scanner.

Parameters:

path (str | PathLike) – The path to the file to import.

Returns:

The imported scan.

Return type:

ImportedObject

Raises:

• NoScanDataError – If the scan file contains no scan data (e.g. It is image-only).

• ValueError – If path does not have the .r3s extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_3dr(path, *, coordinate_system=None)

Import a 3dr file.

This is the scan format used by Maptek’s 8000 series scanners. Scans cannot be exported in this format, so they always come from a scanner.

Parameters:

• path (str | PathLike) – The path to the file to import.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

Returns:

The imported scan.

Return type:

ImportedObject

Raises:

• NoScanDataError – If the scan file contains no scan data (e.g. It is image-only).

• ValueError – If path does not have the .3dr extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_3di(path, *, coordinate_system=None, unit=DistanceUnit.METRE)

Import a 3di file.

One of Maptek’s proprietary scan formats. This is a legacy format.

Parameters:

• path (str | PathLike) – The path to the file to import.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

• unit (DistanceUnit) – The unit the file is stored in. This is metres by default.

Returns:

The imported scan.

Return type:

ImportedObject

Raises:

• NoScanDataError – If the scan file contains no scan data (e.g. It is image-only).

• ValueError – If path does not have the .3di extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_las_scan(path, *, coordinate_system=None, unit=DistanceUnit.METRE)

Import a las scan.

This is an open, binary format specified by the American Society for Photogrammetry and Remote Sending.

More details can be found on the US Library of Congress Reference page for the format here: https://www.loc.gov/preservation/digital/formats/fdd/fdd000418.shtml

Parameters:

• path (str | PathLike) – The path to the file to import. This can be a las or a laz file.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

• unit (DistanceUnit) – The unit the file is stored in. This is metres by default. Some las scan files include information about the units within the file. If this information is found, the unit supplied to this parameter will be ignored.

Returns:

The imported scan.

Return type:

ImportedObject

Raises:

• NoScanDataError – If the scan file contains no scan data (e.g. It is image-only).

• ValueError – If path does not have the .las or .laz extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_autocad_drawing_file(path, *, coordinate_system=None, unit=DistanceUnit.METRE)

Import an Autodesk AutoCAD drawing file (.dwg).

These files store 2 or 3 dimensional design data. They can store multiple objects of different types in one file.

Parameters:

• path (str | os.PathLike) – The path to the file to import.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

• unit (DistanceUnit) – The unit the file is stored in. This is metres by default.

Returns:

A sequence containing the imported objects. This can include PointSet, Polyline, Polygon, EdgeNetwork, Surface or Text3D. The sequence may contain objects of different types.

Return type:

Sequence[ImportedObject]

Raises:

• ValueError – If path does not have the .dwg extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_autocad_exchange_file(path, *, coordinate_system=None, unit=DistanceUnit.METRE)

Import an Autodesk AutoCAD exchange file (.dxf or .dxb).

These files store 2 or 3 dimensional design data. They can store multiple objects of different types in one file.

Parameters:

• path (str | os.PathLike) – The path to the file to import.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

• unit (DistanceUnit) – The unit the file is stored in. This is metres by default.

Returns:

A sequence containing the imported objects. This can include PointSet, Polyline, Polygon, EdgeNetwork, Surface or Text3D. The sequence may contain objects of different types.

Return type:

Sequence[ImportedObject]

Raises:

• ValueError – If the extension of path is not .dxf or .dxb.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_ecw(path)

Imports a ecw file.

Import an ECW (Enhanced Compression Wavelet) file developed by Hexagon Geospatial as a rastered surface. This format is typically used for aerial photography and satellite imagery.

Parameters:

path (str | PathLike) – The path to the file to import.

Returns:

The imported surface. This will always have a raster applied containing the image read from the ecw file.

Return type:

ImportedObject

Raises:

• ValueError – If path does not have the .ecw extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_jp2(path)

Imports a jp2 file.

Import a JPEG 2000 (Joint Photographic Experts Group) image file as a rastered surface.

JPEG 2000 was designed as an improved version of the widely used JPEG image format (.jpg or .jpeg) however the ubiquity of the original JPEG format means jp2 is not widely supported.

Parameters:

path (str | PathLike) – The path to the file to import.

Returns:

The imported surface. This will always have a raster applied containing the image read from the jp2 file.

Return type:

ImportedObject

Raises:

• ValueError – If path does not have the .jp2 extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

Notes

These files can also be imported via the pillow library.

import_scd(path)

Imports a Vulcan scd file.

This format is used by Maptek Vulcan to store colour maps.

Parameters:

path (str | os.PathLike) – The path to the file to import.

Returns:

A sequence containing the object IDs of the imported colour maps.

Return type:

Sequence[ImportedObject]

Raises:

• ValueError – If path does not have the .scd extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_arch_d(path, *, coordinate_system=None, unit=DistanceUnit.METRE)

Import an arch_d file.

Import data from an Envisage archive file used by Maptek Vulcan.

Parameters:

• path (str | os.PathLike) – The path to the file to import.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

• unit (DistanceUnit) – The unit the file is stored in. This is metres by default.

Returns:

Sequence of imported objects. Each is a container representing a layer imported from the file.

Return type:

Sequence[ImportedObject]

Raises:

• ValueError – If path does not have the .arch_d extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_dgd_isis(path, *, coordinate_system=None, unit=DistanceUnit.METRE)

Import a dgd.isis file.

Import data from a Vulcan design database file. Currently, all supported objects from all layers are imported.

Parameters:

• path (str | os.PathLike) – The path to the file to import.

• coordinate_system (CoordinateSystem | None) – The coordinate system which the imported objects are in. Setting this parameter does not trigger a coordinate system conversion. This is no coordinate system by default.

• unit (DistanceUnit) – The unit the file is stored in. This is metres by default.

Returns:

A sequence of ObjectID`s of `VisualContainer objects. There is one container per layer in the design database.

Return type:

Sequence[ImportedObject]

Raises:

• ValueError – If path does not have the .dgd.isis extension.

• FileNotFoundError – If there is no file at path.

• FileImportError – If there was an error importing path. The error message is often (but not always) provided by the application so may be translated into the user’s selected language.

• ImportFormatNotSupportedError – If the connected application does not support importing this format.

Warns:

FileImportWarning – If one or more objects could not be imported correctly.

import_image(path)

Import a raster from an image file.

Unlike the other import functions in this package, this uses the Pillow package instead of the application’s importer.

Parameters:

path (str | PathLike) – The path to the file to import.

Returns:

The imported raster.

Return type:

ImportedObject

Raises:

• ValueError – If path is not to a supported image file.

• FileNotFoundError – If there is no file at path.

import_image_with_world_file(image_path, world_file_path=None)

Import an image file with an associated world file.

The image will be applied as a raster to a rectangular surface at a location defined by the world file.

Parameters:

• image_path (str | PathLike) – Path to the image file to import. This must be a jpg, png, bmp, tif or tiff file.

• world_file_path (str | PathLike | None) – Path to the world file to import. If None, this function will search for a world file with the same name as the image file. To import using an image with the .wld extension, you must explicitly set the world_file_path parameters.

Returns:

The surface imported based on the world file with a raster based on the image file applied.

Return type:

ImportedObject

Raises:

• FileNotFoundError – If the image or world file cannot be found.

• CorruptFileError – If the world file is corrupt.

Notes

The following table outlines the expected extensions for world files based on the associated image file:

Image format	World file format
jpg / jpeg	jpw
png	pgw
bmp	bpw
tif / tiff	tfw
any	wld