Leveling a ZMap

Sometimes, the reference plane of the ZMap is not set right.

To solve this problem, use the method Level of the class EZMapLeveler to reproject the ZMap on a new reference plane.

● To specify the new reference plane, you can either:
□ Give an ERegion of points contained in the plane to the method Level.
► The plane might be shifted so that the leveled ZMap contains all the points of the original one.

An ERegion (composed of 2 ERectangle regions) highlighting the new reference plane

□ Give the normal of the new plane to the ZMap (with argument projectionDirection).
► The ZMap plane is computed from the normal and shifted so that the new ZMap contains all the points of the old one.

A typical way to find the projectionDirection is to use an EPlaneFinder to find the biggest plane in the ZMap.

2 See code snippet: Performing ZMap Leveling.
● To set the angle of the X and Y axes of the leveled ZMap, use the argument rotationAngle.

Illustration of the EZMapLeveler with the default (left) and correct (right) value of the rotationAngle

 

Size and XYZ resolution settings

There are several options to handle the size and X, Y or Z resolution of the leveled ZMap:

● PreservationModes determines whether the XY resolution, size and/or Z resolution of the input ZMap are preserved.
□ When the XY resolution is preserved, the size of the leveled ZMap is adjusted.
□ When the size of the ZMap is preserved, the resolution is adjusted.

Note that this may introduce holes in the leveled ZMap.

□ When both are preserved, the visible contents of the ZMap are adjusted, meaning that some undefined pixels may appear on the edges of the ZMap or the extremities of the object may be cropped.
□ When the Z resolution is preserved, some data may be impossible to represent if the Z range of the leveled ZMap is bigger than the one of the source ZMap (see next point). Otherwise, the Z resolution is recomputed to use the whole range of the ZMap.
□ To avoid undesired side-effects, only the XY resolution is preserved by default.
● Use PreserveZResolutionFailureHandler to choose how to handle data falling outside of the representable range of the ZMap when EZMapLeveler.PreservationModes is set to EPreservationMode.ZResolution. The data may be cropped (the corresponding pixel is undefined), Saturated (the corresponding pixel is white) or an exception is thrown when the problem occurs.

3D position settings

● By default, the leveling does not change the underlying 3D data of the ZMap. The goal is to use the leveling to ease some 2D processing while maintaining the link with the real-world positions of the data.
● Alternatively, you can use the method Preserve3DPosition to alter that behavior and modify the 3D data of the leveled ZMap.

In this mode, the z = 0 plane is either:

□ The plane defined by the ERegion when the method Level takes a region as argument.
□ The plane used for the leveling when the method Level takes a projection direction as argument.