Point Cloud Workflow
- bianca.badajos
3D Data Overview
Pointclouds and Potree
Point clouds are a collection of data points defined in a three-dimensional coordinate system.
Potree is an open-source project that enables the visualization of large 3D point clouds on the web. It provides a user-friendly interface for exploring and interacting with massive datasets. Potree was built combining various pre-existing 3D data GL (graphics libraries) to allow you to present scans with highly customizable viewers.
Each scan hosted on our server is done with Potree.
Potree References:
Browser Functionalities provides a thorough explanation of what a Potree viewer provides for users
pointcloud.ucla.edu
Our online repository for point clouds is hosted with Amazon Web Services (AWS). We store each point cloud and various viewers here, all sorted by project. Each item present in the index is located with the “Potree” folder of the EC2 instance. See more info below on AWS, accessing the instance, and uploading files.
Open “VHM” to view scans from the Vietnamese Heritage Museum, such as the refugee boat shown below. Our server and use of Potree allows for the pointclouds to be embedded as an iframe into websites using a protected UCLA URL, shown here in Confluence.
Right-click to drag, left-click to rotate
Setting up your enviroment: What you’ll need
To use the remote desktop:
To upload a point cloud to the server:
*These are provided for you.
Accessing the PCWS
The Point Cloud Workstation is where you can work with large point cloud datasets. The computer is located in YRL, but you can access it anywhere you have connected to the UCLA VPN. You should download any supplementary programs here. The drives connected to this computer are good places to keep point cloud files of any kind due to their large storage capacities. Typically a drive will be designated for specific projects.
You’ll need to be connected to the UCLA VPN, which you can download here. You must re-connect each time you connect to wifi / upon opening your computer.
Remote Desktop Connection is available on Windows. When the program is opened, you’ll see a log in page to enter your credentials- make sure to save them upon first log in.
Logging into AWS
Once you have an AWS IAM account, log in with https://us-east-2.signin.aws.amazon.com/oauth?client_id=arn%3Aaws%3Asignin%3A%3A%3Aconsole%2Fcanvas&code_challenge=bUE6c08X9Y89JUFw1SppHxIzuOk6kk_UPJ_B2vd3cDY&code_challenge_method=SHA-256&response_type=code&redirect_uri=https%3A%2F%2Fconsole.aws.amazon.com%2Fconsole%2Fhome%3FhashArgs%3D%2523%26isauthcode%3Dtrue%26nc2%3Dh_ct%26oauthStart%3D1724105375886%26src%3Dheader-signin%26state%3DhashArgsFromTB_us-east-2_eeaeecfaa4a793fe. You’ll need an account ID, IAM user name, and password.
Accessing and Navigating the point cloud server
Obtain the public key or PEM file, “potree-test.pem” and place it in your .ssh folder, which you should find at "C:\Users\yourUser\.ssh\". Access the server via SSH by entering this line into Command Prompt:
ssh -i ".ssh/potree-test.pem" ubuntu@ec2-44-225-161-146.us-west-2.compute.amazonaws.com
Once entering the server, navigation is similar to that in terminal.
Commands
ls - lists all items in your current folder
cd [targetfolder] - opens target folder
cd .. - opens the parent folder (the folder one level up)
cd ../.. - opens parent folder of the parent folder (the folder 2 levels up)
mv currentfilepath destinationfilepath - moves file
rm file - removes file
cp currentfilepath destinationfilepath - copies file
du -h --max-depth=1 | sort -rh
du - shows files sizes in a directory
-h - makes the sizes “human readable”
--max-depth=1 - excludes the contents of any folders
sort -rh - sorts greatest-to-least
Downloads: Potree, Cloud Compare, VS Code, XAMPP
Potree currently only converts on a Windows or Linux OS, so it’s recommended to keep your downloads on the PCWS if not your personal Windows computer.
https://cloudcompare-org.danielgm.net/release/ Download the latest version of Cloud Compare for your OS.
There’s 2 potential downloads to use Potree:
PotreeDesktop opens a window where you can drag-and-drop and see the final point cloud when the conversion is complete
PotreeConverter allows you to use command prompt or drag-and-drop in the file explorer for your conversions
Unzip the download (Windows10: Right clip zipped folder → “Extract All” → choose destination)
To run the converter, you’ll need Node.JS, which you can download here.
Download instructions for any Potree version can be found on the Github.
Hosting Locally with XAMPP
To edit an opened viewer without directly updating the file on the server, you can view your HTML files locally on your computer with XAMPP. This is also useful for editing sites before pushing changes to Github.
Download XAMPP
XAMPP folders are typically located on the top level of the C: drive, or main computer drive
Open the XAMPP Control Panel
Search “XAMPP Control Panel” or open the file at "C:/xampp/xampp_start.exe"
Click “Start” beside Apache to start running the module
In future cases where your file cannot be accessed, open up the Control Panel and ensure Apache is running
For the purpose of hosting Potree viewers, only Apache is needed
Be sure to note which ports are being used
Open “xampp/htdocs” and drop the potree viewer html and pointcloud folders
Ensure the point cloud paths are correctly referenced in the HTML
Open your browser and enter “localhost/example.html” or “localhost:[port number]/example.html”
Common port numbers: 80, 180
From Scan to Server
Converting and orienting with Cloud Compare
Once converted from the raw scans, pointcloud folders will contain a material file (.mtl), an object file (.obj), and a photo (.jpg). When you load an object file into Cloud Compare, the associated files will be processed as well. Here, you will convert the point cloud into a .las file and orient it as you’d like it to be presented on the server.
Opening your file
Open Cloud Compare
Click “File” → “Open” → “yourscan.obj”
“Global shift and scale”
When you import a pointcloud, it will prompt a global shift to adapt. Accept the global shift to with “Yes to all” to maintain the original point distribution. Cloud compare can’t handle the original coordinate range of pointclouds, so it will temporarily shift the cloud. Shifting the cloud yourself may cause location or length discrepancies. The original local coordinates are restored on export.
Picking a rotation center
Select the target pointcloud under “DB Tree”
Decide on a point on your cloud to be the rotation center and rotate the object so the point is in view
Click the “Rotate” icon
Click your desired rotation center
Rotating
The Potree viewer will generate the point cloud along the coordinate plane. Rotate the scan so it horizontally aligns with the x-axis and vertically aligns with the z-axis.
Select the target pointcloud under “DB Tree”
On the left vertical toolbar, click the “Front” icon to adjust the pointcloud to it’s default “front”
On the top toolbar, select the “Rotate/Translate” icon
Drag to rotate your item to set its new “front”
Click the checkmark in the upper right when complete
Note the coordinate plane reference on the bottom right of the CC window.
The Bounding Box: The yellow box around your pointcloud is an indicator of the coordinate plane. When you rotate your object with the rotation tool, the bounding box will re-adjust to reflect the object’s new position in the plane. The bounding box will adjust to align with the coordinate planes once the rotation is complete.
Exporting as a LAS file
Select the target pointcloud under “DB Tree”
On the top toolbar, click the “Sample points on a mesh” icon
Add a couple 0s to the points number and click “Ok”
Once your sample has generated, it will appear in the “DB Tree” window on the left, beside a cloud icon. Click the sample and and select the save icon.
Save as a .las/.laz
Save with “optimal resolution”
Check the Cloud Compare console to ensure the conversion and save were successful.
Troubleshooting CloudCompare
Converting from a LAS file to a Potree folder
Open PotreeDesktop.bat as a shortcut or from your download folder. Drag and drop your las file into the window, and watch it generate. The pointcloud will appear as it would in a standard Potree viewer as soon as the conversion is complete. You can drag multiple las files in the window to be converted.
To skip opening the desktop program, use PotreeConverter to convert in the terminal, or drag and drop las files over PotreeConverter.exe to convert within FileExplorer.
Once the conversion is complete, a new folder named “orginal.las”+”_converted” will share the same location as the source .las file. This new folder should contain 3 files: metadata.json, octree.bin, and hierarchy.bin. If a “chunks” file is present and any of the other files are missing, the conversion is either not yet complete or has failed.
AWS & Uploading to the Point Cloud Server
We use Amazon Web Services (AWS) for the EC2 virtual server and S3 storage buckets.
Potree HTML files are stored on the server. Larger files (like point cloud folders) are stored in s3 buckets. You can use your terminal and AWS CLI to access each for uploading and editing files.
Connecting to AWS Command Line Interface (CLI)
AWS CLI allows you to upload and access the server and storage from your desktop.
1. Download AWS CLI
Find your access keys
Login to the IAM Console
Search “Identity and Access Management (IAM)”
Click “Users” under “Access Management” in the left nav bar
Find your user and open the “Security Credentials” tab
Scroll to find and click “Create access key”
Save your secret access key immediately along with your access key, as it is only shared on creation
Configure AWS CLI in Command Prompt (CMD) by entering the following:
aws configureIt’ll then prompt you for your access keys and default region name. This refers to where the server is being hosted. Enter “us-west-2” for the point cloud server and storage. Last, it’ll ask for a default output format. You can leave this blank.
AWS Access Key ID [None]: ACCESSKEYAWS Secret Access Key [None]: SECRETACCESSKEYDefault region name [None]: us-west-2Default output format [None]:
For more info, check the IAM CLI documentation. You’ll want to set up long-term credentials to ease access on your personal computers. Your IAM User should be given to you, but create your own access key.
https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-user.html
Uploading point clouds
S3 buckets are organized by project. You can upload items and edit names and locations with CMD Prompt or the IAM Console online.
Sign in to the IAM Console
Search and open the S3 page
Open “potree-test2” under “General Purpose Buckets”
With AWS configured, enter the next line in your command prompt/terminal to upload a point cloud folder:
aws s3 cp path/to/pointcloudfolder s3://potree-test2/projectname/pointcloudfolder --recursive
Uploading the octree.bin file may take some time. It should return the following:
Quick Ref for Connecting, Uploading, and Downloading with EC2 and S3
Potree HTML Basics
To generate the Potree viewer, the HTML will reference scripts and stylesheets in the Potree folder. This folder is present within each Potree download folder and is already uploaded to the EC2 Instance.
Edit the HTML to position, rotate, and adjust generation of a point cloud as well as change viewer settings
View the folder of html templates to see how to add more point clouds, scenes, or viewers to one Potree page
Call the uploaded point cloud to the viewer using its s3 URL: In the “loadPointCloud” functon of a Potree template, load the scan into the viewer by replacing “project” and “pointcloud” accordingly. Alternatively, you can copy the complete URL directly from AWS…
Potree.loadPointCloud("https://potree-test2.s3.us-west-2.amazonaws.com/project/pointcloud/metadata.json", "Point Cloud", function (e) {
Sign in to the IAM Console
Search and open the S3 page
Open “potree-test2” under “General Purpose Buckets”
Click the project
Find the point cloud
Check the metadata file
Click “Copy URL” and paste into the first parameter of the loadPointCloud function
UCLA Pointcloud folder of HTML templates: Potree Templates
Uploading the HTML
HTML can be drag-and-dropped from your file explorer into the desired server folder with VSCode
The file can also be uploaded through AWS CLI. Navigate to the folder with the html file in the terminal and use this command:
scp -i ~/.ssh/potree-test.pem potree.html ubuntu@ec2-44-225-161-146.us-west-2.compute.amazonaws.com:~/potree/potree.htmlAlternatively, you can create the HTML directly in the instance using VS Code…
Using VS Code as an EC2 file editor
This is the easiest way to create and edit your Potree HTML files and see live updates on the website. Split your screen with the point cloud page.
Connecting to the server on VS Code
Ensure your potree-test.pem file is in the SHH folder
On the welcome page, under “Start”, click “Connect to…“
Click “Connect to Host” → “+ Add New SSH Host…”
Enter ssh -i ".ssh/potree-test.pem" ubuntu@ec2-44-225-161-146.us-west-2.compute.amazonaws.com
Select your config file to update
Once the host is added, click “Connect to…” → “Connect to Host” → “ec2-44-225-161-146.us-west-2.compute.amazonaws.com”
Click “File Explorer” or CTRL+SHIFT+E to open the File Explorer
Click “Open Folder” and open /home/ubuntu/potree/
Now you can open the file explorer, open or create your file in a project folder, and refresh the point cloud page to see your code changes. You can also rename, organize, or remove files from the instance. Next time you open VS Code, you can find the Potree folder under “Recent”.
Ensure your HTML references the correct path to the folders “build” and “libs”.
Make sure the library scripts referenced to generate the viewer are located correctly in the path. Navigating the directory:
../libs/potree.js Two dots direct a reference to the parent folder, one level up. This indicates that the libs folder is outside of the html’s folder. It moves upwards into the parent directory before opening the libs folder. If the html file shares the same location as libs, remove these dots.
Customizing Potree Viewers: Camera, Annotations, Etc.
Resources
GitHub - potree/potree: WebGL point cloud viewer for large datasets
Potree’s github page provides a thorough rundown of downloads, examples, features, and updates. This will be handy when you want to know how to code any new features- simply refer to the HTML of the examples.
Another resource for exploring potential uses of Potree is the UCSD directory: pointcloud.ucsd.edu.
To save an HTML file, open your chosen Potree viewer and press CTRL+S.
Changing the Potree Camera
viewer.scene.view.position.set(0, -1000, 0);
viewer.scene.view.lookAt(0, 0, 0);
Potree.loadPointCloud("https://potree-test2.s3.us-west-2.amazonaws.com/VHM/rotated/metadata.json", "Pointcloud Title", function (e) {
e.pointcloud.rotation.set(Math.PI * 0, Math.PI * 0, Math.PI * 0);
e.pointcloud.position.set(-250, 0, -100);When adjusting how the point cloud loads in to the viewer, you can change the point cloud position and rotation as well as camera position and target. For big orientation changes, consider re-orienting in Cloud Compare.
with sidebar:
Open the sidebar and expand the “Scene Panel”
Click “Camera”
Orient the point cloud and copy the coordinates into viewer.scene.view.position.set() and viewer.scene.view.lookAt() in the HTML
with console:
Open Developer Tools in your browser (CTRL+SHIFT+I on Chrome)
Left click to rotate the camera around the rotation center and enter viewer.scene.view.position in the console to return the new camera’s coordinates.
You can also right click and drag to move the pointcloud in the viewer. Be sure to update viewer.scene.view.lookAt(0, 0, 0); in the html file to adjust the camera’s target as needed.
UCLA Pointcloud folder of HTML templates: Potree Templates
Potree Features
You can format and stylize Potree viewers to best suit any project. To see current live HTML templates and references, visit https://www.pointcloud.ucla.edu/templates/.
Annotated Templates
View live with the link, CTRL+S on the webpage or open in the instance for the HTML
Include your own new templates or features to grow our showcase of accessible and effective 3D Data with Potree.
Scripting