Synoptic Panel Toolbox

A command-line toolbox for managing Synoptic Panel maps in Power BI reports.

It currently supports:

• optimizing SVG maps containing embedded bitmap images (e.g. maps created with large static backgrounds on top of which you added vector shapes with Synoptic Designer)
• recovering SVG maps from Power BI .pbix files with Synoptic Panel v1 and v2 instances

Installation

Download the latest package from the releases page.

The application version is stored in the root VERSION file.

Security

Synoptic Panel Toolbox is a standalone command-line application that does not require installation or elevated permissions.

Windows code signing and Mac approval behavior are documented in the project Code signing policy.

Windows

Windows release binaries are signed with the SQLBI code signing certificate.

Mac

Mac release binaries are not currently signed or notarized.

Download the darwin_arm64 archive on Apple Silicon Macs and the darwin_amd64 archive on Intel Macs.

macOS may block the executable with a warning that the developer cannot be verified. Only bypass this warning if you downloaded the binary from the official project release page or built it yourself from this repository.

To allow only this downloaded executable from Terminal:

chmod +x ./synoptic-panel-toolbox
xattr -d com.apple.quarantine ./synoptic-panel-toolbox
./synoptic-panel-toolbox --help

Alternatively, try opening the executable once, then use:

• System Settings > Privacy & Security > Open Anyway for this specific file.

Do not disable Gatekeeper globally.

Usage

Synoptic Panel Toolbox is a command-line application that accepts commands and options as arguments. It also supports an interactive mode when run without arguments.

Just run the executable without arguments or show the available commands with the following command:

On Windows:

synoptic-panel-toolbox.exe --help

On Mac:

./synoptic-panel-toolbox --help

Optimize SVG Files

The optimize command accepts an optional -quality flag to control embedded image recompression, an optional -webp flag to try WebP conversion when it produces a smaller result, an optional -no-webp flag to disable WebP prompts, and an optional folder path as a positional argument. Higher values reduce compression.

On Windows:

synoptic-panel-toolbox.exe optimize -quality 90 -webp C:\path\to\svg-folder

On Mac:

./synoptic-panel-toolbox optimize -quality 90 -webp /path/to/svg-folder

In PowerShell, if you run it from the current folder, use .\synoptic-panel-toolbox.exe.

When launched by double-clicking the Windows executable, the tool keeps the console open at the end until you press Enter.

If you omit -quality, the script prompts for it. Leaving the prompt empty uses the default value 75.

If you omit -webp and cwebp is available in PATH, the script asks whether it should try converting embedded images to WebP when smaller. Use -no-webp to skip WebP conversion without prompting.

If you omit the folder argument, the script prompts for the SVG folder to process.

On Windows:

synoptic-panel-toolbox.exe optimize C:\path\to\svg-folder
synoptic-panel-toolbox.exe optimize -quality 90
synoptic-panel-toolbox.exe optimize

On Mac:

./synoptic-panel-toolbox optimize /path/to/svg-folder
./synoptic-panel-toolbox optimize -quality 90
./synoptic-panel-toolbox optimize

For compatibility with earlier releases, running synoptic-panel-toolbox [options] [folder] without a command still starts the optimizer.

The valid quality range is 1-100. The default value is 75, which matches the previous JPEG behavior and keeps strong PNG compression.

JPEG embedded images use the provided quality value directly. PNG embedded images use the same value in two ways:

• Below 75, the optimizer reduces PNG color precision to allow a real quality drop and stronger size reduction.
• From 75 upwards, PNG images remain lossless and the value only reduces the PNG compression level at higher settings.

When WebP conversion is enabled, the tool tries cwebp and keeps the WebP version only if it is smaller than the best JPEG/PNG result. This feature requires cwebp to be installed and available in PATH.

Before rewriting an SVG, the tool stores the original file inside the original subfolder of the selected root directory, preserving the relative directory structure.

Recover SVG Files from PBIX Reports

The recover command scans a folder for Power BI .pbix files and extracts Synoptic Panel v1 and v2 SVG maps.

On Windows:

synoptic-panel-toolbox.exe recover C:\path\to\pbix-folder

synoptic-panel-toolbox.exe recover --fetch-url-maps C:\path\to\pbix-folder

On Mac:

./synoptic-panel-toolbox recover /path/to/pbix-folder

./synoptic-panel-toolbox recover --fetch-url-maps /path/to/pbix-folder

The folder argument is optional. If omitted, recover scans the folder where the executable is saved.

For each .pbix file, the tool creates a recovery folder next to the report:

reports/
  Sales.pbix
  Sales_recovery/
    Sales__section1__Page_Name__visual2__map1__unnamed.svg
    recovery-summary.txt

recovery-summary.txt includes the processing status, Synoptic Panel instance counts, recovered file names, and URL download errors when present.

The --fetch-url-maps option downloads SVG maps referenced by URL. Use it only with trusted PBIX files or trusted networks.

Privacy

This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it.

The optional WebP conversion uses the local cwebp executable only when it is installed in PATH and the user enables WebP conversion.

The recovery command does not download URL-based maps unless --fetch-url-maps is explicitly enabled.

Uninstallation

Synoptic Panel Toolbox does not install background services, startup items, browser extensions, or system configuration.

To uninstall it, delete the downloaded synoptic-panel-toolbox or synoptic-panel-toolbox.exe executable and any release archive you downloaded.

Developer Notes

Versioning

Update the VERSION file when you want to publish a new release.

If you want to build the tool yourself or run it from source, you need to have Go installed on your system.

After cloning the repository, navigate to the project folder and run the following command to install dependencies:

go mod tidy

Run

You can run the tool directly from source without building an executable:

go run .

Run a command from source:

go run . optimize /path/to/svg-folder
go run . recover /path/to/pbix-folder

Build

You can build the executable with the following command for your platform. The output will be in the dist folder.

# Mac Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o dist/synoptic-panel-toolbox

# Mac Intel
GOOS=darwin GOARCH=amd64 go build -o dist/synoptic-panel-toolbox

# Linux
GOOS=linux GOARCH=amd64 go build -o dist/synoptic-panel-toolbox

# Windows
GOOS=windows GOARCH=amd64 go build -o dist/synoptic-panel-toolbox.exe

License

This project is licensed under the MIT License - see the LICENSE file for details.

About Synoptic Panel

Synoptic Panel is a custom visual for Microsoft Power BI that allows you to create interactive maps and diagrams with custom shapes and images. It is developed by OKVIZ and available on the Microsoft AppSource marketplace.

For more information, visit the Synoptic Panel product page.