Preset Format

Technical specification for MouseMaster preset files.

File Format

Presets are stored as JSON files with UTF-8 encoding.

Schema

{
  "id": "string (required)",
  "name": "string (required)",
  "version": "string (required)",
  "mouseId": "string (required)",
  "author": "string (optional)",
  "description": "string (optional)",
  "mappings": {
    "button_id": {
      "action": "action_id",
      "parameters": {}
    }
  },
  "contextMappings": {
    "ModuleName": {
      "button_id": {
        "action": "action_id",
        "parameters": {}
      }
    }
  }
}

Required Fields

id

Unique identifier for the preset.

Type: string
Format: lowercase letters, numbers, underscores
Example: "my_workflow_preset"

name

Human-readable display name.

Type: string
Example: "My Workflow Preset"

version

Preset format version for compatibility.

Type: string
Current version: "1.0"

mouseId

Target mouse profile identifier.

Type: string
Must match an existing mouse profile ID
Example: "logitech_mx_master_3s"

Optional Fields

author

Creator of the preset.

Type: string
Example: "Your Name"

description

Brief description of the preset’s purpose.

Type: string
Example: "Optimized for segmentation workflows"

mappings

Default button-to-action mappings.

Type: object
Keys: Button IDs (from mouse profile)
Values: Mapping objects

contextMappings

Module-specific binding overrides.

Type: object
Keys: Slicer module names (case-sensitive)
Values: Objects with button-to-mapping pairs

Mapping Object

Defines what action a button triggers:

{
  "action": "action_id",
  "parameters": {
    "key": "value"
  }
}

action

Action identifier to execute.

Type: string
Required: yes
Example: "edit_undo"

parameters

Additional parameters for the action.

Type: object
Required: no
Content depends on action type

Button IDs

Standard button identifiers:

ID	Description
`left`	Left click (usually not remappable)
`right`	Right click (usually not remappable)
`middle`	Middle click / scroll wheel click
`back`	Back button (thumb area)
`forward`	Forward button (thumb area)
`thumb`	Additional thumb button

Custom button IDs may be defined in mouse profiles.

Module Names

Common Slicer module names for context mappings:

SegmentEditor
Markups
VolumeRendering
Models
Transforms
Data
Volumes

Module names are case-sensitive and must match exactly.

Complete Example

{
  "id": "segmentation_workflow",
  "name": "Segmentation Workflow",
  "version": "1.0",
  "mouseId": "logitech_mx_master_3s",
  "author": "Ben Zwick",
  "description": "Optimized button layout for segmentation tasks",
  "mappings": {
    "back": {
      "action": "edit_undo"
    },
    "forward": {
      "action": "edit_redo"
    },
    "middle": {
      "action": "view_reset_3d"
    },
    "thumb": {
      "action": "view_toggle_crosshair"
    }
  },
  "contextMappings": {
    "SegmentEditor": {
      "back": {
        "action": "segment_previous"
      },
      "forward": {
        "action": "segment_next"
      },
      "thumb": {
        "action": "segment_editor_toggle_effect"
      }
    },
    "Markups": {
      "back": {
        "action": "markups_delete_point"
      },
      "forward": {
        "action": "markups_place_fiducial"
      }
    }
  }
}

Validation

Presets are validated on load. Validation checks:

Required fields present
mouseId references existing profile
Button IDs exist in the referenced mouse profile
Action IDs are registered
JSON syntax is valid

Python Validation

import json

with open("preset.json") as f:
    data = json.load(f)

required = ["id", "name", "version", "mouseId"]
for field in required:
    assert field in data, f"Missing required field: {field}"

print("Preset structure valid!")

File Locations

Built-in presets

<Extension>/presets/builtin/

User presets

# Windows
%LOCALAPPDATA%/NA-MIC/Slicer X.X-YYYY-MM-DD/MouseMaster/presets/

# macOS
~/Library/Application Support/NA-MIC/Slicer X.X-YYYY-MM-DD/MouseMaster/presets/

# Linux
~/.config/NA-MIC/Slicer X.X-YYYY-MM-DD/MouseMaster/presets/

Migration

When the preset format version changes, MouseMaster will automatically migrate older presets. The original file is preserved with a .bak extension.