RST — User Guide

This is the complete guide to RST — what it does, how to set it up, and how to build and share toolbar profiles. Written for Revit admins and users who want a clean, curated ribbon.

---

What Is RST

RST is a pyRevit extension that lets administrators build custom toolbar profiles from any installed Revit tool or add-in. Instead of digging through default tabs and third-party panels, users load a single profile and get a purpose-built ribbon with only the tools they need.

Admins detect available tools, arrange them into colored panels, add company branding, and export profiles as shareable JSON files. Users load a profile and get a clean ribbon that rebuilds automatically every time Revit starts.

---

Install

Dependencies

You need two things installed before adding RST:

• pyRevit 4.8+ — the extension framework that RST runs on
• Python 3.12 — required for the UI windows (pywebview)

Install Python 3.12 (Windows)

1. Open PowerShell and run: winget install 9NQ7512CXL7T
2. Run first-launch config: py install --configure
3. Install Python 3.12: py install 3.12
4. Install pywebview: py -3.12 -m pip install pywebview
5. Verify: py -3.12 --version should return Python 3.12.x

Add the Extension

1. Launch Revit
2. Go to the pyRevit tab → Extensions → Add Extension
3. Paste the repo URL: https://github.com/jedbjorn/RST
4. Reload pyRevit

The RST tab appears in the Revit ribbon.

---

How It Works

Architecture

RST runs two processes: one inside Revit (IronPython) for ribbon building and button scripts, and one outside (CPython 3.12 + pywebview) for the admin and user UIs. They communicate through temporary JSON files. No persistent services, no background processes.

On Revit Launch

When Revit starts, startup.py reads active_profile.json and rebuilds the ribbon:

1. Removes any existing RST tabs
2. Builds the branding panel (logo, always leftmost)
3. Creates colored panels with rounded-corner backgrounds
4. Adds tool buttons with PostCommand handlers
5. Adds small tool stacks (text-only grouped buttons)
6. Styles RST admin panels grey
7. Hides tabs configured in RSTify

The ribbon rebuilds from scratch every launch. Custom tabs don't persist natively in Revit — RST reconstructs them each time.

Profiler Flow (Admin)

1. Click Profiler — IronPython scans the ribbon and writes tool data to a temp JSON
2. The CPython UI launches. Admin detects tools, creates panels, picks colors, adds tools and stacks
3. Export — saves profile JSON to app/profiles/ plus a Desktop copy

Loader Flow (User)

1. Click Loader — IronPython collects Revit version and loaded add-ins, launches CPython UI
2. User browses profiles, checks add-in compatibility, configures tab visibility
3. Load Profile — writes active_profile.json, triggers pyRevit reload, ribbon rebuilds

Add-in Detection

RST scans the live Revit session using AdWindows.dll and categorises every tool it finds:

Status	Meaning
Native	Built-in Revit tab (Architecture, View, Manage, etc.) — always available
Loaded	Add-in tab detected in current session (DiRootsOne, pyRevit, Kinship, etc.)
Not Loaded	Required by profile but not found in this session

---

The RST Tab

The RST tab contains five tool panels, each with a rounded grey background.

Profiler

Build and edit toolbar profiles. The Profiler is the admin-facing tool where all profile creation happens.

• Detect scans every ribbon tab for installed tools
• Search and filter tools by name or source tab
• Create panels with custom colors (hex input + swatches) and opacity (10–100%)
• Add tools via checkbox, drag to reorder
• Create tool stacks — 2–3 small buttons stacked vertically
• A tool can only live in one place. Adding it to a stack removes it from standalone
• + Add URL for custom URL buttons (company wikis, SharePoint, Teams)
• Add Logo for company branding (48×48 recommended)
• Export saves to app/profiles/ and Desktop

Loader

Load and manage profiles. The Loader is the user-facing tool for switching between profiles.

• Shows Revit version (live from session) and profile cards
• Each card shows a tab preview and required add-in status
• RSTify tab toggles — choose which ribbon tabs to hide
• Load Profile triggers pyRevit reload and ribbon rebuild
• Unload or delete profiles (creates a blank tab if active profile is removed)
• Add Profile from Path to import shared profiles

RSTify

Toggle tab visibility on and off. Orange icon means tabs are hidden. Blue means all tabs are visible. Click to toggle. No configuration UI — reconfigure by reloading a profile.

Update

Downloads the latest version from GitHub (zip), preserves user data (profiles, branding, config), and reloads pyRevit automatically.

Reload

Triggers a pyRevit reload to apply changes.

---

Custom URL Tools

You can add buttons that open URLs directly from the Revit ribbon — company wikis, SharePoint sites, Teams channels, or any web resource.

1. In the Profiler, click + Add URL at the bottom of the tool list
2. Enter a name (e.g. "Company Wiki") and the URL
3. The tool appears tagged "Custom" — add it to any panel like a regular tool
4. In Revit, clicking the button opens the URL in your default browser

Custom tools persist across sessions in app/custom_tools.json. They survive Detect scans, profile exports, and profile imports. You can edit or delete them at any time.

---

RSTify — Tab Visibility

RSTify replaces pyRevit's MinifyUI with profile-aware tab hiding. Instead of a global show/hide, it remembers which tabs to hide per profile and applies them automatically on every load.

How It Works

1. Open the Profile Loader and select a profile
2. The RSTify: Hide These Tabs column shows all ribbon tabs with toggles
3. Core tabs (Modify, Manage, View, Annotate, Add-Ins) are locked — cannot be hidden
4. Source tabs (tabs containing tools used by your profile) are locked — hiding them would break tools
5. Everything else can be toggled off
6. Click Load Profile — hidden tab selections are saved with the profile
7. On every reload, configured tabs are hidden automatically

The RSTify Button

Icon Color	State	Click Action
Orange	Tabs are hidden	Show all tabs
Blue	All tabs visible	Re-hide configured tabs

Previous hidden tab selections are remembered when you reopen the Loader. Tabs you hid last time are pre-toggled.

MinifyUI

RST automatically deletes pyRevit's MinifyUI smartbutton folder when a profile is loaded, to avoid conflicts. To restore MinifyUI after removing RST: unload the RST profile (creates a blank tab), then reinstall pyRevit.

---

Branding

Every profile tab includes a branding panel as the leftmost element. By default it shows the RST logo. To use your company logo:

1. In the Profiler, click Add Logo
2. Upload your image (48×48 recommended — resized automatically)
3. The logo persists across sessions and updates at icons/branding.png

The branding panel is not stored in the profile JSON — it's injected at runtime so each install can have its own logo.

---

Panel Styling

Colors

The Profiler includes two rows of color swatches: 8 built-in presets (Blue, Green, Purple, Amber, Red, Cyan, Orange, Lime) and 8 custom slots that start blank. Click a swatch to select it, type a hex code, and click the checkmark to save. Custom swatches persist across sessions in app/panel_colors.json.

Opacity

A per-profile slider controls panel background opacity from 10% to 100%. Applied to all panels in the profile.

Rounded Corners

Panel backgrounds use WPF DrawingBrush with RectangleGeometry for rounded corners. RST admin panels get a light grey background, applied after pyRevit finishes loading.

Tool Name Display

Long tool names are auto-split at the first space for compact two-line display on the ribbon.

Finding Colors

The Profiler includes a link to imagecolorpicker.com — upload a logo or brand guide and click any pixel to grab the hex code.

---

Profile JSON

Profiles are self-contained JSON files. They can be shared via email, OneDrive, Slack, or any file transfer. Each profile includes:

Field	Purpose
profile	Profile name
tab	Ribbon tab name
min_version	Minimum Revit version
exportDate	When the profile was exported
panelOpacity	Background opacity (10–100)
requiredAddins	Add-ins the profile depends on
hideRules	Tabs to hide via RSTify
stacks	Tool stack definitions (2–3 tools each)
panels	Panel definitions with tools, colors, and layout

The branding panel is not included in the JSON — it's injected at runtime from the local install.

---

Configuration

Add-in Lookup

The file lookup/addin_lookup.json maps ribbon tab names to .addin filenames. This is the single source of truth read by both UIs. Add entries for firm-specific add-ins — changes take effect on next Profiler or Loader open.

Protected Add-ins & Exempt Paths

The file lookup/config.json defines two lists:

• protected_addins — add-in files RST will never touch (e.g. pyRevit.addin, Dynamo.addin)
• exempt_paths — entire directories RST will never modify. Supports environment variables.

Both files are preserved across updates.

---

Known Limitations

Limitation	Detail
pyRevit script tools	Can be detected and placed but may not execute via PostCommand
Some OOTB tools	Dropdown/list button CommandIds are filtered out automatically
Locked files on update	Icons loaded by Revit are skipped during update, overwritten on next restart
Tab persistence	Custom tabs don't survive Revit restart — startup.py rebuilds every launch
Hidden tabs break tools	Tools from hidden tabs may not execute. RSTify protects source tabs, but manually hiding via MinifyUI can break things
MinifyUI deleted	RST removes MinifyUI smartbutton folder on profile load. Reinstall pyRevit to restore it
Add-in disabling	Feature deferred — code exists but is not active

---

Tech Stack

Component	Role
pyRevit	Extension framework, ribbon buttons, startup hooks
IronPython	Revit-side scripts — ribbon scanning, building, panel styling, reload UI
CPython 3.12	UI windows via pywebview
AdWindows.dll	Ribbon manipulation — scan tools, build panels, detect add-ins, set colors
WPF	ImageBrush for branding, DrawingBrush for rounded corners, ToolWindow for reload messages
pywebview	HTML-based UI windows for Profiler and Loader

---

Part of the Emergence Project. Built by the Design/OS shell team.