이 페이지에서

Q3DSurface Class

Q3DSurface 클래스는 3D 표면 플롯을 렌더링하는 메서드를 제공합니다. 더 보기...

헤더: #include <Q3DSurface>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
출시일: QtDataVisualization 1.0
상속: QAbstract3DGraph
상태: 사용 중단됨

이 클래스는 더 이상 사용되지 않습니다. 새로운 코드에서는 이 클래스를 사용하지 않는 것을 강력히 권장합니다.

속성

공개 함수

Q3DSurface(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)
virtual ~Q3DSurface()
void addAxis(QValue3DAxis *axis)
void addSeries(QSurface3DSeries *series)
QList<QValue3DAxis *> axes() const
QValue3DAxis *axisX() const
QValue3DAxis *axisY() const
QValue3DAxis *axisZ() const
bool flipHorizontalGrid() const
void releaseAxis(QValue3DAxis *axis)
void removeSeries(QSurface3DSeries *series)
QSurface3DSeries *selectedSeries() const
QList<QSurface3DSeries *> seriesList() const
void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

신호

void axisXChanged(QValue3DAxis *axis)
void axisYChanged(QValue3DAxis *axis)
void axisZChanged(QValue3DAxis *axis)
void flipHorizontalGridChanged(bool flip)
void selectedSeriesChanged(QSurface3DSeries *series)

상세 설명

이 클래스를 사용하면 개발자가 3D 표면 플롯을 렌더링하고, 장면을 자유롭게 회전시키며 볼 수 있습니다. 그리기 모드 및 셰이딩과 같은 표면의 시각적 속성은 ` QSurface3DSeries`을 통해 제어할 수 있습니다.

Q3DSurface는 사용자가 마우스 왼쪽 버튼으로 클릭한 데이터 포인트(기본 입력 핸들러를 사용하는 경우) 또는 QSurface3DSeries 을 통해 선택한 데이터 포인트에 강조 표시된 구체를 표시하여 선택을 지원합니다. 선택 포인터에는 레이블이 함께 표시되며, 기본적으로 데이터 포인트의 값과 해당 점의 좌표를 보여줍니다.

축에 표시되는 값의 범위와 레이블 형식은 ` QValue3DAxis`를 통해 제어할 수 있습니다.

그래프를 회전하려면 마우스 오른쪽 버튼을 누른 상태에서 마우스를 이동합니다. 확대/축소는 마우스 휠을 사용하여 수행합니다. 두 작업 모두 기본 입력 핸들러가 사용 중임을 전제로 합니다.

Q3DSurface에 축이 명시적으로 설정되지 않은 경우, 레이블이 없는 임시 기본 축이 생성됩니다. 이러한 기본 축은 축 액세스자를 통해 수정할 수 있지만, 방향에 대해 축이 명시적으로 설정되는 즉시 해당 방향의 기본 축은 소멸됩니다.

최소 구성의 Q3DSurface 그래프를 생성하는 방법

먼저, Q3DSurface를 생성합니다. 이 예제에서는 그래프를 최상위 창으로 실행하고 있으므로, 기본적으로 설정되어 있는 ` Qt::FramelessWindowHint ` 플래그를 해제해야 합니다:

Q3DSurface surface;
surface.setFlags(surface.flags() ^ Qt::FramelessWindowHint);

이제 Q3DSurface는 렌더링할 데이터를 수신할 준비가 되었습니다. 값을 수신할 데이터 요소를 생성합니다:

먼저 데이터를 행 요소에 전달한 다음, 해당 포인터를 데이터 요소에 추가합니다:

*dataRow1 << QVector3D(0.0f, 0.1f, 0.5f) << QVector3D(1.0f, 0.5f, 0.5f);
*dataRow2 << QVector3D(0.0f, 1.8f, 1.0f) << QVector3D(1.0f, 1.2f, 1.0f);
*data << dataRow1 << dataRow2;

새로운 시리즈를 생성하고 데이터를 설정합니다:

QSurface3DSeries *series = new QSurface3DSeries;
series->dataProxy()->resetArray(data);
surface.addSeries(series);

마지막으로 그래프를 표시하도록 설정해야 합니다:

surface.show();

이 그래프를 생성하고 표시하는 데 필요한 전체 코드는 다음과 같습니다:

#include <QtDataVisualization>

int main(int argc, char **argv)
{
    qputenv("QSG_RHI_BACKEND", "opengl");
    QGuiApplication app(argc, argv);

    Q3DSurface surface;
    surface.setFlags(surface.flags() ^ Qt::FramelessWindowHint);
    QSurfaceDataArray *data = new QSurfaceDataArray;
    QSurfaceDataRow *dataRow1 = new QSurfaceDataRow;
    QSurfaceDataRow *dataRow2 = new QSurfaceDataRow;

    *dataRow1 << QVector3D(0.0f, 0.1f, 0.5f) << QVector3D(1.0f, 0.5f, 0.5f);
    *dataRow2 << QVector3D(0.0f, 1.8f, 1.0f) << QVector3D(1.0f, 1.2f, 1.0f);
    *data << dataRow1 << dataRow2;

    QSurface3DSeries *series = new QSurface3DSeries;
    series->dataProxy()->resetArray(data);
    surface.addSeries(series);
    surface.show();

    return app.exec();
}

그리고 이 몇 줄의 코드가 만들어내는 결과는 다음과 같습니다:

격자 무늬 바닥 위에 녹색의 접힌 능선 표면이 표시된 최소한의 3D 표면 그래프

이 장면을 회전하거나 확대할 수 있으며, 표면 상의 점을 선택하여 그 위치를 확인할 수 있지만, 이 최소한의 코드 예제에는 그 외의 상호작용 기능은 포함되어 있지 않습니다. ‘표면 그래프(Surface Graph)’와 같은 제공된 예제를 살펴보시면 더 자세한 내용을 확인하실 수 있습니다.

Q3DBars, Q3DScatter 및 Qt Data Visualization C++ Classes.

속성 문서

axisX : QValue3DAxis*

이 속성은 활성 x축을 지정합니다.

액세스 함수:

QValue3DAxis *axisX() const
void setAxisX(QValue3DAxis *axis)

알림 신호:

void axisXChanged(QValue3DAxis *axis)

axisY : QValue3DAxis*

이 속성은 활성 Y축을 지정합니다.

액세스 함수:

QValue3DAxis *axisY() const
void setAxisY(QValue3DAxis *axis)

알림 신호:

void axisYChanged(QValue3DAxis *axis)

axisZ : QValue3DAxis*

이 속성은 활성 z축을 나타냅니다.

액세스 함수:

QValue3DAxis *axisZ() const
void setAxisZ(QValue3DAxis *axis)

알림 신호:

void axisZChanged(QValue3DAxis *axis)

[since QtDataVisualization 1.2] flipHorizontalGrid : bool

이 속성은 가로축 눈금이 그래프 하단이 아닌 상단에 표시되는지 여부를 지정합니다.

일부 사용 사례에서는 수평축 격자가 그래프 영역에 대부분 가려지기 때문에, 수평축 격자를 그래프 하단이 아닌 상단에 표시하는 것이 더 유용할 수 있습니다. 이에 대한 대표적인 사용 사례는 상단에서 하단을 내려다보는 시점을 사용하는 정투영(orthographic projection) 방식의 2D 스펙트로그램을 표시하는 경우입니다.

false 인 경우, 가로축 격자와 레이블은 그래프의 가로 배경 위에 그려집니다. true 인 경우, 가로축 격자와 레이블은 가로 배경과 반대편 그래프 영역에 그려집니다. 기본값은 false 입니다.

이 열거형은 QtDataVisualization 1.2에서 도입되었습니다.

액세스 함수:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Notifier 신호:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

이 속성은 선택된 시리즈를 반환하거나 null을 반환합니다.

selectionMode에 ' SelectionMultiSeries '가 설정된 경우, 이 속성은 선택된 점을 소유한 시리를 저장합니다.

액세스 함수:

QSurface3DSeries *selectedSeries() const

알림 신호:

void selectedSeriesChanged(QSurface3DSeries *series)

멤버 함수 설명서

[explicit] Q3DSurface::Q3DSurface(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)

선택 사항인 parent 창과 표면 format 을 사용하여 새로운 3D 표면 그래프를 생성합니다.

[virtual noexcept] Q3DSurface::~Q3DSurface()

3D 표면 그래프를 삭제합니다.

void Q3DSurface::addAxis(QValue3DAxis *axis)

그래프에 ` axis `을 추가합니다. `addAxis`를 통해 추가된 축은 아직 사용 대상으로 간주되지 않으며, `addAxis`는 단순히 ` axis `의 소유권을 그래프에 부여하기 위해 사용됩니다. ` axis `는 `null`이거나 다른 그래프에 추가되어서는 안 됩니다.

releaseAxis(), setAxisX(), setAxisY() 및 setAxisZ()도 참조하십시오 .

void Q3DSurface::addSeries(QSurface3DSeries *series)

그래프에 ‘ series ’를 추가합니다. 그래프에는 여러 시계가 포함될 수 있지만, 축 세트는 하나만 가질 수 있습니다. 새로 추가된 시계에 선택 항목이 지정되어 있으면 해당 항목이 강조 표시되고, 기존 선택 항목은 모두 해제됩니다. 추가된 시계 중 하나만 선택 상태로 유지될 수 있습니다.

QAbstract3DGraph::hasSeries()도 참조하십시오 .

QList<QValue3DAxis *> Q3DSurface::axes() const

추가된 모든 축의 목록을 반환합니다.

addAxis()도 참조하십시오 .

void Q3DSurface::releaseAxis(QValue3DAxis *axis)

axis 가 이 그래프에 추가된 경우, 해당 축의 소유권을 호출자에게 반환합니다. 반환된 axis 가 사용 중인 경우, 새로운 기본 축이 생성되어 활성 상태로 설정됩니다.

기본 축이 해제되었다가 나중에 다시 추가되면, 다른 축과 마찬가지로 동작합니다.

addAxis(), setAxisX(), setAxisY(), setAxisZ()도 참조하십시오 .

void Q3DSurface::removeSeries(QSurface3DSeries *series)

그래프에서 ‘ series ’를 제거합니다.

QAbstract3DGraph::hasSeries()도 참조하십시오 .

QList<QSurface3DSeries *> Q3DSurface::seriesList() const

이 그래프에 추가된 시리즈 목록을 반환합니다.

QAbstract3DGraph::hasSeries()도 참조하십시오 .

void Q3DSurface::setAxisX(QValue3DAxis *axis)

axis 를 활성 X축으로 설정합니다. addAxis()을 묵시적으로 호출하여 축의 소유권을 이 그래프로 이전합니다.

axis 가 null인 경우, 레이블이 없고 범위가 자동으로 조정되는 임시 기본 축이 생성됩니다.

다른 축이 동일한 방향으로 명시적으로 설정되면 이 임시 축은 삭제됩니다.

참고: axisX 속성에 대한세터 함수입니다.

axisX(), addAxis() 및 releaseAxis()도 참조하십시오 .

void Q3DSurface::setAxisY(QValue3DAxis *axis)

axis 를 활성 Y축으로 설정합니다. addAxis()를 묵시적으로 호출하여 축의 소유권을 이 그래프로 이전합니다.

axis 가 null인 경우, 레이블이 없고 범위가 자동으로 조정되는 임시 기본 축이 생성됩니다.

다른 축이 동일한 방향으로 명시적으로 설정되면 이 임시 축은 소멸됩니다.

참고: axisY 속성에 대한세터 함수입니다.

axisY(), addAxis() 및 releaseAxis()도 참조하십시오 .

void Q3DSurface::setAxisZ(QValue3DAxis *axis)

axis 를 활성 Z축으로 설정합니다. addAxis()을 암시적으로 호출하여 해당 축의 소유권을 이 그래프로 이전합니다.

axis 가 null인 경우, 레이블이 없고 범위가 자동으로 조정되는 임시 기본 축이 생성됩니다.

다른 축이 명시적으로 동일한 방향으로 설정되면 이 임시 축은 소멸됩니다.

참고: axisZ 속성에 대한세터 함수입니다.

axisZ(), addAxis() 및 releaseAxis()도 참조하십시오 .

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.