@paperpic/vue 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,186 @@
1
+ ---
2
+ title: Saving the result
3
+ description: How PaperPic hands over the edited image, how to choose its format and size, how to upload it, and how the download button and its event work.
4
+ ---
5
+
6
+ # Saving the result
7
+
8
+ PaperPic never uploads or stores anything. When the user applies the edits, it hands the result to your code, and your app decides where it goes. This page covers what you receive and how to save it.
9
+
10
+ ## The `apply` event
11
+
12
+ Apply computes the result and fires [`apply`](../reference/events#apply) with:
13
+
14
+ | Field | Type | Description |
15
+ | ----------------- | -------- | --------------------------------- |
16
+ | `blob` | `Blob` | The edited image |
17
+ | `type` | `string` | Its format, such as `'image/png'` |
18
+ | `width`, `height` | `number` | Its size in pixels |
19
+
20
+ :::tabs key:framework
21
+ == JavaScript
22
+
23
+ ```ts
24
+ pic.on('apply', result => upload(result))
25
+ ```
26
+
27
+ == Vue
28
+
29
+ ```vue
30
+ <PaperPic src="/receipt.jpg" @apply="upload" />
31
+ ```
32
+
33
+ == React
34
+
35
+ ```tsx
36
+ <PaperPic src="/receipt.jpg" onApply={upload} />
37
+ ```
38
+
39
+ :::
40
+
41
+ After Apply, the result is the image on display, the history is empty, and the next edit starts from the result. [`reload()`](../reference/methods#reload) brings back the original `src`.
42
+
43
+ ## Upload it
44
+
45
+ Send the `blob` as a file in a form:
46
+
47
+ ```ts
48
+ async function upload({ blob, type }: { blob: Blob, type: string }) {
49
+ const body = new FormData()
50
+ body.append('image', blob, `document.${type.split('/')[1]}`)
51
+ const response = await fetch('/api/documents', { method: 'POST', body })
52
+ if (!response.ok) {
53
+ throw new Error(`The upload failed with status ${response.status}`)
54
+ }
55
+ }
56
+ ```
57
+
58
+ The viewer shows the result at once, whether or not it reaches your server, so tell the user when the upload fails.
59
+
60
+ ## Format and quality
61
+
62
+ Without options, the result keeps the format of the source: JPEG, PNG or WebP. A cleaned up document is PNG, because JPEG would add artifacts around its sharp edges. Any other source, such as a GIF, gives PNG.
63
+
64
+ [`output`](../reference/options#output) chooses the format, and its quality from 0 to 1 for JPEG and WebP, with 0.92 by default:
65
+
66
+ :::tabs key:framework
67
+ == JavaScript
68
+
69
+ ```ts
70
+ const pic = new PaperPic(container, {
71
+ src: '/receipt.jpg',
72
+ output: { type: 'image/webp', quality: 0.8 },
73
+ })
74
+ ```
75
+
76
+ == Vue
77
+
78
+ ```vue
79
+ <PaperPic src="/receipt.jpg" :output="{ type: 'image/webp', quality: 0.8 }" />
80
+ ```
81
+
82
+ == React
83
+
84
+ ```tsx
85
+ const output = { type: 'image/webp', quality: 0.8 }
86
+
87
+ export function Receipt() {
88
+ return <PaperPic src="/receipt.jpg" output={output} />
89
+ }
90
+ ```
91
+
92
+ :::
93
+
94
+ | Format | Suits |
95
+ | ------------ | -------------------------------------------------------- |
96
+ | `image/png` | Cleaned up documents and text, with no loss |
97
+ | `image/jpeg` | Photos and colored documents, in small files |
98
+ | `image/webp` | Photos and colored documents, in smaller files than JPEG |
99
+
100
+ A browser that cannot encode the format you ask for gives PNG, so read `type` in the event.
101
+
102
+ ## Size
103
+
104
+ The result keeps the full resolution of the source, which is 12 megapixels or more for many phone photos. [`maxOutputSize`](../reference/options#maxoutputsize) limits its longest side, in pixels:
105
+
106
+ :::tabs key:framework
107
+ == JavaScript
108
+
109
+ ```ts
110
+ const pic = new PaperPic(container, {
111
+ src: '/receipt.jpg',
112
+ maxOutputSize: 2000,
113
+ })
114
+ ```
115
+
116
+ == Vue
117
+
118
+ ```vue
119
+ <PaperPic src="/receipt.jpg" :max-output-size="2000" />
120
+ ```
121
+
122
+ == React
123
+
124
+ ```tsx
125
+ <PaperPic src="/receipt.jpg" maxOutputSize={2000} />
126
+ ```
127
+
128
+ :::
129
+
130
+ The preview while editing is always about 2 megapixels, so `maxOutputSize` changes only the result.
131
+
132
+ ## The download button
133
+
134
+ [`download: true`](../reference/options#download) adds a button at the end of the toolbar that saves the image on display: the result of the last Apply, or else the source as it is. It is hidden while editing, because the edits are not applied yet. [`download()`](../reference/methods#download) does the same from code, with or without the button. The browser's context menu does not open over the viewer, so this button is the way to save the image from it.
135
+
136
+ The file keeps the name of the source and takes the extension of its format, so a cleaned up `receipt.jpg` saves as `receipt.png`. [`filename`](../reference/options#filename) sets another name. Without any name, such as for a `Blob`, the file is called `image`.
137
+
138
+ ### Save it another way
139
+
140
+ The [`download`](../reference/events#download) event comes before the browser saves the file. Call `preventDefault()` to save it another way, such as from your server, which can name the file and check who downloads it:
141
+
142
+ :::tabs key:framework
143
+ == JavaScript
144
+
145
+ ```ts
146
+ pic.on('download', ({ preventDefault }) => {
147
+ preventDefault()
148
+ window.location.assign('/api/documents/42/file')
149
+ })
150
+ ```
151
+
152
+ == Vue
153
+
154
+ ```vue
155
+ <script setup lang="ts">
156
+ import type { PaperPicDownload } from '@paperpic/vue'
157
+ import { PaperPic } from '@paperpic/vue'
158
+
159
+ function download({ preventDefault }: PaperPicDownload) {
160
+ preventDefault()
161
+ window.location.assign('/api/documents/42/file')
162
+ }
163
+ </script>
164
+
165
+ <template>
166
+ <PaperPic src="/receipt.jpg" download @download="download" />
167
+ </template>
168
+ ```
169
+
170
+ == React
171
+
172
+ ```tsx
173
+ import type { PaperPicDownload } from '@paperpic/react'
174
+ import { PaperPic } from '@paperpic/react'
175
+
176
+ function download({ preventDefault }: PaperPicDownload) {
177
+ preventDefault()
178
+ window.location.assign('/api/documents/42/file')
179
+ }
180
+
181
+ export function Receipt() {
182
+ return <PaperPic src="/receipt.jpg" download onDownload={download} />
183
+ }
184
+ ```
185
+
186
+ :::
@@ -0,0 +1,266 @@
1
+ ---
2
+ title: Styling
3
+ description: How to fit PaperPic into the look of your app, with its stylesheet, its CSS tokens, dark mode, your own icons and a cascade layer that lets your CSS win.
4
+ ---
5
+
6
+ # Styling
7
+
8
+ PaperPic should look like part of your app. It ships one stylesheet, takes its colors and corners from a few CSS tokens, follows the color scheme of your page, and keeps its rules in a cascade layer, so your own CSS always wins.
9
+
10
+ ## Import the stylesheet
11
+
12
+ Import it once in your app:
13
+
14
+ :::tabs key:framework
15
+ == JavaScript
16
+
17
+ ```ts
18
+ import '@paperpic/core/style.css'
19
+ ```
20
+
21
+ == Vue
22
+
23
+ ```ts
24
+ import '@paperpic/vue/style.css'
25
+ ```
26
+
27
+ == React
28
+
29
+ ```ts
30
+ import '@paperpic/react/style.css'
31
+ ```
32
+
33
+ :::
34
+
35
+ ## Give it a size
36
+
37
+ The viewer fills its container and has no height of its own, so the container needs one. Any CSS that gives it a height works:
38
+
39
+ ```css
40
+ .document-viewer {
41
+ height: 70dvh;
42
+ }
43
+ ```
44
+
45
+ The viewer follows the size of its container, not the size of the screen. It reacts when the container changes, such as when a side panel opens.
46
+
47
+ ## Colors and corners
48
+
49
+ Five [CSS tokens](../reference/css-tokens) set the surface, the text, the accent, the corner radius and the length of the transitions. Set them on `:root`, on an ancestor of the viewer or on `.paperpic`:
50
+
51
+ ```css
52
+ :root {
53
+ --paperpic-color-accent: #c2410c;
54
+ --paperpic-radius: 0;
55
+ }
56
+ ```
57
+
58
+ The tokens are inherited, so a class on the container of one viewer, or on the Vue or React component, changes that viewer only:
59
+
60
+ ```css
61
+ .signature-viewer {
62
+ --paperpic-color-accent: #15803d;
63
+ }
64
+ ```
65
+
66
+ ## Use the colors of your design system {#design-system}
67
+
68
+ If your app keeps its colors in CSS variables, point the tokens at them instead of copying their values. The viewer then follows your theme, dark mode included:
69
+
70
+ ```css
71
+ .paperpic {
72
+ --paperpic-color-surface: var(--app-surface);
73
+ --paperpic-color-text: var(--app-text);
74
+ --paperpic-color-accent: var(--app-primary);
75
+ --paperpic-radius: var(--app-radius);
76
+ }
77
+ ```
78
+
79
+ Set them on `.paperpic`, as here. A token that uses `var()` reads the variable on the element where you set it, so on `:root` it would miss a theme that you switch on one part of the page.
80
+
81
+ Any design system with CSS variables works, such as the theme variables of Tailwind CSS 4: `var(--color-blue-600)` or `var(--radius-md)`.
82
+
83
+ ## Dark mode {#dark-mode}
84
+
85
+ The colors follow the `color-scheme` of your page, as the form controls of the browser do:
86
+
87
+ - With `color-scheme: light dark`, they turn dark when the user's system prefers a dark color scheme.
88
+ - With `color-scheme: dark`, they are always dark. This also works on one part of the page.
89
+ - Without `color-scheme`, they stay light, so a page without a dark theme keeps a light viewer.
90
+
91
+ If your site follows the system, declare it once:
92
+
93
+ ```css
94
+ :root {
95
+ color-scheme: light dark;
96
+ }
97
+ ```
98
+
99
+ If your site switches themes with a class, such as on `<html>`, set `color-scheme` with that class. The scroll bars and form controls of the browser follow it too:
100
+
101
+ ```css
102
+ :root.dark {
103
+ color-scheme: dark;
104
+ }
105
+ ```
106
+
107
+ To choose your own dark colors, give a token both values with `light-dark()`:
108
+
109
+ ```css
110
+ :root {
111
+ --paperpic-color-accent: light-dark(#c2410c, #fb923c);
112
+ }
113
+ ```
114
+
115
+ Tokens that point at the variables of your [design system](#design-system) follow your theme instead.
116
+
117
+ ## Icons {#icons}
118
+
119
+ The [`icons`](../reference/options#icons) option replaces any icon with your own markup, usually an `<svg>` from the icon set of your app:
120
+
121
+ :::tabs key:framework
122
+ == JavaScript
123
+
124
+ ```ts
125
+ import { PaperPic } from '@paperpic/core'
126
+ import '@paperpic/core/style.css'
127
+
128
+ const pic = new PaperPic(document.querySelector<HTMLElement>('#viewer')!, {
129
+ src: '/receipt.jpg',
130
+ icons: {
131
+ zoomIn: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="11" cy="11" r="7" /><path d="M11 8v6M8 11h6M20 20l-4-4" /></svg>',
132
+ },
133
+ })
134
+ ```
135
+
136
+ == Vue
137
+
138
+ ```vue
139
+ <script setup lang="ts">
140
+ import { PaperPic } from '@paperpic/vue'
141
+ import '@paperpic/vue/style.css'
142
+
143
+ const icons = {
144
+ zoomIn: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="11" cy="11" r="7" /><path d="M11 8v6M8 11h6M20 20l-4-4" /></svg>',
145
+ }
146
+ </script>
147
+
148
+ <template>
149
+ <div style="height: 480px">
150
+ <PaperPic src="/receipt.jpg" :icons="icons" />
151
+ </div>
152
+ </template>
153
+ ```
154
+
155
+ == React
156
+
157
+ ```tsx
158
+ import { PaperPic } from '@paperpic/react'
159
+ import '@paperpic/react/style.css'
160
+
161
+ const icons = {
162
+ zoomIn: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="11" cy="11" r="7" /><path d="M11 8v6M8 11h6M20 20l-4-4" /></svg>',
163
+ }
164
+
165
+ export function Receipt() {
166
+ return (
167
+ <div style={{ height: 480 }}>
168
+ <PaperPic src="/receipt.jpg" icons={icons} />
169
+ </div>
170
+ )
171
+ }
172
+ ```
173
+
174
+ :::
175
+
176
+ - Each key names an icon, and some icons appear on two buttons: `apply` is also on Done, and `cancel` also closes a tool. [Options](../reference/options#icons) lists every key.
177
+ - PaperPic gives the icon the class `paperpic-icon`, which sets its size, and hides it from screen readers, because the button already has a name.
178
+ - Draw the icon with `currentColor`, so it takes the color of the button in every theme.
179
+ - The markup goes into the page as HTML, so pass only markup you trust.
180
+ - With Vite, `import zoomIn from './zoom-in.svg?raw'` gives you the markup of an `.svg` file.
181
+
182
+ To change every icon at once, such as their size or the width of their lines, style the class:
183
+
184
+ ```css
185
+ .paperpic-icon {
186
+ inline-size: 1.125rem;
187
+ block-size: 1.125rem;
188
+ stroke-width: 1.5;
189
+ }
190
+ ```
191
+
192
+ ## Your CSS wins
193
+
194
+ The rules of PaperPic live in the `paperpic` cascade layer, and any CSS outside a layer overrides them, whatever its specificity. That makes overrides easy, but a global reset outside a layer, such as a rule on `button`, also reaches the buttons of the viewer.
195
+
196
+ If your reset breaks the viewer, move it into a layer that comes before `paperpic`. The first statement that names the layers fixes their order, so put it in CSS that loads before the stylesheet of PaperPic:
197
+
198
+ ```css
199
+ @layer reset, paperpic;
200
+
201
+ @layer reset {
202
+ button {
203
+ all: unset;
204
+ }
205
+ }
206
+ ```
207
+
208
+ ## Tailwind CSS {#tailwind}
209
+
210
+ Tailwind CSS 4 keeps its rules in cascade layers too. Name every layer, in order, before you import Tailwind and PaperPic, so the reset of Tailwind comes before `paperpic` and its utilities come after it:
211
+
212
+ :::tabs key:framework
213
+ == JavaScript
214
+
215
+ ```css
216
+ @layer theme, base, paperpic, components, utilities;
217
+
218
+ @import 'tailwindcss';
219
+ @import '@paperpic/core/style.css';
220
+ ```
221
+
222
+ == Vue
223
+
224
+ ```css
225
+ @layer theme, base, paperpic, components, utilities;
226
+
227
+ @import 'tailwindcss';
228
+ @import '@paperpic/vue/style.css';
229
+ ```
230
+
231
+ == React
232
+
233
+ ```css
234
+ @layer theme, base, paperpic, components, utilities;
235
+
236
+ @import 'tailwindcss';
237
+ @import '@paperpic/react/style.css';
238
+ ```
239
+
240
+ :::
241
+
242
+ Import the stylesheet of PaperPic here, in your CSS, and not from JavaScript. In another order, the reset of Tailwind removes padding and borders from the viewer, or the viewer overrides utilities such as `h-96` on the component.
243
+
244
+ ## Class names {#class-names}
245
+
246
+ The [CSS reference](../reference/css-tokens#classes) lists the classes you can target, such as `paperpic-toolbar` and `paperpic-button`, and their names stay stable. Other classes hold the layout together and can change in any release. Prefer the tokens when they cover what you need.
247
+
248
+ Every button, ruler and corner handle also carries `data-paperpic-control`, with the key of its [label](../reference/labels). Select it to style one control:
249
+
250
+ ```css
251
+ .paperpic-button[data-paperpic-control='edit'] {
252
+ color: var(--paperpic-color-accent);
253
+ }
254
+ ```
255
+
256
+ ## Layout
257
+
258
+ The interface adapts to its container on its own:
259
+
260
+ - The toolbar sits at the right and scrolls when the viewer is too short for its buttons. It hides while editing.
261
+ - The edit bar is a card at the bottom with two rows of fixed height, or one row in a viewer at least 28rem wide, so the image keeps its place when a tool opens.
262
+ - On touch screens, buttons and corner handles grow to at least 44 pixels.
263
+
264
+ ## Your own controls
265
+
266
+ When styling is not enough, hide the built-in toolbar and edit bar with `toolbar: false`, and drive the viewer from controls of your own. [Custom toolbar](../examples/custom-toolbar) shows how.
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: Adjust
3
+ description: How the Adjust tool of PaperPic changes the brightness and the contrast of a document image with a live ruler, and how to set them from code.
4
+ ---
5
+
6
+ # Adjust
7
+
8
+ Photos taken in poor light come out dark or gray. Adjust changes the brightness and the contrast and keeps the colors, for documents that should not become black and white, such as colored forms or photos.
9
+
10
+ ## Use it
11
+
12
+ 1. Press Edit, then Adjust. Its panel takes the place of the tools: a ruler, and Brightness and Contrast to choose which tone it changes.
13
+ 2. Drag the ruler. The preview changes while you drag. Choose Contrast to change the other tone with the same ruler.
14
+ 3. Press Done to keep both tones as one edit, which Undo removes. Cancel this tool leaves the image as it was.
15
+
16
+ The middle of the ruler leaves the image as it is, and the needle catches there, so no change is easy to find again. Screen readers announce the value from -100 to 100, such as "Brightness +30". A dot on Adjust marks values that are not 0.
17
+
18
+ Adjust runs after the other edits, so Crop and Straighten show the image with it.
19
+
20
+ ## Adjust or Clean up?
21
+
22
+ | Adjust | [Clean up](./clean-up) |
23
+ | ------------------------------------ | --------------------------------------- |
24
+ | Keeps the colors and the grays | Turns the document into black and white |
25
+ | For colored forms, stamps and photos | For text on paper |
26
+ | Keeps the format of the source | Gives PNG |
27
+
28
+ While Clean up is on, Adjust is disabled, because a cleaned up document has tones of its own.
29
+
30
+ ## From code
31
+
32
+ [`setAdjustments()`](../../reference/methods#setadjustments) takes values from -1 to 1, where 0 is no change, and [`getState()`](../../reference/methods#getstate) returns them in `adjustments`:
33
+
34
+ ```ts
35
+ pic.edit()
36
+ pic.setAdjustments({ brightness: 0.2, contrast: 0.3 })
37
+ ```
38
+
39
+ While Adjust is open, `setAdjustments()` changes what its panel shows, and [`confirmTool()`](../../reference/methods#confirmtool) keeps it as one edit.
40
+
41
+ In the [`tools`](../../reference/options#tools) option, Adjust is `'adjust'`.
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: Clean up
3
+ description: How the Clean up tool of PaperPic turns a photo of a document into crisp black and white without shadows, and how sensitivity and softness change the result, with a live demo.
4
+ ---
5
+
6
+ # Clean up
7
+
8
+ Text on paper reads best in black and white, but a photo has shadows, uneven light and gray paper. Clean up compares each pixel with its surroundings to decide whether it is ink or paper, so shadows and uneven light disappear and the text stays sharp. Its id in the API is `threshold`.
9
+
10
+ <Demo src="/samples/receipt.jpg" alt="A receipt" :tools="['perspective', 'threshold']" />
11
+
12
+ Straighten the receipt first, then clean it up.
13
+
14
+ ## Use it
15
+
16
+ 1. Press Edit, then Clean up. Its panel takes the place of the tools, the preview turns black and white, and a Sensitivity ruler appears.
17
+ 2. Drag the ruler. Higher sensitivity darkens more pixels, which recovers faint or worn text. Lower sensitivity gives a cleaner page, without the print that shows through from the back.
18
+ 3. Press Done to keep it as one edit, or Cancel this tool to leave the image as it was.
19
+
20
+ To turn off a Clean up that is already an edit, open it again: a switch next to the ruler turns it off, and the edits that came after it stay. Undo would take those edits away first.
21
+
22
+ Clean up always runs after the other edits. Crop shows the image cleaned up, as it will be. Straighten shows it without Clean up, because the edges of the paper are hard to find on a cleaned up page.
23
+
24
+ ## Softness
25
+
26
+ [`softness`](../../reference/options#softness) sets how much gray Clean up keeps at the edges of the letters, from 0 to 1, with 0.25 by default. A little gray smooths the edges and makes small text easier to read. Use `0` for strict black and white, which gives smaller files but breaks thin strokes.
27
+
28
+ ## Format of the result
29
+
30
+ A cleaned up image is PNG, because JPEG would add artifacts around its sharp edges. The [`output`](../../reference/options#output) option can choose another format.
31
+
32
+ ## From code
33
+
34
+ [`setThreshold()`](../../reference/methods#setthreshold) turns Clean up on or off and sets its sensitivity, from 0 to 1, with 0.5 by default. [`getState()`](../../reference/methods#getstate) returns both in `threshold`:
35
+
36
+ ```ts
37
+ pic.edit()
38
+ pic.setThreshold({ enabled: true, sensitivity: 0.6 })
39
+ ```
40
+
41
+ While Clean up is open, `setThreshold()` changes what its panel shows, and [`confirmTool()`](../../reference/methods#confirmtool) keeps it as one edit.
@@ -0,0 +1,39 @@
1
+ ---
2
+ title: Crop
3
+ description: How the Crop tool of PaperPic keeps the part of a photo that holds the document, with corner handles, a magnifier on touch screens and the keyboard.
4
+ ---
5
+
6
+ # Crop
7
+
8
+ A photo of a document often shows the table, a hand or other papers around it. Crop keeps the rectangle that holds the document and drops the rest.
9
+
10
+ ## Use it
11
+
12
+ 1. Press Edit, then Crop. A rectangle appears inside the image, with a handle at each corner.
13
+ 2. Drag the corners until the rectangle frames the document. The panel of Crop has zoom buttons, so you can zoom in to place them precisely.
14
+ 3. Press Done, or `Enter`, to add the crop to the edits. Cancel this tool, or `Esc`, closes Crop without changing anything.
15
+
16
+ While Crop is open, the image looks as the result will, with Adjust and Clean up included. The crop is an edit like any other: Undo removes it, and Apply makes it permanent.
17
+
18
+ ## Corner handles
19
+
20
+ - The handles stay inside the image, and the rectangle never turns inside out.
21
+ - On a touch screen, a magnifier shows the area under the finger while it drags a corner, so the finger does not hide where the corner lands.
22
+ - Without dragging, press a handle and then tap where its corner goes. The handle stays highlighted until then, the zoom buttons zoom toward its corner, and `Esc` lets go of it.
23
+ - With the keyboard, Tab moves between the handles, and the arrow keys move the focused handle 1 screen pixel, or 10 with Shift. `+` and `-` zoom toward the focused handle. Screen readers announce each move.
24
+
25
+ ## Crop or Straighten?
26
+
27
+ Crop keeps a rectangle as it is. In a photo taken at an angle, the document looks like a trapezoid, and no rectangle fits it. Use [Straighten](./straighten) for those: it moves each corner on its own and flattens the page.
28
+
29
+ ## From code
30
+
31
+ Crop is in the edit bar by default, with the id `'crop'` in [`tools`](../../reference/options#tools). With `toolbar: false`, open it with [`openTool()`](../../reference/methods#opentool), and close it with [`confirmTool()`](../../reference/methods#confirmtool) or [`cancelTool()`](../../reference/methods#canceltool):
32
+
33
+ ```ts
34
+ pic.edit()
35
+ pic.openTool('crop')
36
+
37
+ // Later, from a button of your own
38
+ pic.confirmTool()
39
+ ```
@@ -0,0 +1,35 @@
1
+ ---
2
+ title: Rotate and flip
3
+ description: How to rotate and flip a document image in PaperPic, in the edit mode, in a read-only viewer and from code.
4
+ ---
5
+
6
+ # Rotate and flip
7
+
8
+ Phones often save a photo of a document sideways or upside down, and some scans come out mirrored. Rotate left and Flip fix the orientation and leave the rest of the image as it is.
9
+
10
+ ## Rotate
11
+
12
+ In the edit bar, Rotate left turns the image a quarter turn counterclockwise, as in photo galleries. Press it twice for a half turn, or three times for a quarter turn clockwise.
13
+
14
+ A rotation is an edit: Undo removes it, and Apply makes it permanent. Four rotations bring the image back to where it was, and then there is nothing to apply.
15
+
16
+ From code, [`rotate()`](../../reference/methods#rotate) turns clockwise with `1`, and counterclockwise with `-1`:
17
+
18
+ ```ts
19
+ pic.rotate(1)
20
+ pic.rotate(-1)
21
+ ```
22
+
23
+ ## Flip
24
+
25
+ Flip mirrors the image left to right, as it is on display, so after a quarter turn it still mirrors left to right on the screen. To turn an image upside down, flip it and rotate it twice.
26
+
27
+ Flips and rotations that cancel out leave nothing to apply. From code, call [`flip()`](../../reference/methods#flip).
28
+
29
+ ## In a read-only viewer
30
+
31
+ With [`editable: false`](../viewer#read-only), the toolbar has Rotate left and Rotate right buttons. They only turn the image on display: nothing is saved, and the `apply` event never fires. [`rotate()`](../../reference/methods#rotate) does the same from code. A read-only viewer has no Flip.
32
+
33
+ ## Ids
34
+
35
+ In the [`tools`](../../reference/options#tools) option, Rotate left is `'rotate'` and Flip is `'flip'`.
@@ -0,0 +1,78 @@
1
+ ---
2
+ title: Straighten
3
+ description: How the Straighten tool of PaperPic turns a photo of a document taken at an angle into a flat page, how it estimates the proportions and when to set aspectRatio, with a live demo.
4
+ ---
5
+
6
+ # Straighten
7
+
8
+ A document photographed at an angle looks like a trapezoid: the far edge is shorter and the text leans. Straighten turns it back into a flat, rectangular page, as if it had been scanned. Its id in the API is `perspective`.
9
+
10
+ <Demo src="/samples/receipt.jpg" alt="A receipt" :tools="['perspective']" />
11
+
12
+ ## Use it
13
+
14
+ 1. Press Edit, then Straighten. A handle appears for each corner.
15
+ 2. Drag each handle onto a corner of the document. Zoom in with the buttons of its panel to place them precisely.
16
+ 3. Press Done, or `Enter`. The viewer shows the page flat, cut to the four corners.
17
+
18
+ The handles work as in [Crop](./crop): a magnifier on touch screens, press and tap instead of dragging, and Tab and the arrow keys on the keyboard. The four corners always keep a convex shape, so the page can always be flattened.
19
+
20
+ Straighten shows the photo without [Clean up](./clean-up), because the edges of the paper are hard to find on a cleaned up page. Clean up comes back after Done.
21
+
22
+ ## Proportions
23
+
24
+ A photo does not tell the real shape of the page, so Straighten estimates its proportions from where the corners sit in the photo. The estimate suits photos taken from a normal distance, but it cannot be exact.
25
+
26
+ The estimate uses the original photo, even after a crop or a rotation in the same edit. Once the user applies, the result counts as the new photo, so straighten before applying.
27
+
28
+ When you know the document, set [`aspectRatio`](../../reference/options#aspectratio) to its width divided by its height, and the result takes those proportions:
29
+
30
+ :::tabs key:framework
31
+ == JavaScript
32
+
33
+ ```ts
34
+ const pic = new PaperPic(container, {
35
+ src: '/invoice.jpg',
36
+ aspectRatio: 210 / 297,
37
+ })
38
+ ```
39
+
40
+ == Vue
41
+
42
+ ```vue
43
+ <PaperPic src="/invoice.jpg" :aspect-ratio="210 / 297" />
44
+ ```
45
+
46
+ == React
47
+
48
+ ```tsx
49
+ <PaperPic src="/invoice.jpg" aspectRatio={210 / 297} />
50
+ ```
51
+
52
+ :::
53
+
54
+ | Document | `aspectRatio` |
55
+ | ------------------------- | -------------- |
56
+ | A4 sheet, portrait | `210 / 297` |
57
+ | US Letter sheet, portrait | `8.5 / 11` |
58
+ | ID card, landscape | `85.6 / 53.98` |
59
+
60
+ For a sheet in landscape, swap the numbers, such as `297 / 210`.
61
+
62
+ ## Corners cut off by the photo
63
+
64
+ Sometimes a corner of the document falls outside the photo. The handles stay inside the image, so place that handle on the border of the photo, along the edge of the document that keeps the content. The last rows lean slightly and the estimated proportions suffer, which [`aspectRatio`](../../reference/options#aspectratio) can fix.
65
+
66
+ The [playground](../../playground) has a sample receipt with a cut-off corner to try it.
67
+
68
+ ## From code
69
+
70
+ Straighten opens with [`openTool('perspective')`](../../reference/methods#opentool) and closes with [`confirmTool()`](../../reference/methods#confirmtool) or [`cancelTool()`](../../reference/methods#canceltool):
71
+
72
+ ```ts
73
+ pic.edit()
74
+ pic.openTool('perspective')
75
+
76
+ // Later, from a button of your own
77
+ pic.confirmTool()
78
+ ```