Skip to content

README.md

Latest commit

 

History

History
186 lines (117 loc) · 7.21 KB

README.md

File metadata and controls

186 lines (117 loc) · 7.21 KB

Slicer URI Bridge

Python 3.11+ License: MIT Platform: Windows | macOS | Linux

Installation · Security Model · Changelog

Slicer URI Bridge helps open 3D model links from websites in Bambu Studio, including sites that do not provide a native Bambu Studio button or where that integration is not available.

demo.mp4

It registers URI handlers for other slicers (PrusaSlicer, OrcaSlicer, Cura, and Creality Print) and routes those links through a small Python bridge that downloads the model safely and opens it in Bambu Studio.

Installation

Windows (automatic)

Open PowerShell and run:

powershell -ExecutionPolicy Bypass -c "iwr -useb https://raw.githubusercontent.com/mbv06/slicer-uri-bridge/main/install-windows.ps1 | iex"

The installer creates a private virtual environment in %LOCALAPPDATA%\slicer-uri-bridge, installs or upgrades the package there, adds the Scripts directory to the user PATH, initializes config if needed, and registers URI handlers.

After installation, open a new terminal window if the command is not found, then test the registered handler by opening a known Benchy model URI:

slicer-uri-bridge test

macOS (automatic)

Run the installer:

curl -fsSL https://raw.githubusercontent.com/mbv06/slicer-uri-bridge/main/install-macos.sh | bash && export PATH="$HOME/.local/bin:$PATH"

The installer creates a private virtual environment in ~/.local/share/slicer-uri-bridge, installs or upgrades the package there, creates ~/.local/bin/slicer-uri-bridge, initializes config if needed, and registers URI handlers.

After installation, open a new Terminal window if the command is not found, then test the registered handler by opening a known Benchy model URI:

slicer-uri-bridge test

Manual

First, install Python 3.11 or newer on the target system:

  • Windows: install Python from python.org and enable the Add python.exe to PATH option.
  • macOS: install Python from python.org and run the bundled Install Certificates.command, or install Python with Homebrew.
  • Linux: install Python 3.11+ from your distribution package manager.

Then install the package from GitHub:

python -m pip install https://github.com/mbv06/slicer-uri-bridge/archive/refs/heads/main.zip

Installation only installs the CLI and Python package. It does not register URI handlers automatically.

First Run

Run the CLI without arguments for interactive setup:

slicer-uri-bridge

This will initialize the config and open the interactive manager, where you can choose which URI schemes to register or unregister. Use slicer-uri-bridge -h to see all available commands.

Automatic mode is conservative:

  • bambustudioopen is always selected, so Bambu-style links are routed through this bridge (to support not only 3mf models).
  • cura, crealityprintlink, prusaslicer, and orcaslicer are registered only when the system currently has no effective handler for that scheme.

To manage an existing handler, specify the scheme explicitly or select it in interactive registration:

slicer-uri-bridge manager

This command shows the current status and lets you choose which schemes to manage:

slicer-uri-bridge status

Uninstall

Unregister all URI handlers managed by this package:

slicer-uri-bridge unregister --auto

You can also delete the config and log files manually. Find their location with:

slicer-uri-bridge config-path

Then remove the package:

pip uninstall slicer-uri-bridge

How It Works

When a slicer URI link is clicked in a browser, the OS routes it to the registered handler, which launches:

python -m slicer_uri_bridge.handler "<incoming-uri>"

The bridge reads the user config, validates the incoming URI, downloads the model to a temporary or configured folder, checks the file type, and opens the result in Bambu Studio.

The config file and log files are stored in:

  • Linux/macOS: ~/.config/slicer-uri-bridge/
  • Windows: %APPDATA%\slicer-uri-bridge\

If XDG_CONFIG_HOME is set on Linux or macOS, it is used instead of ~/.config. The config includes allowed download hosts, allowed model file extensions, optional download folder, and platform-specific Bambu Studio paths. Print the active path with slicer-uri-bridge config-path.

Security Model

The bridge validates downloads before opening them:

  • only HTTPS URLs are allowed unless allow_plain_http = true
  • URLs with embedded credentials are rejected
  • resolved hosts must not point to local/private/reserved addresses
  • redirect targets are revalidated
  • downloaded files must use an allowed model extension
  • empty files and obvious executable formats are refused
  • 3MF files are checked for embedded post-processing scripts (scripts that can run after slicing)

By default, downloads are accepted from any host. To restrict downloads to specific hosts, set allow_any_original_host = false in the config and use the allowed_hosts list (the default config includes CDNs for Printables, Thingiverse, and Creality).

All available options are described in the bundled default_config.toml template and copied into the generated config.toml file.

Troubleshooting

The bridge writes log files next to the config file. To find their location:

slicer-uri-bridge config-path

Log files in that directory record each handler invocation and can help diagnose download failures, URI parsing issues, or slicer launch problems.

If the slicer-uri-bridge command is not found after installation, make sure the Python scripts directory is on your PATH. On macOS with the automatic installer, open a new Terminal window. On Windows, ensure the Add python.exe to PATH option was enabled during Python installation, or use the automatic installer above. As a fallback, you can always run python -m slicer_uri_bridge instead of slicer-uri-bridge.

If URI links do not open after registration, verify the current handler status:

slicer-uri-bridge status

Then try re-registering with slicer-uri-bridge register and select the scheme you want to replace.

To verify the default bambustudioopen handler, run:

slicer-uri-bridge test

Known Limitations

On Windows, OrcaSlicer re-registers the orcaslicer:// URI scheme to itself on every launch. Registering this scheme to the bridge only makes sense if you do not use OrcaSlicer.

Supported URI Formats

Supported URI formats include:

bambustudioopen://https%3A%2F%2F...
cura://open?file=https%3A%2F%2F...
crealityprintlink://open?file=https%3A%2F%2F...
prusaslicer://open?file=https%3A%2F%2F...
orcaslicer://open?file=https%3A%2F%2F...