Out-of-Core Octree STL Viewer This is a high-performance 3D viewer seed project designed to render extremely large STL models that cannot fit into memory (RAM). It utilizes an out-of-core octree data structure to partition the model's geometry and dynamically stream only the visible parts from the disk to the GPU.
This approach allows for the interactive visualization of massive 3D datasets with a limited memory footprint, using C# and OpenTK (OpenGL).
Out-of-Core Rendering: Processes and renders models that are larger than available RAM by keeping most of the data on disk.
Octree-based Spatial Partitioning: The source STL model is pre-processed into an octree structure. This allows for efficient spatial queries and culling.
View Frustum Culling: Only octree nodes that are within the camera's view frustum are considered for rendering, significantly reducing the amount of data processed each frame.
Asynchronous Data Loading: A separate worker thread loads node data from the disk in the background to prevent stuttering in the main render loop.
LRU Cache Management: A Least Recently Used (LRU) cache manages the geometry data that is loaded into memory, ensuring that the most relevant data is kept available while staying within a defined memory budget.
Debug Visualization: An option to render the bounding boxes of the octree nodes, color-coded by their intersection status with the view frustum.
The system operates in two main phases: an offline indexing phase and a real-time rendering phase.
Indexing (First Run):
When the application is run for the first time with a new model.stl file, it performs a pre-processing step.
It reads the entire STL file, calculates the model's global bounds, and builds an octree in memory.
The geometry (triangles) in each leaf node of the octree is serialized and saved to a separate binary file on disk (/nodes/*.bin).
Finally, the overall tree structure (without the bulky geometry) is saved to an index file (/index/model.octree).
Real-time Rendering (Subsequent Runs):
The application loads the lightweight octree index file.
In each frame, it determines which octree nodes are visible using view frustum culling.
For each visible node, it checks if its geometry is present in the LRU cache.
If present, the geometry is rendered directly.
If not present, a request is sent to the background worker thread to load the node's data file from disk. The node will be rendered in a future frame once its data is loaded and uploaded to the GPU.
C#
OpenTK - A fast, low-level C# wrapper for OpenGL.
Prerequisites .NET SDK (6.0 or later)
A graphics card that supports OpenGL 3.3+
Usage Clone the repository.
Place your binary STL file in the project's root directory and name it model.stl.
Open a terminal in the project's root directory and run the application:
Bash
dotnet run On the first launch, please wait for the indexing process to complete. You will see progress updates in the console. Subsequent launches will be much faster.
Rotate Camera: Click and drag with the Left Mouse Button.
Zoom In/Out: Use the Mouse Scroll Wheel.
Toggle Debug View: Press the 'B' key to show/hide the octree bounding boxes.
Out-of-Core 옥트리 STL 뷰어 이 프로젝트는 메모리(RAM)에 모두 담을 수 없는 대용량 STL 모델을 렌더링하기 위해 설계된 3D 뷰어 seed project입니다. Out-of-Core 옥트리 자료구조를 활용하여 모델의 기하학적 구조를 분할하고, 디스크로부터 보이는 부분만 동적으로 스트리밍하여 GPU로 전송합니다.
Out-of-Core 렌더링: 사용 가능한 RAM보다 큰 모델을 디스크에 대부분의 데이터를 유지한 채로 처리하고 렌더링합니다.
옥트리 기반 공간 분할: 원본 STL 모델을 옥트리 구조로 사전 처리하여 효율적인 공간 탐색 및 컬링을 가능하게 합니다.
뷰 프러스텀 컬링: 카메라의 시야(View Frustum) 내에 있는 옥트리 노드만 렌더링 대상으로 고려하여 매 프레임 처리되는 데이터의 양을 크게 줄입니다.
비동기 데이터 로딩: 별도의 워커 스레드가 백그라운드에서 노드 데이터를 로드하여 메인 렌더링 루프의 끊김 현상을 방지합니다.
LRU 캐시 관리: LRU(Least Recently Used) 캐시가 메모리에 로드된 기하학적 데이터를 관리하여, 정해진 메모리 예산 내에서 가장 연관성 높은 데이터를 유지합니다.
디버그 시각화: 옥트리 노드의 경계 상자 시각화 기능을 제공합니다.
시스템은 오프라인 인덱싱 단계와 실시간 렌더링 단계, 두 가지 주요 단계로 동작합니다.
인덱싱 (최초 실행 시):
model.stl 파일로 프로그램을 처음 실행하면, 사전 처리 단계를 수행합니다.
전체 STL 파일을 읽어 모델의 전역 경계를 계산하고 메모리 내에 옥트리를 구축합니다.
옥트리의 각 리프 노드에 포함된 기하 정보(삼각형)는 별도의 바이너리 파일(nodes/*.bin)로 직렬화되어 디스크에 저장됩니다.
마지막으로, 부피가 큰 기하 정보를 제외한 전체 트리 구조가 인덱스 파일(index/model.octree)로 저장됩니다.
실시간 렌더링 (이후 실행 시):
프로그램은 가벼운 옥트리 인덱스 파일을 로드합니다.
매 프레임마다 뷰 프러스텀 컬링을 사용하여 현재 보이는 옥트리 노드를 결정합니다.
각각의 보이는 노드에 대해, 해당 기하 정보가 LRU 캐시에 있는지 확인합니다.
존재하는 경우, 즉시 렌더링합니다.
존재하지 않는 경우, 백그라운드 워커 스레드에 디스크로부터 노드 데이터 파일을 로드하라는 요청을 보냅니다. 데이터가 로드되고 GPU에 업로드되면 다음 프레임부터 렌더링됩니다.
C#
OpenTK - OpenGL을 위한 빠르고 저수준의 C# 래퍼 라이브러리.
요구 사항 .NET SDK (6.0 이상)
OpenGL 3.3 이상을 지원하는 그래픽 카드
사용법 저장소를 복제(Clone)합니다.
프로젝트의 최상위 경로에 바이너리 STL 파일을 위치시키고, 파일명을 model.stl로 변경합니다.
프로젝트의 최상위 경로에서 터미널을 열고 아래 명령어를 실행합니다:
Bash
dotnet run 최초 실행 시에는 인덱싱 과정이 완료될 때까지 기다려주세요. 콘솔에서 진행 상황을 확인할 수 있습니다. 그 이후의 실행은 훨씬 빠릅니다.
카메라 회전: 마우스 왼쪽 버튼을 누른 채로 드래그합니다.
확대/축소: 마우스 스크롤 휠을 사용합니다.
디버그 뷰 전환: 'B' 키를 눌러 옥트리 경계 상자를 표시하거나 숨깁니다.