Skip to content

About

Local-first point-cloud alignment and precision cropping tool

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

PointFrame icon PointFrame

PointFrame is a local-first point-cloud alignment and precision cropping tool. Inspect a cloud in 3D, align its crop frame, select a region with a polygon and a height range, review the selection in 3D, and export full-resolution PLY files. The source file is never modified, and all processing happens on your computer.

PointFrame 3D Inspect

Screenshot from an earlier PointFrame version. The interface was redesigned in 0.2.0.

Features

  • Inspect first: clouds open in a 3D view with Turntable and Free orbit, zoom toward the cursor, depth-correct rendering, and a pivot set by double click on the front-most visible point.
  • Guided cropping: Start Crop → Crop preparation → Draw Selection, in the 2D Top view of the current crop frame.
  • Interactive alignment: rotate the cloud freely in 3D and apply the view as the new Top; Reset to Auto and Cancel keep the crop frame safe.
  • Polygon and height selection: editable outline, local height range, Keep Inside / Keep Outside, and live preview counts.
  • 3D selection review: refine the height range and preview the selected or excluded points in 3D, then export directly from there.
  • Full-resolution export: raw and aligned PLY files in versioned export folders that never overwrite silently.
  • Display options: configurable point size, on-demand camera controls, and a collapsible sidebar.
  • About & Updates: the installed version and a manual check for new releases on GitHub.

Supported formats

PointFrame supports binary PLY files (little- or big-endian) with vertex properties:

  • x, y, and z required.
  • red, green, and blue optional.
  • nx, ny, and nz optional.

ASCII PLY, LAS and LAZ files are not supported. Points without RGB values use a neutral preview color. Exports preserve source properties. Aligned exports rotate normals when present and do not create them when absent.

Installation

Ubuntu 26.04 package

Download pointframe_0.2.0_amd64.deb from GitHub Releases and install it with:

sudo apt install ./pointframe_0.2.0_amd64.deb

The package installs a self-contained application in /opt/pointframe, the pointframe command and a desktop launcher; Python is not required. Installing it over an earlier version upgrades it in place. Launch PointFrame from the application menu or with:

pointframe

Source installation

PointFrame requires Python 3.12 or newer. From the project directory, install the desktop application and its GTK based PyWebView shell:

python -m pip install -e '.[desktop]'

For browser-only use:

python -m pip install -e .

Native open and export dialogs use Zenity on Linux. If PyWebView or its GTK renderer is unavailable, PointFrame opens the local interface in the default browser.

Building the package

With PyInstaller and the desktop dependencies installed in a build environment:

./packaging/build-standalone.sh   # dist/PointFrame/PointFrame
./packaging/build-deb.sh          # dist/pointframe_<version>_amd64.deb

The package version is taken from src/pointframe/__init__.py.

Usage

Open the start screen and choose a PLY file:

pointframe

Open a specific file directly:

pointframe /path/to/cloud.ply
python -m pointframe /path/to/cloud.ply

Use Open… in the viewer to switch to another PLY without restarting PointFrame. Cancelling the native picker leaves the current cloud unchanged.

Useful options:

pointframe /path/to/cloud.ply --output-dir /path/to/exports
pointframe --preview-points 500000
pointframe --no-open --host 127.0.0.1 --port 8765

The viewer shows a preview of up to --preview-points points (1,500,000 by default). Exports always use every point of the source file.

Interface

  • Header: the loaded file, its point count and size, the processing status, and Info (Help, and About & Updates).
  • Toolbar: persistent tools on the left (Open…, 3D Inspect, Fit View, Display, and in 3D the orbit mode and Camera); on the right the one primary action for the current step (Start Crop, Draw Selection, Apply as Top View or Crop & Export…), its secondary actions, and Sidebar to hide the sidebar and enlarge the viewport.
  • Sidebar: only the controls for the current step.
  • Status bar: the current step, a short hint, messages and export progress.

3D Inspect controls

  • Left drag: orbit around the pivot (the cloud follows the mouse).
  • Right or middle drag: pan.
  • Mouse wheel: zoom toward the cursor (all views).
  • Double click: set the orbit pivot on the front-most visible point under the cursor; the view does not move.
  • Orbit mode: Turntable (default) rotates around the local vertical axis with a level horizon; Free orbit allows unrestricted rotation including roll.
  • Camera: shows the Azimuth, Elevation and Roll controls on the viewport. They are shown automatically while adjusting the alignment. The Diagnostics option shows the raw camera state.
  • Fit View: frames the visible points.

Display

Display → Point size sets how large preview points are drawn: Fine (1 px), Original (1.5 px, the default), Normal (2 px), Large (3 px) or Extra Large (4 px). Larger points make sparse areas easier to read when zoomed in. Point size affects rendering only: the preview density, the selection and the exported geometry are unchanged. The choice is kept while you work and is remembered between sessions where browser storage is available.

Crop/export workflow

PointFrame crop selection

Crop selection shown in the earlier interface.

  1. Open a binary PLY point cloud and wait for preview preparation. PointFrame opens in 3D Inspect with an oblique overview of the cloud (35° azimuth, 55° elevation in the local crop frame), fitted to the window.

  2. Select Start Crop to switch to the Top view of the current crop frame (normally the automatic alignment; a manually adjusted or loaded frame is kept). In this preparation step, dragging pans and clicks do not add vertices. If the automatic up direction could not be determined, a note suggests checking it. Technical details shows the alignment metadata.

  3. Optionally select Adjust Alignment to correct the crop frame interactively. The cloud is shown in 3D, starting from the current Top view, and dragging rotates it freely; the Roll control turns it within the view. Panning and zooming only move the camera. Apply as Top View makes the current view the new Top (with a confirmation if an outline exists), Reset to Auto returns the candidate to the automatic orientation, and Cancel leaves the crop frame unchanged. Top / Front / Side checks, Flip Top and Rotate Top 180° are under Advanced alignment tools.

  4. Select Draw Selection and click to create the selection outline. Drag vertices to move them, click or drag an edge to insert one, and right click a vertex to delete it. An existing outline is resumed, never cleared.

  5. Set the minimum and maximum local height and choose whether to keep points inside or outside the crop volume.

  6. Select 3D Inspect at any time to review the selection in 3D. With a valid outline, the 3D review shows the height range, Keep Inside/Outside, the All / Selected / Excluded preview and Crop & Export…, sharing the same settings as the Top view. Return to Crop goes back to the 2D editor with everything unchanged.

  7. Optionally select Save definition (and later Reload definition under Saved crop definition).

  8. Select Crop & Export… in Draw Selection or in the 3D review. It is available once the outline has at least three vertices and the height range is valid. Without --output-dir, choose a destination using the native folder picker.

Each versioned export directory contains:

  • crop_raw.ply
  • crop_aligned.ply
  • crop_definition.json
  • crop_report.json

Exports use crop_001, crop_002, and later available numbers. Replacing the latest export requires an explicit confirmation.

About & Updates

Info → About & Updates shows the installed version, the license, and links to the repository and the release history.

PointFrame works fully offline. It contacts the internet only when you select Check for Updates: the local PointFrame process then makes one HTTPS request to the official GitHub Releases API (https://api.github.com/repos/Maysker/PointFrame/releases/latest) and compares the latest stable release with the installed version. No files, paths, point-cloud data or crop settings are sent. PointFrame never downloads or installs updates itself; a newer release is offered as a link to its GitHub release page, where you can download the new package.

Workspace behavior

PointFrame keeps previews and saved crop definitions outside the source PLY directory. The workspace for each source path is:

$XDG_DATA_HOME/pointframe/workspaces/<source-stem>-<path-hash>/

If XDG_DATA_HOME is unset, PointFrame uses:

~/.local/share/pointframe/workspaces/<source-stem>-<path-hash>/

Opening the same source path reuses its workspace. Source PLY files remain in place and are not uploaded or copied through the browser. User exports are stored in the selected export directory, separate from the application workspace.

Current status: 0.2.0

Version 0.2.0 redesigns the inspection and cropping experience: an inspect-first workflow, interactive 3D alignment, 3D selection review with export, a new desktop interface, configurable point size, and a manual update check. It supports the local Linux desktop workflow described above.

Known limitations

  • Linux only; the package targets Ubuntu 26.04 (amd64). Native dialogs need Zenity.
  • Binary PLY input only.
  • The viewer uses an orthographic projection.
  • Selection counts in the viewer are for the preview (up to 1,500,000 points by default); exports always process the full file.
  • Point size is a fixed choice; it does not adapt automatically to density or zoom.
  • Update checks are manual and do not install anything.

Roadmap

Planned future work, not supported in version 0.2.0:

  • LAS and LAZ input support.
  • Faster and more compact exports.
  • Adaptive point sizing.

Repository

https://github.com/Maysker/PointFrame

License

PointFrame is released under the MIT License.

About

Local-first point-cloud alignment and precision cropping tool

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages