@paperpic/react 0.0.0-stage → 0.1.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.
- package/LICENSE +21 -0
- package/README.md +40 -2
- package/dist/docs/examples/custom-toolbar.md +211 -0
- package/dist/docs/examples/fixed-proportions.md +120 -0
- package/dist/docs/examples/read-only.md +115 -0
- package/dist/docs/examples/upload.md +130 -0
- package/dist/docs/guide/accessibility.md +55 -0
- package/dist/docs/guide/editing.md +140 -0
- package/dist/docs/guide/getting-started.md +144 -0
- package/dist/docs/guide/introduction.md +36 -0
- package/dist/docs/guide/labels.md +120 -0
- package/dist/docs/guide/performance.md +39 -0
- package/dist/docs/guide/saving.md +186 -0
- package/dist/docs/guide/styling.md +266 -0
- package/dist/docs/guide/tools/adjust.md +41 -0
- package/dist/docs/guide/tools/clean-up.md +41 -0
- package/dist/docs/guide/tools/crop.md +39 -0
- package/dist/docs/guide/tools/rotate-and-flip.md +35 -0
- package/dist/docs/guide/tools/straighten.md +78 -0
- package/dist/docs/guide/viewer.md +81 -0
- package/dist/docs/reference/css-tokens.md +113 -0
- package/dist/docs/reference/events.md +68 -0
- package/dist/docs/reference/labels.md +70 -0
- package/dist/docs/reference/methods.md +228 -0
- package/dist/docs/reference/options.md +160 -0
- package/dist/docs/reference/react.md +84 -0
- package/dist/docs/reference/state.md +30 -0
- package/dist/docs/reference/vue.md +78 -0
- package/dist/index.d.ts +36 -0
- package/dist/index.js +85 -0
- package/dist/style.css +702 -0
- package/package.json +62 -3
|
@@ -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
|
+
```
|