Class Surface

Creates a new empty surface.

The surface will not contain any points. This parameterless constructor exists mainly for language bindings, Surface.new_from_data() is usually more useful.

Returns:

A new empty surface. (Surface)

Creates a new empty surface similar to another surface.

The units of the new surface will be identical to those of model but the new surface will not contain any points. Use Surface.duplicate() to completely duplicate a surface including data.

Returns:

A new empty surface. (Surface)

Creates a new surface as a part of another surface.

The new surface consits of data with lateral coordinates within the specified ranges (inclusively). It may be empty.

Data are physically copied, i.e. changing the new surface data does not change surface's data and vice versa.

Parameters:

• xfrom - Minimum x-coordinate value. (float)
• xto - Maximum x-coordinate value. (float)
• yfrom - Minimum y-coordinate value. (float)
• yto - Maximum y-coordinate value. (float)

Returns:

A new surface. (Surface)

Gets the raw XYZ data array of a surface.

The returned buffer is not guaranteed to be valid through whole data surface life time.

This function invalidates any cached information, use Surface.get_data_const() if you are not going to change the data.

See Surface.invalidate() for some discussion.

Returns:

The surface XYZ data as a pointer to an array of Surface.get_npoints() items. (XYZ)

Gets the number of points in an XYZ surface.

Returns:

The number of points. (int)

Emits signal Surface::data-changed on a surface.

Copies the data of a surface to another surface of the same dimensions.

Only the data points are copied. To make a surface completely identical to another, including units and change of dimensions, you can use Surface.clone().

Parameters:

• dest - Destination surface. (Surface)

Invalidates cached surface statistics.

Cached statistics include ranges returned by Surface.get_xrange(), Surface.get_yrange() and Surface.get_min_max(), the fingerprint for Surface.xy_is_compatible() and and possibly other characteristics in the future.

See DataField.invalidate() for discussion of invalidation and examples.

Fills the data of a surface from a data field.

The number of points in the new surface will be equal to the number of points in the field. Lateral coordinates will be equal to the corresponding data_field coordinates; values will be created in regular grid according to data_field's physical size and offset.

Lateral and value units will correspond to data_field's units. This means the field needs to have identical x and y units.

Parameters:

• data_field - A two-dimensional data field. (DataField)

Fills the data of a surface from a data field, possibly using masking.

Parameters:

• data_field - A two-dimensional data field. (DataField)
• mask - Mask of pixels to include from/exclude, or None (DataField)
• masking - Masking mode to use. Expected values: MASK_EXCLUDE, MASK_INCLUDE, MASK_IGNORE. (MaskingType)

Returns lateral SI unit of a surface.

Returns:

SI unit corresponding to the lateral (XY) dimensions of the surface. Its reference count is not incremented. (SIUnit)

Returns value SI unit of a surface.

Returns:

SI unit corresponding to the "height" (Z) dimension of the surface. Its reference count is not incremented. (SIUnit)

Sets the SI unit corresponding to the lateral (XY) dimensions of a surface.

It does not assume a reference on si_unit, instead it adds its own reference.

Parameters:

• si_unit - SI unit to be set. (SIUnit)

Sets the SI unit corresponding to the "height" (Z) dimension of a surface.

It does not assume a reference on si_unit, instead it adds its own reference.

Parameters:

• si_unit - SI unit to be set. (SIUnit)

Finds value format good for displaying coordinates of a surface.

Parameters:

• style - Unit format style. Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, SI_UNIT_FORMAT_VFTEX, SI_UNIT_FORMAT_UNICODE, SI_UNIT_FORMAT_VFUNICODE. (SIUnitFormatStyle)

Returns:

Tuple consisting of 2 values (value, format). ((SIValueFormat), (SkipArg))

Finds value format good for displaying values of a surface.

Parameters:

• style - Unit format style. Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, SI_UNIT_FORMAT_VFTEX, SI_UNIT_FORMAT_UNICODE, SI_UNIT_FORMAT_VFUNICODE. (SIUnitFormatStyle)

Returns:

Tuple consisting of 2 values (value, format). ((SIValueFormat), (SkipArg))

Sets lateral and value units of a surface to match another surface.

Parameters:

• target - Target surface. (Surface)

Sets lateral and value units of a data field to match a surface.

Parameters:

• data_field - A two-dimensional data field. (DataField)

Obtains a single surface point.

This function exists only for language bindings as it is very slow compared to simply accessing data in Surface directly in C.

Parameters:

• pos - Position in surface. (int)

Returns:

The point at pos. (XYZ)

Gets the range of X coordinates of a surface.

This information is cached.

Returns:

Tuple consisting of 2 values (min, max). ((float), (float))

Gets the range of Y coordinates of a surface.

This information is cached.

Returns:

Tuple consisting of 2 values (min, max). ((float), (float))

Gets the range of Z values of a surface.

This information is cached.

Returns:

Tuple consisting of 2 values (min, max). ((float), (float))

Puts back values from a flat array to an entire data surface.

If you do not have an array of XYZ and want to fill the data sequentially, use Surface.resize() and Surface.get_data().

See Surface.get_data_full() for a discussion.

Parameters:

• points - Data points to copy to the surface. They replace whatever points are in surface now. (const-XYZ*)
• n - The number of points in data. (int)

Checks whether the XY positions of two surfaces are compatible.

Compatible XY positions mean the XY units are the same and the points are the same. Two surfaces that have the same set of XY points but in different orders are not considered compatible. This is because the points at the same index in data are different and thus calculations involving data from the two surfaces are impossible. It is necessary to match the points order in the two surfaces to make this possible.

This information is cached.

Parameters:

• othersurface - Another surface. (Surface)

Returns:

True if the surfaces are XY-position compatible, False if they are not. (bool)

Creates a similar surface with smaller number of points.

The functions attempts to choose points from the original surface to cover its full area, even though points from dense regions are still more likely to be found in the result than points from sparse regions. As the main purpose to enable quick rough operations that may take long time with the full surface, the focus is on speed not fidelity.

The function may employ random selection and thus be be non-deterministic.

Parameters:

• npoints - Requested number of points in the reduced surface. If it is not smaller than the number of points in surface then the function behaves like Surface.duplicate(). (int)

Returns:

A newly created Surface with reduced number of points. (Surface)

Changes the number of points in a surface.

If the number of points decreases then the first npoints points will be kept. If the number of points increases the new points will be uninitialised. Although usually you would overwrite all the points after using this function.

Use Surface.set_data_full() if you already have an array of XYZ to fill the surface data with.

Parameters:

• npoints - New number of points in the surface. (int)

Sets a single surface value.

This function exists only for language bindings as it is very slow compared to simply accessing data in Surface directly in C.

Parameters:

• pos - Position in surface. (int)
• point - Point to store at given position. (const-XYZ*)

Duplicates a surface.

This is a convenience wrapper of gwy_serializable_duplicate().

Returns:

(Surface)