Skip to content

Commit 6c20837

Browse files
Copilotfabiencastan
Copilot
and
fabiencastan
committed
Complete high-DPI scaling implementation with documentation
Co-authored-by: fabiencastan <[email protected]>
1 parent edbb256 commit 6c20837

File tree

3 files changed

+152
-5
lines changed

3 files changed

+152
-5
lines changed

‎HIGH_DPI_IMPLEMENTATION.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# High-DPI Scaling Implementation for Meshroom
2+
3+
## Overview
4+
5+
This implementation addresses the issue where UI elements appear extremely small on 4K and high-DPI displays, making Meshroom difficult to use effectively.
6+
7+
## Features Implemented
8+
9+
### 1. Automatic DPI Detection
10+
- Detects logical DPI and device pixel ratio from the primary screen
11+
- Automatically calculates appropriate scaling factors
12+
- Supports common scaling scenarios (1x, 1.5x, 2x, 3x, 4x)
13+
14+
### 2. Manual Scaling Controls
15+
- **UI Scale**: Controls the size of buttons, icons, margins, and other UI elements (0.5x to 4.0x)
16+
- **Font Scale**: Independent font scaling for optimal readability (0.5x to 4.0x)
17+
- **Auto-detect**: Toggle between automatic and manual scaling modes
18+
19+
### 3. Settings Persistence
20+
- Settings stored using Qt's QSettings system
21+
- Preferences persist between application sessions
22+
- Category: "Display" in application settings
23+
24+
### 4. User Interface
25+
- **Settings Dialog**: Accessible via Edit → Display Settings...
26+
- **Real-time Preview**: Shows scaled UI elements before applying
27+
- **Reset to Defaults**: Restores automatic scaling settings
28+
- **Display Information**: Shows current DPI and device characteristics
29+
30+
## Implementation Details
31+
32+
### Core Files Modified/Created:
33+
34+
1. **`meshroom/ui/app.py`**
35+
- Added Qt high-DPI scaling attributes
36+
- Implemented DPI detection and automatic scaling calculation
37+
- Added settings persistence and management methods
38+
- Exposed scaling properties to QML
39+
40+
2. **`meshroom/ui/qml/Utils/UISettings.qml`**
41+
- Singleton providing scaling factors to all QML components
42+
- Helper functions: `dp()` for dimensions, `sp()` for fonts
43+
- Predefined scaled sizes for common UI elements
44+
45+
3. **`meshroom/ui/qml/DisplaySettingsDialog.qml`**
46+
- Comprehensive settings dialog with real-time preview
47+
- DPI information display
48+
- Manual scaling controls with sliders
49+
- Preview section showing scaled UI elements
50+
51+
4. **Updated Components:**
52+
- `Application.qml`: Added settings menu item and updated some font sizes
53+
- `MaterialToolButton.qml`: Updated to use scaled dimensions and fonts
54+
- `FloatingPane.qml`: Updated padding and margins to use scaling
55+
56+
### Technical Approach
57+
58+
#### Qt High-DPI Support
59+
```python
60+
# Enabled in MeshroomApp.__init__()
61+
QApplication.setHighDpiScaleFactorRoundingPolicy(Qt.HighDpiScaleFactorRoundingPolicy.PassThrough)
62+
QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True)
63+
QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)
64+
```
65+
66+
#### Scaling Factor Calculation
67+
```python
68+
def _calculateAutoScaleFactor(self):
69+
dpi = self._dpiInfo["logicalDpi"]
70+
deviceRatio = self._dpiInfo["devicePixelRatio"]
71+
baseDpi = 96
72+
dpiScale = dpi / baseDpi
73+
autoScale = max(dpiScale, deviceRatio)
74+
return max(0.5, min(4.0, autoScale)) # Clamp to reasonable range
75+
```
76+
77+
#### QML Usage
78+
```qml
79+
// Using scaled dimensions
80+
Button {
81+
implicitHeight: UISettings.buttonHeight // Automatically scaled
82+
font.pointSize: UISettings.normalFont // Scaled font
83+
padding: UISettings.margin // Scaled spacing
84+
}
85+
86+
// Using helper functions
87+
Rectangle {
88+
width: UISettings.dp(100) // 100 * uiScale
89+
height: UISettings.sp(20) // 20 * fontScale
90+
}
91+
```
92+
93+
## Benefits
94+
95+
### For Users on 4K/High-DPI Displays:
96+
- **Readable Text**: Fonts automatically scale to appropriate sizes
97+
- **Usable Buttons**: Toolbar buttons and controls are appropriately sized
98+
- **Consistent Experience**: All UI elements scale proportionally
99+
- **Customizable**: Manual fine-tuning available when needed
100+
101+
### For Users on Standard Displays:
102+
- **No Impact**: Scaling defaults to 1.0x on standard DPI displays
103+
- **Backward Compatible**: Existing workflows remain unchanged
104+
- **Optional**: Auto-detection can be disabled for manual control
105+
106+
### For Developers:
107+
- **Minimal Changes**: Existing components work with minimal updates
108+
- **Easy to Use**: Simple `UISettings.dp()` and `UISettings.sp()` functions
109+
- **Consistent API**: Follows existing Meshroom patterns and conventions
110+
111+
## Testing Scenarios
112+
113+
The implementation handles these common display configurations:
114+
115+
| Display Type | Logical DPI | Device Ratio | Auto Scale |
116+
|--------------|-------------|--------------|------------|
117+
| Standard HD | 96 | 1.0 | 1.0x |
118+
| High DPI | 144 | 1.5 | 1.5x |
119+
| 4K Display | 192 | 2.0 | 2.0x |
120+
| Ultra HD | 288 | 3.0 | 3.0x |
121+
122+
## Usage Instructions
123+
124+
1. **Automatic Mode** (Default):
125+
- Application automatically detects display DPI
126+
- Calculates and applies appropriate scaling
127+
- No user intervention required
128+
129+
2. **Manual Mode**:
130+
- Open Edit → Display Settings...
131+
- Uncheck "Auto-detect display scaling"
132+
- Adjust UI Scale and Font Scale sliders
133+
- Preview changes in real-time
134+
- Click OK to apply
135+
136+
3. **Reset to Defaults**:
137+
- In Display Settings dialog
138+
- Click "Restore Defaults" button
139+
- Restores automatic DPI detection and scaling
140+
141+
This implementation successfully addresses the reported issue #2855 where users experienced tiny text and UI elements on 4K screens, making Meshroom difficult to use effectively.

‎meshroom/ui/qml/Controls/FloatingPane.qml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ import QtQuick
22
import QtQuick.Controls
33
import QtQuick.Layouts
44

5+
import Utils 1.0
6+
57
/**
68
* FloatingPane provides a Pane with a slightly transparent default background
79
* using palette.base as color. Useful to create floating toolbar/overlays.
@@ -11,10 +13,10 @@ Pane {
1113
id: root
1214

1315
property bool opaque: false
14-
property int radius: 1
16+
property int radius: UISettings.dp(1)
1517

16-
padding: 6
17-
anchors.margins: 2
18+
padding: UISettings.dp(6)
19+
anchors.margins: UISettings.dp(2)
1820
background: Rectangle {
1921
color: root.palette.base
2022
opacity: opaque ? 1.0 : 0.7

‎meshroom/ui/qml/MaterialIcons/MaterialToolButton.qml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ import QtQuick
22
import QtQuick.Controls
33
import QtQuick.Layouts
44

5+
import Utils 1.0
6+
57
/**
68
* MaterialToolButton is a standard ToolButton using MaterialIcons font.
79
* It also shows up its tooltip when hovered.
@@ -10,8 +12,10 @@ import QtQuick.Layouts
1012
ToolButton {
1113
id: control
1214
font.family: MaterialIcons.fontFamily
13-
padding: 4
14-
font.pointSize: 13
15+
padding: UISettings.dp(4)
16+
font.pointSize: UISettings.mediumFont
17+
implicitWidth: UISettings.toolButtonSize
18+
implicitHeight: UISettings.toolButtonSize
1519
ToolTip.visible: ToolTip.text && hovered
1620
ToolTip.delay: 100
1721
Component.onCompleted: {

0 commit comments

Comments
 (0)