- Qt 6.12
- Qt Graphs
- QML Types
- QtGraphs
- Surface3DSeries
- Qt Graphs | Commercial or GPLv3

# Surface3DSeries QML Type (Uncreatable)

Represents a data series in a 3D surface graph. More...

Import Statement: | `import QtGraphs`
In C++: | QSurface3DSeries
Inherits: | Abstract3DSeries

Note: This is an uncreatable type. It cannot be instantiated in QML.

- List of all members, including inherited members
- Surface3DSeries is part of Qt Graphs QML Types for 3D.

## Properties

- baseColor : color
- baseGradient : Gradient
- colorStyle : GraphsTheme.ColorStyle
- dataArray : SurfaceDataArray
- dataProxy : SurfaceDataProxy
- drawMode : DrawFlag
- flatShadingSupported : bool
- invalidSelectionPosition : point
- itemLabel : string
- itemLabelFormat : string
- itemLabelVisible : bool
- lightingMode : Abstract3DSeries.LightingMode `(since 6.10)`
- mesh : Abstract3DSeries.Mesh
- meshRotation : quaternion
- meshSmooth : bool
- multiHighlightColor : color
- multiHighlightGradient : Gradient
- name : string
- selectedPoint : point
- shading : Shading
- singleHighlightColor : color
- singleHighlightGradient : Gradient
- textureFile : string
- type : Abstract3DSeries.SeriesType
- userDefinedMesh : string
- visible : bool
- wireframeColor : color

## Signals

- baseColorChanged(color color)
- baseGradientChanged(Gradient gradient)
- colorStyleChanged(GraphsTheme.ColorStyle style)
- dataArrayChanged(SurfaceDataArray array)
- dataProxyChanged(SurfaceDataProxy proxy)
- drawModeChanged(DrawFlag mode)
- flatShadingSupportedChanged(bool enable)
- itemLabelChanged(string label)
- itemLabelFormatChanged(string format)
- itemLabelVisibilityChanged(bool visible)
- lightingModeChanged(Abstract3DSeries.LightingMode lightingMode) `(since 6.10)`
- meshChanged(Abstract3DSeries.Mesh mesh)
- meshRotationChanged(quaternion rotation)
- meshSmoothChanged(bool enabled)
- multiHighlightColorChanged(color color)
- multiHighlightGradientChanged(Gradient gradient)
- nameChanged(string name)
- rowsSanitizedChanged(bool enabled)
- selectedPointChanged(point position)
- shadingChanged(const Shading shading)
- singleHighlightColorChanged(color color)
- singleHighlightGradientChanged(Gradient gradient)
- textureFileChanged(string filename)
- userDefinedMeshChanged(string fileName)
- visibilityChanged(bool visible)
- wireframeColorChanged(color color)

## Methods

- void setMeshAxisAndAngle(vector3d axis, real angle)

## Detailed Description

This type manages the series specific visual elements, as well as the series data (via a data proxy).

Surface3DSeries supports the following format tags for itemLabelFormat:

@xTitle | Title from x-axis
@yTitle | Title from y-axis
@zTitle | Title from z-axis
@xLabel | Item value formatted using the format of the x-axis. For more information, see labelFormat.
@yLabel | Item value formatted using the format of the y-axis. For more information, see labelFormat.
@zLabel | Item value formatted using the format of the z-axis. For more information, see labelFormat.
@seriesName | Name of the series

For a more complete description, see QSurface3DSeries.

See also Qt Graphs Data Handling with 3D.

## Property Documentation

### baseColor : color

The base color of the series.

See also colorStyle and GraphsTheme.seriesColors.

### baseGradient : Gradient

The base gradient of the series.

See also colorStyle.

### colorStyle : GraphsTheme.ColorStyle

The color style for the series.

See also GraphsTheme.ColorStyle.

### dataArray : SurfaceDataArray

Holds the reference of the data array.

dataArrayChanged signal is emitted when data array is set, unless newDataArray is identical to the previous one.

Note: Before doing anything regarding the dataArray, a series must be created for the relevant proxy.

### dataProxy : SurfaceDataProxy

The active data proxy. The series assumes ownership of any proxy set to it and deletes any previously set proxy when a new one is added. The proxy cannot be null or set to another series.

### drawMode : DrawFlag

Sets the drawing mode to one of Surface3DSeries.DrawFlag{QSurface3DSeries.DrawFilledSurface}. Either DrawWireframe or DrawSurface must be set

### flatShadingSupported : bool `[read-only]`

Indicates whether flat shading for surfaces is supported by the current system. It requires at least GLSL version 1.2 with GL_EXT_gpu_shader4 extension.

Note: This read-only property is set to its correct value after the first render pass. Until then it is always `true`.

### invalidSelectionPosition : point `[read-only]`

A constant property providing an invalid selection position. This position is assigned to the selectedPoint property to clear the selection from this series.

See also GraphsItem3D::clearSelection().

### itemLabel : string `[read-only]`

The formatted item label. If there is no selected item or the selected item is not visible, returns an empty string.

See also itemLabelFormat.

### itemLabelFormat : string

The label format for data items in this series. This format is used for single item labels, for example, when an item is selected. How the format is interpreted depends on series type.

See also Bar3DSeries, Scatter3DSeries, and Surface3DSeries.

### itemLabelVisible : bool

If `true`, item labels are drawn as floating labels in the graph. Otherwise, item labels are not drawn. To show the item label in an external control, this property is set to `false`. Defaults to `true`.

See also itemLabelFormat and itemLabel.

### lightingMode : Abstract3DSeries.LightingMode `[since 6.10]`

The lighting mode of the items in the series. The default value is QAbstract3DSeries::LightingMode::Shaded

This property was introduced in Qt 6.10.

See also QAbstract3DSeries::LightingMode.

### mesh : Abstract3DSeries.Mesh

The mesh of the items in the series, or the selection pointer in case of Surface3DSeries. If the mesh is Abstract3DSeries.Mesh.UserDefined, then the userDefinedMesh property must also be set for items to render properly. The default value depends on the graph type.

See also QAbstract3DSeries::Mesh.

### meshRotation : quaternion

The mesh rotation that is applied to all items of the series. The rotation should be a normalized quaternion. For those series types that support item specific rotation, the rotations are multiplied together. Bar3DSeries ignores any rotation that is not around the y-axis. Surface3DSeries applies the rotation only to the selection pointer. Defaults to no rotation.

### meshSmooth : bool

If `true`, smooth versions of predefined meshes set via the mesh property are used. This property does not affect custom meshes used when the mesh is set to Abstract3DSeries.Mesh.UserDefined. Defaults to `false`.

### multiHighlightColor : color

The multiple item highlight color of the series.

See also colorStyle and GraphsTheme.multiHighlightColor.

### multiHighlightGradient : Gradient

The multiple item highlight gradient of the series.

See also colorStyle and GraphsTheme.multiHighlightGradient.

### name : string

The series name. It can be used in item label format with the tag `@seriesName`.

See also itemLabelFormat.

### selectedPoint : point

Sets the surface grid point in the position specified by a row and a column in the data array of the series as selected. Only one point can be selected at a time.

To clear the selection from this series, assign invalidSelectionPosition as the position. If this series is added to a graph, the graph can adjust the selection according to user interaction or if it becomes invalid.

Removing rows from or inserting rows into the series before the row of the selected point will adjust the selection so that the same point will stay selected.

See also GraphsItem3D::clearSelection().

### shading : Shading

Sets surface flat shading to visible. It is preset to `Surface3DSeries.Shading.Flat` by default. When disabled, the normals on the surface are interpolated making the edges look round. When visible, the normals are kept the same on a triangle making the color of the triangle solid. This makes the data more readable from the model.

Note: Flat shaded surfaces require at least GLSL version 1.2 with GL_EXT_gpu_shader4 extension. The value of the flatShadingSupported property indicates whether flat shading is supported at runtime.

### singleHighlightColor : color

The single item highlight color of the series.

See also colorStyle and GraphsTheme.singleHighlightColor.

### singleHighlightGradient : Gradient

The single item highlight gradient of the series.

See also colorStyle and GraphsTheme.singleHighlightGradient.

### textureFile : string

The texture file name for the surface texture. To clear the texture, an empty file name is set.

### type : Abstract3DSeries.SeriesType `[read-only]`

The type of the series. One of the QAbstract3DSeries::SeriesType values.

### userDefinedMesh : string

The filename for a user defined custom mesh for objects that is used when mesh is Abstract3DSeries.Mesh.UserDefined.

Note: The file needs to be in the QtQuick3D mesh format. Use the `balsam` conversion tool to create a mesh from other 3D model formats.

### visible : bool

The visibility of the series. If `false`, the series is not rendered.

### wireframeColor : color

The color used to draw the gridlines of the surface wireframe.

## Signal Documentation

### baseColorChanged(color color)

This signal is emitted when baseColor changes to color.

Note: The corresponding handler is `onBaseColorChanged`.

### baseGradientChanged(Gradient gradient)

This signal is emitted when baseGradient changes to gradient.

Note: The corresponding handler is `onBaseGradientChanged`.

### colorStyleChanged(GraphsTheme.ColorStyle style)

This signal is emitted when colorStyle changes to style.

Note: The corresponding handler is `onColorStyleChanged`.

### dataArrayChanged(SurfaceDataArray array)

This signal is emitted when dataArray changes to array.

Note: The corresponding handler is `onDataArrayChanged`.

### dataProxyChanged(SurfaceDataProxy proxy)

This signal is emitted when dataProxy changes to proxy.

Note: The corresponding handler is `onDataProxyChanged`.

### drawModeChanged(DrawFlag mode)

This signal is emitted when drawMode changes to mode.

Note: The corresponding handler is `onDrawModeChanged`.

### flatShadingSupportedChanged(bool enable)

This signal is emitted when flatShadingSupported changes to enable.

Note: The corresponding handler is `onFlatShadingSupportedChanged`.

### itemLabelChanged(string label)

This signal is emitted when itemLabel changes to label.

Note: The corresponding handler is `onItemLabelChanged`.

### itemLabelFormatChanged(string format)

This signal is emitted when itemLabelFormat changes to format.

Note: The corresponding handler is `onItemLabelFormatChanged`.

### itemLabelVisibilityChanged(bool visible)

This signal is emitted when itemLabelVisibility changes to visible.

Note: The corresponding handler is `onItemLabelVisibilityChanged`.

### `[since 6.10]` lightingModeChanged(Abstract3DSeries.LightingMode lightingMode)

This signal is emitted when lightingMode changes to lightingMode.

Note: The corresponding handler is `onLightingModeChanged`.

This signal was introduced in Qt 6.10.

### meshChanged(Abstract3DSeries.Mesh mesh)

This signal is emitted when mesh changes to mesh.

Note: The corresponding handler is `onMeshChanged`.

### meshRotationChanged(quaternion rotation)

This signal is emitted when meshRotation changes to rotation.

Note: The corresponding handler is `onMeshRotationChanged`.

### meshSmoothChanged(bool enabled)

This signal is emitted when meshSmooth changes to enabled.

Note: The corresponding handler is `onMeshSmoothChanged`.

### multiHighlightColorChanged(color color)

This signal is emitted when multiHighlightColor changes to color.

Note: The corresponding handler is `onMultiHighlightColorChanged`.

### multiHighlightGradientChanged(Gradient gradient)

This signal is emitted when multiHighlightGradient changes to gradient.

Note: The corresponding handler is `onMultiHighlightGradientChanged`.

### nameChanged(string name)

This signal is emitted when name changes to name.

Note: The corresponding handler is `onNameChanged`.

### rowsSanitizedChanged(bool enabled)

This signal is emitted when rowsSanitized changes to enabled.

Note: The corresponding handler is `onRowsSanitizedChanged`.

### selectedPointChanged(point position)

This signal is emitted when selectedPoint changes to position.

Note: The corresponding handler is `onSelectedPointChanged`.

### shadingChanged(const Shading shading)

This signal is emitted when shading changes to shading.

Note: The corresponding handler is `onShadingChanged`.

### singleHighlightColorChanged(color color)

This signal is emitted when singleHighlightColor changes to color.

Note: The corresponding handler is `onSingleHighlightColorChanged`.

### singleHighlightGradientChanged(Gradient gradient)

This signal is emitted when singleHighlightGradient changes to gradient.

Note: The corresponding handler is `onSingleHighlightGradientChanged`.

### textureFileChanged(string filename)

This signal is emitted when textureFile changes to filename.

Note: The corresponding handler is `onTextureFileChanged`.

### userDefinedMeshChanged(string fileName)

This signal is emitted when userDefinedMesh changes to fileName.

Note: The corresponding handler is `onUserDefinedMeshChanged`.

### visibilityChanged(bool visible)

This signal is emitted when the series visibility changes to visible.

Note: The corresponding handler is `onVisibilityChanged`.

### wireframeColorChanged(color color)

This signal is emitted when wireframeColor changes to color.

Note: The corresponding handler is `onWireframeColorChanged`.

## Method Documentation

### void setMeshAxisAndAngle(vector3d axis, real angle)

A convenience function to construct a mesh rotation quaternion from axis and angle.

See also meshRotation.