Back to Qt.io
Contact Us Blog Download Qt

Scatter3D QML Type

3D 분산 그래프. 더 보기...

Import Statement: import QtGraphs
Inherits:

GraphsItem3D

속성

신호

방법

상세 설명

이 유형을 사용하면 개발자가 Qt Quick 를 사용하여 스캐터 그래프를 3D로 렌더링할 수 있습니다.

이 유형을 사용하려면 Qt Graphs 모듈을 임포트해야 합니다:

import QtGraphs

그런 다음 qml 파일에서 Scatter3D를 사용할 수 있습니다:

import QtQuick
import QtGraphs

Item {
    width: 640
    height: 480

    Scatter3D {
        width: parent.width
        height: parent.height
        Scatter3DSeries {
            ItemModelScatterDataProxy {
                itemModel: dataModel
                // Mapping model roles to scatter series item coordinates.
                xPosRole: "xPos"
                yPosRole: "yPos"
                zPosRole: "zPos"
            }
        }
    }

    ListModel {
        id: dataModel
        ListElement{ xPos: "2.754"; yPos: "1.455"; zPos: "3.362"; }
        ListElement{ xPos: "3.164"; yPos: "2.022"; zPos: "4.348"; }
        ListElement{ xPos: "4.564"; yPos: "1.865"; zPos: "1.346"; }
        ListElement{ xPos: "1.068"; yPos: "1.224"; zPos: "2.983"; }
        ListElement{ xPos: "2.323"; yPos: "2.502"; zPos: "3.133"; }
    }
}

자세한 사용 예는 간단한 분산 그래프를 참조하세요.

또한 Scatter3DSeries, ScatterDataProxy, Bars3D, Surface3D, Qt Graphs 3D용 C++ 클래스를참조하세요 .

프로퍼티 문서

ambientLightStrength : real

전체 그래프에 대한 주변광 강도입니다. 이 값은 빛의 위치에 관계없이 그래프 전체에 색상이 얼마나 균일하고 밝게 표시되는지를 결정합니다. 값은 0.0 과 1.0 사이여야 합니다.


aspectRatio : real

가로 평면에서 가장 긴 축과 y축 사이의 그래프 배율 비율입니다. 기본값은 2.0 입니다.

참고: Bars3D 에는 영향을 주지 않습니다.

horizontalAspectRatio 를참조하십시오 .


axisX : Value3DAxis

활성 X축입니다.

축을 지정하지 않으면 레이블이 없고 자동으로 조정되는 범위가 있는 임시 기본 축이 만들어집니다. 이 임시 축은 다른 축이 명시적으로 같은 방향으로 설정되어 있으면 삭제됩니다.


axisY : Value3DAxis

활성 Y축입니다.

축을 지정하지 않으면 레이블이 없고 자동으로 조정되는 범위가 있는 임시 기본 축이 생성됩니다. 이 임시 축은 다른 축이 명시적으로 같은 방향으로 설정되면 삭제됩니다.


axisZ : Value3DAxis

활성 Z축입니다.

축을 지정하지 않으면 레이블이 없고 자동으로 조정되는 범위가 있는 임시 기본 축이 생성됩니다. 이 임시 축은 다른 축이 같은 방향으로 명시적으로 설정되면 삭제됩니다.


cameraPreset : Graphs3D.CameraPreset

현재 활성화된 카메라 프리셋( Graphs3D.CameraPreset 중 하나). 활성화된 프리셋이 없는 경우 값은 Graphs3D.CameraPreset.NoPreset 입니다.


cameraTargetPosition : vector3d

카메라 타깃을 벡터3d로 표현합니다. 기본값은 vector3d(0.0, 0.0, 0.0) 입니다.

유효한 좌표 값은 -1.0...1.0 사이이며, 여기서 에지 값은 해당 축 범위의 에지를 나타냅니다. 이 범위를 벗어나는 모든 값은 가장자리에 고정됩니다.


cameraXRotation : float

현재 기준 위치에서 시작하여 대상 지점을 중심으로 한 카메라의 X 회전 각도(도)입니다.


cameraYRotation : float

현재 기준 위치에서 시작하여 대상 지점을 중심으로 한 카메라의 Y 회전 각도(도)입니다.


cameraZoomLevel : float

카메라 줌 레벨(백분율)입니다. 기본값인 100.0 은 카메라에 줌 인 또는 줌 아웃이 설정되어 있지 않음을 의미합니다. 이 값은 minCameraZoomLevel 및 maxCameraZoomLevel 속성에 의해 제한됩니다.

minCameraZoomLevel 및 maxCameraZoomLevel 을참조하세요 .


currentFps : int

FPS 측정이 활성화되면 지난 1초 동안의 결과가 이 읽기 전용 프로퍼티에 저장됩니다. 측정이 활성화된 후 이 값이 업데이트되기까지 최소 1초가 걸립니다.

measureFps도 참조하세요 .


customItemList : list<Custom3DItem>

그래프에 추가된 Custom3DItem 항목 목록입니다. 그래프가 추가된 항목의 소유권을 가집니다.


gridLineType : Graphs3D.GridLineType

격자선 유형이 Graphs3D.GridLineType.Shader 또는 Graphs3D.GridLineType.Geometry 인지 여부를 정의합니다.

이 값은 모든 그리드 선에 영향을 줍니다.

Graphs3D.GridLineType도 참조하십시오 .


horizontalAspectRatio : real

X축과 Z축 사이의 그래프 배율 비율입니다. 0.0 값은 축 범위에 따른 자동 배율을 나타냅니다. 기본값은 0.0 입니다.

참고: barThickness 및 barSpacing 속성을 통해 가로 평면에서 배율을 처리하는 Bars3D 에는 영향을 미치지 않습니다. 극좌표 그래프도 이 속성을 무시합니다.

aspectRatio, polar, Bars3D::barThickness, Bars3D::barSpacing 을참조하세요 .


labelMargin : real

이 속성은 축 레이블 배치에 대한 여백을 지정합니다.

음수 값은 레이블을 플롯 영역 안에 배치하고 양수 값은 레이블을 플롯 영역 밖에 배치합니다. 값이 음수이면 레이블 자동 회전이 비활성화됩니다. 기본값은 0.1

QAbstract3DAxis::labelAutoAngle 를참조하세요 .


lightColor : color

Scene3D 에 정의된 앰비언트 및 스페큘러 라이트의 색상입니다.


lightStrength : real

전체 그래프의 스페큘러 라이트 강도입니다. 값은 0.0 과 10.0 사이여야 합니다.

이 값은 Scene3D 에 지정된 조명에 영향을 줍니다.


locale : locale

다양한 숫자 레이블의 서식을 지정하는 데 사용되는 로캘을 설정합니다. 기본값은 "C" 로캘입니다.

Value3DAxis::labelFormat 를참조하십시오 .


margin : real

여백 - 플로팅 가능한 그래프 영역의 가장자리와 그래프 배경의 가장자리 사이에 남은 공간에 사용되는 절대값입니다.

여백 값이 음수인 경우 여백은 자동으로 결정되며 계열의 항목 크기 및 그래프 유형에 따라 달라질 수 있습니다. 그래프 가로 세로 비율이 기본값에서 변경되지 않은 경우 이 값은 Y축 범위의 일부분으로 해석됩니다. 기본값은 -1.0 입니다.

참고: 분산형 그래프의 여백을 자동으로 결정된 여백보다 작게 설정하면 그래프 가장자리에 있는 분산형 항목이 그래프 배경과 겹칠 수 있습니다.

참고: 분산형 및 표면 그래프에서 여백이 축 레이블 크기에 비해 작은 경우 축의 가장자리 레이블 위치가 인접 축의 가장자리 레이블과 겹치지 않도록 조정됩니다.


maxCameraZoomLevel : float

허용되는 최대 카메라 줌 레벨을 설정합니다. 새 최대 레벨이 기존 최소 레벨보다 낮으면 최소 레벨도 새 최대 레벨로 조정됩니다. 현재 cameraZoomLevel 이 새 범위를 벗어나면 이 값도 조정됩니다. 기본값은 500.0f 입니다.

cameraZoomLevel 및 minCameraZoomLevel 을참조하세요 .


measureFps : bool

true 인 경우 렌더링은 온디맨드가 아닌 연속적으로 수행되며 currentFps 속성 값이 업데이트됩니다. 기본값은 false 입니다.

currentFps도 참조하십시오 .


minCameraZoomLevel : float

허용되는 최소 카메라 줌 레벨을 설정합니다. 새 최소 레벨이 기존 최대 레벨보다 높으면 최대 레벨도 새 최소 레벨로 조정됩니다. 현재 cameraZoomLevel 가 새 범위를 벗어나면 이 값도 조정됩니다. 최소 카메라 줌 레벨은 1.0 이하로 설정할 수 없습니다. 기본값은 10.0 입니다.

cameraZoomLevel 및 maxCameraZoomLevel 을참조하세요 .


msaaSamples : int

renderingMode 이 Indirect 일 때 멀티샘플 앤티앨리어싱에 사용되는 샘플 수입니다. renderingMode 이 DirectToBackground 일 때 이 속성 값은 읽기 전용이며 창 표면 형식에 지정된 샘플 수를 반환합니다. 기본값은 4 입니다.

renderingMode 를참조하십시오 .


optimizationHint : Graphs3D.OptimizationHint

렌더링 최적화에 기본 모드 또는 레거시 모드를 사용할지 여부를 지정합니다.

기본 모드는 인스턴스 렌더링을 사용하며 대부분의 시스템에서 최상의 성능으로 전체 기능 세트를 제공합니다. 정적 모드는 그래프 렌더링을 최적화하며 변경되지 않는 대규모 데이터 세트에 이상적입니다. 동적 데이터 변경 및 항목 회전 시 속도가 느려집니다. 선택이 최적화되지 않으므로 대규모 데이터 세트에 정적 모드를 사용하는 것은 바람직하지 않습니다. 레거시 모드는 인스턴스화 없이 그래프의 모든 항목을 개별적으로 렌더링합니다. 기본 모드가 작동하지 않는 경우, 즉 대상 시스템이 인스턴싱을 지원하지 않는 경우에만 사용해야 합니다. 기본값은 Default 입니다.

참고: 일부 환경에서는 모든 항목이 단일 그리기 호출을 사용하여 렌더링되고 그래픽 드라이버마다 호출당 최대 버텍스 수를 다르게 지원하기 때문에 정적 최적화를 사용하는 큰 그래프가 렌더링되지 않을 수 있습니다. 이는 주로 32비트 및 OpenGL ES2 플랫폼에서 발생하는 문제입니다. 이 문제를 해결하려면 버텍스 수가 적은 아이템 메쉬를 선택하거나 포인트 메쉬를 사용하세요.

Abstract3DSeries::mesh 및 Graphs3D.OptimizationHint 을참조하세요 .


orthoProjection : bool

true 인 경우 그래프를 표시하는 데 직교 투영이 사용됩니다. 기본값은 false 입니다.

참고: 그림자를 true 으로 설정하면 그림자가 비활성화됩니다.


polar : bool

true 인 경우 가로축이 극축으로 변경됩니다. X축은 각도 축이 되고 Z축은 방사형 축이 됩니다. 막대 그래프에는 극좌표 모드를 사용할 수 없습니다.

기본값은 false 입니다.

orthoProjection 및 radialLabelOffset 을참조하세요 .


queriedGraphPosition : vector3d [read-only]

이 읽기 전용 속성에는 Scene3D::graphPositionQuery 을 사용하여 쿼리한 각 축의 최신 그래프 위치 값이 포함됩니다. 값은 [-1, 1] 범위로 정규화됩니다. 쿼리된 위치가 그래프 범위를 벗어난 경우 값은 실제 위치를 반영하지 않고 대신 범위 밖의 정의되지 않은 위치가 됩니다 [-1, 1]. 쿼리가 수행될 때까지 값은 정의되지 않은 상태로 유지됩니다.

특정 화면 위치와 일치하는 하나의 정확한 3D 좌표는 없으므로 일관성을 유지하기 위해 쿼리는 항상 그래프를 둘러싼 보이지 않는 상자의 안쪽 면을 기준으로 수행됩니다.

참고: 막대 그래프는 그래프 바닥 수준에서만 그래프 위치를 쿼리할 수 있으므로 막대 그래프의 경우 y값은 항상 0이며 그래프의 바닥이 포함된 화면 위치에서만 유효한 쿼리를 수행할 수 있습니다.

Scene3D::graphPositionQuery 를참조하세요 .


radialLabelOffset : real

이 속성은 방사형 극축의 축 레이블에 대한 정규화된 수평 오프셋을 지정합니다. 0.0 값은 레이블이 0각 각축 격자선 옆에 그려져야 함을 나타냅니다. 1.0 값은 레이블이 그래프 배경 가장자리의 일반적인 위치에 그려져야 함을 나타냅니다. 극좌표 속성 값이 false 인 경우 이 속성은 무시됩니다. 기본값은 1.0 입니다.

polar 를참조하세요 .


renderingMode : Graphs3D.RenderingMode

그래프가 렌더링되는 방식. 기본값은 Indirect 입니다.

참고: 그래프의 antialiasing 속성을 설정해도 아무 작업도 수행되지 않습니다. 그러나 현재 렌더링 모드가 앤티앨리어싱을 사용하는 경우 그래프 자체에 의해 설정됩니다.

msaaSamples 및 Graphs3D.RenderingMode 을참조하세요 .


rotationEnabled : bool

이 입력 핸들러가 그래프 회전을 허용할지 여부.

기본값은 true 입니다.


scene : Scene3D [read-only]

씬을 조작하고 씬 요소에 액세스하는 데 사용할 수 있는 Scene3D 포인터입니다.

이 속성은 읽기 전용입니다.


selectedElement : Graphs3D.ElementType [read-only]

그래프에서 선택된 요소입니다.

이 속성은 선택한 요소 유형을 쿼리하는 데 사용할 수 있습니다. 이 유형은 그래프에서 새 선택이 이루어지고 selectedElementChanged 신호가 전송될 때까지 유효합니다.

이 신호는 예를 들어 축 처리 예시에서 설명한 것처럼 사용자 지정 입력 처리를 구현하는 데 사용할 수 있습니다.

selectedLabelIndex(), selectedAxis(), selectedCustomItemIndex(), selectedCustomItem(), Bars3D::selectedSeries, Scatter3D::selectedSeries, Scene3D::selectionQueryPosition, 및 Graphs3D.ElementType 을참조하세요 .


selectedSeries : Scatter3DSeries [read-only]

선택된 시리즈 또는 null.


selectionEnabled: bool

이 입력 핸들러가 그래프에서 선택을 허용할지 여부입니다.

기본값은 true 입니다.


selectionMode : Graphs3D.SelectionMode

그래프의 활성 선택 모드입니다. Graphs3D.SelectionFlag 열거형 값 중 하나입니다.


seriesList : list<Scatter3DSeries> [default]

이 속성은 그래프의 계열을 보유합니다. 기본적으로 이 속성에는 빈 목록이 포함됩니다. 계열을 설정하려면 addSeries() 메서드를 사용하거나 그래프의 자식으로 정의합니다.


shadowQuality : Graphs3D.ShadowQuality

그림자의 품질. Graphs3D.ShadowQuality 열거형 값 중 하나입니다.


shadowStrength : real

전체 그래프의 그림자 강도입니다. 숫자가 높을수록 그림자가 더 어두워집니다. 값은 0.0 과 100.0 사이여야 합니다.

이 값은 Scene3D 에 지정된 조명에 영향을 줍니다.


theme : GraphsTheme

그래프의 활성 테마.

GraphsTheme 를참조하세요 .


wrapCameraXRotation : bool

X 회전의 최소 및 최대 제한의 동작입니다. 기본적으로 X 회전은 최소값에서 최대값으로, 최대값에서 최소값으로 래핑됩니다.

true 로 설정하면 카메라의 X 회전이 최소값에서 최대값으로, 최대값에서 최소값으로 래핑됩니다. false 로 설정하면 카메라의 X 회전이 최소값과 최대값에 의해 결정된 섹터로 제한됩니다.


wrapCameraYRotation : bool

Y 회전의 최소 및 최대 제한의 동작입니다. 기본적으로 Y 회전은 래핑 없이 최소값과 최대값 사이에서 제한됩니다.

true 인 경우 카메라의 Y 회전은 최소에서 최대로, 최대에서 최소로 래핑됩니다. false 인 경우 카메라의 Y 회전은 최소값과 최대값에 의해 결정된 섹터로 제한됩니다.


zoomAtTargetEnabled : bool

확대/축소 후 그래프의 확대/축소된 지점이 동일한 위치에 유지되도록 카메라 대상을 변경할지 여부입니다.

기본값은 true 입니다.


zoomEnabled : bool

이 입력 핸들러가 그래프 확대/축소를 허용할지 여부입니다.

기본값은 true 입니다.


신호 문서

axisXChanged(ValueAxis3D axis)

* axisX 이 axis 으로 변경될 때 이 신호가 발생합니다.

참고: 해당 핸들러는 onAxisXChanged 입니다.


axisYChanged(ValueAxis3D axis)

* axisY 이 axis 으로 변경될 때 이 신호가 전송됩니다.

참고: 해당 핸들러는 onAxisYChanged 입니다.


axisZChanged(ValueAxis3D axis)

* * * axisZ 이 axis 으로 변경될 때 이 신호가 전송됩니다.

참고: 해당 핸들러는 onAxisZChanged 입니다.


doubleTapped(QEventPoint eventPoint, Qt::MouseButton button)

이 신호는 그래프 항목이 짧은 시간 내에 두 번 탭될 때 발생합니다. eventPoint 신호 매개변수에는 탭한 지점에 대한 릴리스 이벤트의 정보가 포함되며, button 은 클릭한 mouse button 또는 터치스크린의 경우 NoButton 입니다.

참고: 해당 핸들러는 onDoubleTapped 입니다.

QEventPoint, Qt::MouseButtons, TapHandler::doubleTapped도 참조하세요 .


dragged(QVector2D delta)

이 신호는 핀치 제스처가 수행되는 동안 그래프에서 점 클러스터의 이동이 변경될 때 발생합니다. delta 벡터는 번역의 변화를 나타냅니다.

참고: 해당 핸들러는 onDragged 입니다.

PinchHandler::translationChanged도 참조하세요 .


longPressed()

이 신호는 parent 항목을 TapHandler::longPressThreshold 보다 긴 시간 동안 길게 누르면 발산됩니다.

참고: 해당 핸들러는 onLongPressed 입니다.

TapHandler::longPressed도 참조하십시오 .


mouseMove(QPoint mousePos)

이 신호는 그래프가 마우스 이동 이벤트를 수신할 때 발생합니다. mousePos 값은 마우스가 이동하는 동안 마우스 위치를 알려줍니다.

참고: 해당 핸들러는 onMouseMove 입니다.

QQuickItem::mouseMoveEvent도 참조하세요 .


pinch(qreal delta)

이 신호는 핀치 제스처가 수행되는 동안 그래프의 배율이 변경될 때 발생합니다. delta 값은 배율의 승수 변화를 나타냅니다.

참고: 해당 핸들러는 onPinch 입니다.

PinchHandler::scaleChanged도 참조하세요 .


selectedSeriesChanged(Scatter3DSeries series)

* selectedSeries 이 series 으로 변경될 때 이 신호가 발생합니다.

참고: 해당 핸들러는 onSelectedSeriesChanged 입니다.


tapped(QEventPoint eventPoint, Qt::MouseButton button)

이 신호는 그래프 항목을 한 번 탭할 때 발생합니다. eventPoint 신호 매개변수에는 탭한 지점에 대한 릴리스 이벤트의 정보가 포함되어 있으며 button 은 클릭한 mouse button 또는 터치스크린의 경우 NoButton 입니다.

참고: 해당 핸들러는 onTapped 입니다.

QEventPoint, Qt::MouseButtons, TapHandler::singleTapped도 참조하세요 .


wheel(QQuickWheelEvent *event)

이 신호는 그래프가 QWheelEvent 유형의 event, 즉 휠을 움직이거나 스크롤 제스처가 업데이트될 때마다 발생합니다.

참고: 해당 핸들러는 onWheel 입니다.

WheelEvent 및 WheelHandler::wheel 을참조하세요 .


메서드 문서

qsizetype addCustomItem(Custom3DItem item)

그래프에 Custom3DItem item 을 추가합니다. 그래프는 추가된 항목의 소유권을 갖습니다.

추가에 성공하면 추가된 항목의 인덱스를, 널 항목을 추가하려고 하면 -1을, 이미 추가된 항목을 추가하려고 하면 해당 항목의 인덱스를 반환합니다.

removeCustomItems(), removeCustomItem() 및 removeCustomItemAt()도 참조하세요 .


void addSeries(Scatter3DSeries series)

그래프에 series 를 추가합니다. 그래프에는 여러 계열을 포함할 수 있지만 축은 한 세트만 있습니다. 새로 추가된 시리즈에 선택한 항목이 지정되어 있으면 해당 항목이 강조 표시되고 기존 선택 항목은 모두 지워집니다. 추가된 계열은 하나만 활성 선택 항목을 가질 수 있습니다.

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


void clearSelection()

연결된 모든 시리즈에서 선택을 지웁니다.


bool hasSeries(Abstract3DSeries series)

series 가 이미 그래프에 추가되었는지 여부를 반환합니다.


void releaseCustomItem(Custom3DItem item)

item 의 소유권을 되찾고 그래프에서 item 을 제거합니다.

참고: 동일한 항목이 그래프에 다시 추가되면 텍스처 파일을 다시 설정해야 합니다.

Custom3DItem::textureFile 를참조하세요 .


void removeCustomItem(Custom3DItem item)

사용자 지정 item 을 제거합니다. 여기에 할당된 리소스를 삭제합니다.


void removeCustomItemAt(vector3d position)

position 에서 모든 사용자 정의 항목을 제거합니다. 해당 항목에 할당된 리소스를 삭제합니다.


void removeCustomItems()

모든 사용자 지정 항목을 제거합니다. 해당 항목에 할당된 리소스를 삭제합니다.


void removeSeries(Scatter3DSeries series)

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

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


Abstract3DAxis selectedAxis()

모든 레이블 유형으로 selectedElementChanged 신호를 수신한 후 선택한 축을 가져오는 데 사용할 수 있습니다. 선택은 다음 selectedElementChanged 신호까지 유효합니다.

선택한 축을 반환하거나 null을 반환합니다.

selectedElement 를참조하세요 .


Custom3DItem selectedCustomItem()

ElementType.CustomItem 유형으로 selectedElementChanged 신호를 수신한 후 선택한 사용자 지정 항목을 가져오는 데 사용할 수 있습니다. 항목의 소유권은 그래프에 유지됩니다. 선택 항목은 다음 selectedElementChanged 신호까지 유효합니다.

선택한 사용자 지정 항목 또는 null을 반환합니다.

selectedElement도 참조하세요 .


qsizetype selectedCustomItemIndex()

ElementType.CustomItem 타입으로 selectedElementChanged 신호를 수신한 후 선택한 사용자 지정 항목의 인덱스를 쿼리하는 데 사용할 수 있습니다. 선택 항목은 다음 selectedElementChanged 신호까지 유효합니다.

선택한 사용자 지정 항목의 인덱스 또는 -1을 반환합니다.

selectedElement 를참조하세요 .


int selectedLabelIndex()

모든 레이블 유형으로 selectedElementChanged 신호를 받은 후 선택한 레이블의 인덱스를 쿼리하는 데 사용할 수 있습니다. 선택은 다음 selectedElementChanged 신호까지 유효합니다.

선택한 레이블의 인덱스 또는 -1을 반환합니다.

selectedElement도 참조하세요 .


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