Porting Scripts from Older SDK Versions

Updating to a new version of the Maptek Python SDK can break existing scripts. This might be due to functionality being deprecated, or behaviour being changed due to it being unsafe or incorrect. This section describes changes that you might need to make to your scripts to ensure they work correctly with a specific new version of the Maptek Python SDK.

Updating to Maptek Python SDK 1.5

A major change in mapteksdk 1.5 is that it handles properties with one value per primitive more consistently. Because these properties were previously handled inconsistently, this required breaking backwards compatibility in certain cases. By behaving more consistently, the SDK should be easier to use because there are less exceptions to the general rules to keep in mind. The major backwards incompatible changes are listed below:

• NumericColourMap requires the ranges to be specified before the colours.

  • If interpolated is True, then the ranges and colours arrays must have the same length.

  • If interpolated is False, then the colours array must contain one less item than the ranges array.

• StringColourMap requires the legend to be specified before the colours.

• Removes the strange trimming / padding behaviour from NumericColourMap.

• More consistent behaviour of primitive properties:

  • Assigning a single value to the property now consistently will set every value in the property to that value.

    For example, point_set.point_visibility = True now sets every point to visible. This works for every property with one value per primitive.

  • Attempting to replace a per-primitive property array on a read-only object now consistently raises a ReadOnlyError.

  • Attempting to change an element in a per-primitive property array now consistently raises a ValueError.

  • Assigning an array with too many or too few values to a per-primitive property array now consistently raises a ValueError instead of trying to trim or pad the array to the correct length.

  • Assigning None to a per-primitive property array now consistently clears the cached values, resetting them to the values currently saved in the application.

• Accessing a closed object now raises an ObjectClosedError instead of a ValueError.

• Removed support for assigning one dimensional arrays to colour properties as a shorthand for assigning greyscale colours.

Updating to Maptek Python SDK 1.4

Export no longer returns a value

In mapteksdk 1.4 the following functions were changed to not return a value:

• export_00t

• export_bmf

• export_maptekobj

Prior to mapteksdk 1.4 these functions:

• Return True on success.

• Raise an error on failure.

• They could never return False.

Following mapteksdk 1.4 these functions:

• Never return a value.

• Raise an error on failure.

I.e. There was no code path where these functions returned False. This made checking the return value redundant:

if export_00t(surface.id, file_path):
  print("Success")
else:
  # This branch was unreachable.
  print("Failure")

This code should be updated to:

try:
  export_00t(surface.id, file_path)
  print("Success")
except RuntimeError:
  print("Failure")

Which will work in all versions of the SDK.

The try except block is not needed if the script cannot recover from the export failing.

Block model creation

The arguments used to construct DenseBlockModel and SubblockedBlockModel have been renamed:

These original arguments can be misleading because the “x”, “y” and “z” in the names refer to the block model coordinate system and not the “x”, “y” and “z” in the application’s coordinate system.

• Existing scripts will continue to work without changing the parameters, however they will throw a DeprecationWarning exception.

• The old versions of the arguments will be removed in a future version of the SDK.

• New scripts should always use the new arguments.

e.g. The following code:

with project.new(path, DenseBlockModel(
    x_res=col_res, y_res=row_res, z_res=slice_res,
    x_count=col_count, y_count=row_count, z_count=slice_count,
    )) as blocks:
  pass

Should be updated to:

with project.new(path, DenseBlockModel(
    col_res=col_res, row_res=row_res, slice_res=slice_res,
    col_count=col_count, row_count=row_count, slice_count=slice_count,
    )) as blocks:
  pass

(And the same for SubblockedBlockModel.)

Distance units

In mapteksdk 1.4, the elements in the DistanceUnit enum were updated from lowercase to UPPERCASE. This brings them in line with other enums in the Python SDK.

• Scripts that use common distance units (such as metre and feet) will continue to function in version 1.4, however they will emit a deprecation warning and will stop working in a future version of the SDK. They should be updated to use the UPPERCASE version.

• Changing to use the UPPERCASE version of the enum elements is safe and will not functionally change the script.

• New scripts should always use the UPPERCASE version of the enum elements.

E.g. The following code:

oid = import_00t(path, DistanceUnit.metre)

Should be updated to:

oid = import_00t(path, DistanceUnit.METRE)

(And the same for all other DistanceUnit elements in lowercase.)

Primitive removal

In mapteksdk 1.4, the update_immediately argument of the following functions was removed:

• PointSet.remove_points()

• Polyline.remove_points()

• Polygon.remove_points()

• EdgeNetwork.remove_points()

• Surface.remove_points()

• EdgeNetwork.remove_edges()

• Surface.remove_facets()

This parameter was misleading.

• Setting update_immediately=True did not cause the update to occur immediately.

• Setting update_immediately=False would place the object in an inconsistent state, which could cause the script (and potentially the connected application) to crash.

To update usage of these functions, simply delete the update_immediately parameter.

E.g. The following code:

surface.remove_points([0, 1, 2], update_immediately=True)

Should be updated to:

surface.remove_points([0, 1, 2])

(And the same for other primitive removal functions listed above.)