BlueGit

timfa posprint

Use effective ESC/POS printable width for preview and image clamping.

Derive printable dots from Font A columns (384/576) instead of physical
paper DPI so preview and raster width match common receipt printers.

Co-authored-by: Cursor <cursoragent@cursor.com>

timfa Tim Falken · pushed by timfa

Authored 2026-07-16 · 4 months ago

Hash
aca7836ebc78620da7fc8c1e75350e160a740b99
Parent
f3aa8c2e
3 files changed +20 −10
docs/FILE-FORMAT.md +5 −5
@@ -41,15 +41,15 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
41 41 | `title` | `string?` | `null` | Display name in app title / recent files |
42 42 | `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
43 43 | `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
44 | `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
44 | `chars_per_line` | `number?` | derived | Override character width for preview/print width model; derived from mm if omitted |
45 45 | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
46 46
47 47 ### Page width derivation
48 48
49 | `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
50 |-----------------|------------------------|-----------------------------------|
51 | 58 | 384 | 32 |
52 | 80 | 576 | 48 |
49 | `page_width_mm` | Effective printable dots (Font A) | Default `chars_per_line` (Font A) |
50 |-----------------|----------------------------------|-----------------------------------|
51 | 53-58 | 384 | 32 |
52 | >58 | 576 | 48 |
53 53
54 54 ---
55 55
@@ -41,15 +41,15 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
41| `title` | `string?` | `null` | Display name in app title / recent files |
41| `title` | `string?` | `null` | Display name in app title / recent files |
42| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
42| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
43| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
43| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
44| `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
44| `chars_per_line` | `number?` | derived | Override character width for preview/print width model; derived from mm if omitted |
45| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
45| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
46
46
47### Page width derivation
47### Page width derivation
48
48
49| `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
49| `page_width_mm` | Effective printable dots (Font A) | Default `chars_per_line` (Font A) |
50|-----------------|------------------------|-----------------------------------|
50|-----------------|----------------------------------|-----------------------------------|
51| 58 | 384 | 32 |
51| 53-58 | 384 | 32 |
52| 80 | 576 | 48 |
52| >58 | 576 | 48 |
53
53
54---
54---
55
55
docs/PRINTING.md +3 −3
@@ -147,7 +147,7 @@ Status polling (paper out, cover open) is **not** implemented.
147 147
148 148 1. Resolve path relative to `.pos` file directory (or absolute path).
149 149 2. Decode with `image` crate.
150 3. Convert to luma8, resize to target width (%, dots, or full printable width).
150 3. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width.
151 151 4. Threshold to 1-bit raster.
152 152 5. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
153 153
@@ -159,8 +159,8 @@ Preview shows `[image: path]` only — no bitmap preview yet.
159 159
160 160 | `preview_mode` | Preview | Print |
161 161 |----------------|---------|-------|
162 | `autoscale` | Scales to panel width | Full paper width from metadata |
163 | `fixed` | Scaled by mm ratio | Full paper width |
162 | `autoscale` | Scales to panel width | Full effective print width |
163 | `fixed` | Scaled by dot ratio | Full effective print width |
164 164
165 165 ---
166 166
@@ -147,7 +147,7 @@ Status polling (paper out, cover open) is **not** implemented.
147
147
1481. Resolve path relative to `.pos` file directory (or absolute path).
1481. Resolve path relative to `.pos` file directory (or absolute path).
1492. Decode with `image` crate.
1492. Decode with `image` crate.
1503. Convert to luma8, resize to target width (%, dots, or full printable width).
1503. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width.
1514. Threshold to 1-bit raster.
1514. Threshold to 1-bit raster.
1525. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
1525. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
153
153
@@ -159,8 +159,8 @@ Preview shows `[image: path]` only — no bitmap preview yet.
159
159
160| `preview_mode` | Preview | Print |
160| `preview_mode` | Preview | Print |
161|----------------|---------|-------|
161|----------------|---------|-------|
162| `autoscale` | Scales to panel width | Full paper width from metadata |
162| `autoscale` | Scales to panel width | Full effective print width |
163| `fixed` | Scaled by mm ratio | Full paper width |
163| `fixed` | Scaled by dot ratio | Full effective print width |
164
164
165---
165---
166
166
src/io/mod.rs +12 −2
@@ -64,8 +64,10 @@ impl PosFile {
64 64
65 65 impl PosMetadata {
66 66 pub fn printable_dots(&self) -> u16 {
67 // 203 DPI is common for thermal printers
68 (self.page_width_mm / 25.4 * 203.0).round() as u16
67 // Most ESC/POS printers effectively expose Font A widths of:
68 // 32 columns -> 384 dots, 48 columns -> 576 dots.
69 // Keep image/raster width aligned with the text column model.
70 (self.chars_per_line().max(1) * 12) as u16
69 71 }
70 72
71 73 pub fn chars_per_line(&self) -> u32 {
@@ -130,8 +132,16 @@ mod tests {
130 132 ..Default::default()
131 133 };
132 134 assert_eq!(narrow.chars_per_line(), 32);
135 assert_eq!(narrow.printable_dots(), 384);
136 let very_narrow = PosMetadata {
137 page_width_mm: 53.0,
138 ..Default::default()
139 };
140 assert_eq!(very_narrow.chars_per_line(), 32);
141 assert_eq!(very_narrow.printable_dots(), 384);
133 142 let wide = PosMetadata::default();
134 143 assert_eq!(wide.chars_per_line(), 48);
144 assert_eq!(wide.printable_dots(), 576);
135 145 }
136 146
137 147 #[test]
@@ -64,8 +64,10 @@ impl PosFile {
64
64
65impl PosMetadata {
65impl PosMetadata {
66 pub fn printable_dots(&self) -> u16 {
66 pub fn printable_dots(&self) -> u16 {
67 // 203 DPI is common for thermal printers
67 // Most ESC/POS printers effectively expose Font A widths of:
68 (self.page_width_mm / 25.4 * 203.0).round() as u16
68 // 32 columns -> 384 dots, 48 columns -> 576 dots.
69 // Keep image/raster width aligned with the text column model.
70 (self.chars_per_line().max(1) * 12) as u16
69 }
71 }
70
72
71 pub fn chars_per_line(&self) -> u32 {
73 pub fn chars_per_line(&self) -> u32 {
@@ -130,8 +132,16 @@ mod tests {
130 ..Default::default()
132 ..Default::default()
131 };
133 };
132 assert_eq!(narrow.chars_per_line(), 32);
134 assert_eq!(narrow.chars_per_line(), 32);
135 assert_eq!(narrow.printable_dots(), 384);
136 let very_narrow = PosMetadata {
137 page_width_mm: 53.0,
138 ..Default::default()
139 };
140 assert_eq!(very_narrow.chars_per_line(), 32);
141 assert_eq!(very_narrow.printable_dots(), 384);
133 let wide = PosMetadata::default();
142 let wide = PosMetadata::default();
134 assert_eq!(wide.chars_per_line(), 48);
143 assert_eq!(wide.chars_per_line(), 48);
144 assert_eq!(wide.printable_dots(), 576);
135 }
145 }
136
146
137 #[test]
147 #[test]