이 페이지에서

Q3DSurfaceWidgetItem Class

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

헤더: #include <Q3DSurfaceWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake: QT += graphswidgets
상속: Q3DGraphsWidgetItem

속성

공개 함수

Q3DSurfaceWidgetItem(QObject *parent = nullptr)
virtual ~Q3DSurfaceWidgetItem() override
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)
(since 6.10) void renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
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)
(since 6.10) void sliceImageChanged(const QImage &image)

상세 설명

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

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

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

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

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

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

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

QQuickWidget quickWidget;
Q3DSurfaceWidgetItem surface;
surface.setWidget(&quickWidget);
surface.widget()->setMinimumSize(QSize(256, 256));

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

참고: 새로운 프록시-시리즈관계에서는 데이터가 시리즈에 저장됩니다. 따라서 프록시가 데이터를 추가, 삭제 또는 편집할 수 있도록 하려면 먼저 시리즈를 생성해야 합니다.

먼저 데이터를 행 요소에 입력한 다음, 해당 포인터를 데이터 요소에 추가하십시오:

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

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

QSurface3DSeries series;
series.dataProxy()->resetArray(data);
surface.addSeries(&series);

마지막으로 이 요소를 표시하도록 설정해야 합니다:

surface.widget()->show();

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

#include <QtGraphs>
#include <QtGraphsWidgets/q3dsurfacewidgetitem.h>
#include <QtWidgets/qapplication.h>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QQuickWidget quickWidget;
    Q3DSurfaceWidgetItem surface;
    surface.setWidget(&quickWidget);
    surface.widget()->setMinimumSize(QSize(256, 256));
    QSurfaceDataArray data;
    QSurfaceDataRow dataRow1;
    QSurfaceDataRow dataRow2;

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

    QSurface3DSeries series;
    series.dataProxy()->resetArray(data);
    surface.addSeries(&series);
    surface.widget()->show();

    return app.exec();
}

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

경사진 녹색 평면이 포함된 3D 표면 플롯

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

Q3DBarsWidgetItem, Q3DScatterWidgetItem, Qt Graphs 의 3D용 C++ 클래스도 참조하십시오 .

속성 문서

axisX : QValue3DAxis*

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

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

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

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

액세스 함수:

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

알림 신호:

void axisXChanged(QValue3DAxis *axis)

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

axisY : QValue3DAxis*

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

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

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

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

액세스 함수:

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

알림 신호:

void axisYChanged(QValue3DAxis *axis)

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

axisZ : QValue3DAxis*

이 속성은 활성 Z축을 저장합니다.

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

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

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

액세스 함수:

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

알림 신호:

void axisZChanged(QValue3DAxis *axis)

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

flipHorizontalGrid : bool

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

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

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

액세스 함수:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

알림 신호:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

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

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

액세스 함수:

QSurface3DSeries *selectedSeries() const

알림 신호:

void selectedSeriesChanged(QSurface3DSeries *series)

멤버 함수 설명서

[explicit] Q3DSurfaceWidgetItem::Q3DSurfaceWidgetItem(QObject *parent = nullptr)

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

[override virtual noexcept] Q3DSurfaceWidgetItem::~Q3DSurfaceWidgetItem()

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

void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *axis)

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

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

void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)

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

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

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

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

addAxis()도 참조하십시오 .

void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *axis)

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

기본 축이 해제되었다가 나중에 다시 추가되면, 다른 축과 동일한 방식으로 동작합니다.

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

void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)

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

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

[since 6.10] void Q3DSurfaceWidgetItem::renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)

요청된 슬라이스 뷰를 이미지로 내보냅니다. 슬라이스된 결과는 index 의 시퀀스입니다. 모든 시퀀스를 내보내려면 index 를 -1로 설정하십시오. 내보낸 슬라이스는 sliceType 로 정의된 행 또는 열의 한 줄이며, 지정된 requestedIndex 에서 생성됩니다.

sliceImageChanged 신호는 이미지가 준비되면 발생하며, 다음과 같이 캡처할 수 있습니다:

connect(item, &Q3DSurfaceWidgetItem::sliceImageChanged, this, [](const QImage &image) {
    // ~~~
});

item->renderSliceToImage(sliceType, index);

이미지는 현재 앤티앨리어싱 설정으로 렌더링됩니다.

이 함수는 Qt 6.10에서 도입되었습니다.

QQuickItem::grabToImage() 및 sliceImageChanged()도 참조하십시오 .

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

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

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

[signal, since 6.10] void Q3DSurfaceWidgetItem::sliceImageChanged(const QImage &image)

renderSliceToImage 가 image 를 준비했을 때 발생합니다.

이 함수는 Qt 6.10에서 도입되었습니다.

© 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.