Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,15 @@ jobs:
- name: Build package
run: yarn prepare

- name: Run the built svg entry in Node
run: |
node --input-type=module -e "
import { renderSVG } from 'react-native-inkpad/svg';
const doc = { version: 1, size: { width: 10, height: 10 }, strokes: [] };
const svg = renderSVG(doc, { background: { color: 'white' } });
if (!svg.includes('<rect')) process.exit(1);
"

android:
runs-on: ubuntu-latest
steps:
Expand Down Expand Up @@ -140,10 +149,10 @@ jobs:
npx agent-device prepare ios-runner --platform ios --udid "$udid" --timeout 900000
npx agent-device daemon stop

- name: Stroke codec and command queue
- name: Stroke codec, command queue and renderer
env:
INKPAD_IOS_SIMULATOR: ${{ steps.simulator.outputs.udid }}
run: yarn vitest run src/__tests__/iosCodec.test.ts src/__tests__/iosCommandQueue.test.ts
run: yarn vitest run src/__tests__/iosCodec.test.ts src/__tests__/iosCommandQueue.test.ts src/__tests__/iosRender.test.ts

- name: End-to-end tests
env:
Expand Down
53 changes: 47 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ export function SignatureField() {
| `tool` | `'draw' \| 'erase'` | `'draw'` | The eraser removes whole strokes. |
| `inputMode` | `'any' \| 'stylus'` | `'any'` | With `'stylus'`, only a pen draws and fingers go to the parent. |
| `editable` | `boolean` | `true` | Set to `false` to turn drawing off. |
| `background` | `{ color, image, fit }` | transparent | Canvas color and an image under the ink, both exported. `image` takes an image source, `fit` is `'contain'` or `'cover'`. On web, an image from another origin needs CORS headers. |
| `background` | `{ color, image, fit }` | transparent | Canvas color and an image under the ink, both exported. `image` takes an image source, `fit` is `'contain'` or `'cover'`. On web, an image from another origin needs CORS headers. Request `headers` on the image source aren't sent. |
| `onStrokeStart` | `() => void` | | Called when a stroke starts. |
| `onStrokeEnd` | `() => void` | | Called when a stroke ends. |
| `onChange` | `(state) => void` | | Called after every change with `{ strokeCount, canUndo, canRedo }`. |
Expand All @@ -98,9 +98,46 @@ export function SignatureField() {
| `clear()` | Remove every stroke. |
| `getStrokes()` | Get the strokes as a plain object you can store as JSON. |
| `setStrokes(doc)` | Replace the drawing with strokes from `getStrokes()`. |
| `toImage({ format, quality, scale, trim, background, base64 })` | Export a PNG or JPEG. Resolves to `{ uri, width, height, base64? }`. On web, `uri` is a `blob:` URL. |
| `toImage({ format, quality, scale, maxSize, trim, background, base64 })` | Export a PNG or JPEG. `maxSize` caps the longest side in pixels. Resolves to `{ uri, width, height, base64? }`. On web, `uri` is a `blob:` URL. |
| `toSVG({ trim, background })` | Export an SVG string. It links the background image by URI. |

### Render without a canvas

`renderImage(doc, options)` and `renderSVG(doc, options)` turn a document from `getStrokes()` into an image or an SVG string without a mounted `InkCanvas`. Use them for thumbnails and lists.

| Function | Returns | Options |
| --- | --- | --- |
| `renderImage(doc, options)` | `Promise<{ uri, width, height, base64? }>`, the same result as `toImage`. | The `toImage` options, except `background` is `{ color, image, fit }` like the prop. |
| `renderSVG(doc, options)` | An SVG string, synchronously. | `{ trim, background }`, with the same `background`. |

A document has no background, so the default is transparent. `maxSize` is the longest side in pixels. It lowers `scale` for an image that would be bigger and never raises it, and a value below 1 is ignored.

```tsx
import { renderImage } from 'react-native-inkpad';

const thumb = await renderImage(doc, {
maxSize: 256,
trim: { padding: 8 },
background: { color: '#FFFFFF' },
});
```

`renderImage` rejects and `renderSVG` throws an `InkpadError`. `renderImage` fails with `E_EXPORT_FAILED` if the native module is missing, so rebuild the app.

#### On a server

The `react-native-inkpad/svg` entry exports `renderSVG`, `validateDocument`, `InkpadError` and `ErrorCode`, and doesn't load React Native.

```js
import { renderSVG } from 'react-native-inkpad/svg';

const svg = renderSVG(doc, { trim: { padding: 8 }, background: { color: 'hsl(0 0% 100%)' } });
```

Its `background` is `{ color?, image?: { uri }, fit? }`. `color` takes a hex, `rgb()`, `hsl()`, `hwb()` or named color, and one it can't parse throws `E_EXPORT_FAILED`. The SVG links the background image by URI.

npm 7+ installs the `react` and `react-native` peers on the server anyway, though nothing loads them.

### Errors

Failed calls throw an `InkpadError`. Its `code` is one of:
Expand All @@ -109,11 +146,11 @@ Failed calls throw an `InkpadError`. Its `code` is one of:
| --- | --- |
| `E_NOT_MOUNTED` | The canvas isn't mounted, or it unmounted before the call finished. |
| `E_TIMEOUT` | The native view didn't answer within 15 seconds. |
| `E_INVALID_DOCUMENT` | `setStrokes()` got a malformed document. |
| `E_UNSUPPORTED_VERSION` | The document was saved by a newer version of the library. |
| `E_EMPTY` | `trim` was set but the canvas is empty. |
| `E_INVALID_DOCUMENT` | `setStrokes()`, `renderImage()` or `renderSVG()` got a malformed document. |
| `E_UNSUPPORTED_VERSION` | `setStrokes()`, `renderImage()` or `renderSVG()` got a document saved by a newer version of the library. |
| `E_EMPTY` | `trim` was set but the canvas, or the document given to `renderImage()` or `renderSVG()`, has no strokes. |
| `E_EXPORT_FAILED` | The image couldn't be created or saved. |
| `E_IMAGE_LOAD` | The background image couldn't be loaded. It goes to `onError`. |
| `E_IMAGE_LOAD` | The background image couldn't be loaded, or `renderImage()` or `renderSVG()` got an image with no usable URI, such as a numeric `require()` asset on web. On the canvas it goes to `onError`. |
| `E_NATIVE` | Any other native error. |

## Migrating from react-native-signature-canvas
Expand Down Expand Up @@ -148,6 +185,10 @@ From 1.0, releases follow [semver](https://semver.org):
- [x] 0.3: Web
- [x] 0.4: Background images, stylus-only mode and `onError`
- [x] 1.0: First stable release
- [x] 1.1: Render a document without a canvas
- [ ] 1.2: Zoom and pan
- [ ] 1.3: Point eraser and stylus extras
- [ ] 1.4: Lasso select and move

## Contributing

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,273 @@
package me.sectiontn.inkpad

import android.content.Context
import android.graphics.Bitmap
import android.graphics.BitmapFactory
import android.graphics.Color
import android.net.Uri
import android.util.Base64
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import com.facebook.react.soloader.OpenSourceMergedSoMapping
import com.facebook.react.uimanager.ThemedReactContext
import com.facebook.soloader.SoLoader
import org.json.JSONObject
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
import org.junit.Before
import org.junit.Test
import org.junit.runner.RunWith
import java.io.ByteArrayOutputStream
import java.io.File
import java.util.Collections
import java.util.concurrent.CountDownLatch
import java.util.concurrent.TimeUnit

@RunWith(AndroidJUnit4::class)
class DocumentRendererTest {
private val instrumentation = InstrumentationRegistry.getInstrumentation()
private lateinit var base: Context
private lateinit var context: RecordingReactContext

@Before
fun createContext() {
base = instrumentation.targetContext
// Events build their payloads with React Native's native maps.
SoLoader.init(base, OpenSourceMergedSoMapping)
context = RecordingReactContext(base)
}

@Test
fun matchesTheCanvasExport() {
val density = base.resources.displayMetrics.density
val (view, doc) = drawnCanvas()

val cases = listOf(
"{}",
"""{"trim":true,"padding":8}""",
"""{"backgroundColor":"#FFEEDDFF"}""",
"""{"maxSize":160}""",
JSONObject().put("backgroundImageUri", paper).put("backgroundFit", "contain").toString(),
)
for ((i, case) in cases.withIndex()) {
val options = options(case, density)
val requestId = 10 + i
onMain { view.exportImage(requestId, options) }
settle()
val canvas = decode(payload(requestId))
val rendered = decode(render(doc, options).getOrThrow())
assertTrue("$case differs from the canvas export", canvas.sameAs(rendered))
if (case.contains("trim")) assertTrue(rendered.width < 320 * density)
if (case.contains("backgroundColor")) assertEquals(0xFFFFEEDD.toInt(), rendered.getPixel(0, 0))
if (case.contains("maxSize")) {
assertEquals(160, maxOf(canvas.width, canvas.height))
assertEquals(160, maxOf(rendered.width, rendered.height))
}
// The center of the canvas is inside the contained image and clear of every stroke.
if (case.contains("backgroundImageUri")) {
assertEquals(255, Color.alpha(rendered.getPixel(rendered.width / 2, rendered.height / 2)))
}
}
}

@Test
fun rendersAnEmptyDocumentAtItsSize() {
val bitmap = decode(render(EMPTY, options("{}", 2f)).getOrThrow())

assertEquals(640, bitmap.width)
assertEquals(480, bitmap.height)
val pixels = IntArray(bitmap.width * bitmap.height)
bitmap.getPixels(pixels, 0, bitmap.width, 0, 0, bitmap.width, bitmap.height)
assertTrue(pixels.all { it == 0 })
}

@Test
fun rejectsTrimOnAnEmptyDocument() {
val result = render(EMPTY, options("""{"trim":true}""", 2f))

assertEquals(ErrorCodes.EMPTY, (result.exceptionOrNull() as? InkpadException)?.code)
}

@Test
fun rejectsABackgroundThatFailsToLoad() {
val result = render(EMPTY, options("""{"backgroundImageUri":"file:///nonexistent.png"}""", 2f))

assertEquals(ErrorCodes.IMAGE_LOAD, (result.exceptionOrNull() as? InkpadException)?.code)
}

@Test
fun settlesManyRendersAtOnce() = settlesManyRenders(options("{}", 1f))

@Test
fun settlesManyRendersWithABackground() =
settlesManyRenders(options(JSONObject().put("backgroundImageUri", paper).toString(), 1f))

@Test
fun exportsAndRendersAtTheSameTime() {
val (view, doc) = drawnCanvas()
val options = options("{}", 1f)
onMain { view.exportImage(10, options) }
settle()
val reference = decode(payload(10))
val count = 20
val latch = CountDownLatch(count)
val rendered = Collections.synchronizedList(mutableListOf<Result<String>>())
onMain {
repeat(count) { i ->
view.exportImage(100 + i, options)
DocumentRenderer.render(context, doc, options) { result ->
rendered += result
latch.countDown()
}
}
}

assertTrue("renders still pending after 30 s", latch.await(30, TimeUnit.SECONDS))
settle()
repeat(count) { i ->
val canvas = decode(payload(100 + i))
assertTrue("canvas export $i differs", reference.sameAs(canvas))
canvas.recycle()
}
rendered.forEachIndexed { i, result ->
val bitmap = decode(result.getOrThrow())
assertTrue("render $i differs", reference.sameAs(bitmap))
bitmap.recycle()
}
}

private fun settlesManyRenders(options: String) {
val count = 20
val latch = CountDownLatch(count)
val results = Collections.synchronizedList(mutableListOf<Result<String>>())
val threads = Collections.synchronizedSet(mutableSetOf<Thread>())
val doc = drawing()
repeat(count) {
DocumentRenderer.render(context, doc, options) { result ->
results += result
threads += Thread.currentThread()
latch.countDown()
}
}

assertTrue("renders still pending after 30 s", latch.await(30, TimeUnit.SECONDS))
val uris = results.map { JSONObject(it.getOrThrow()).getString("uri") }
assertEquals(count, uris.toSet().size)
val renderer = InkpadExecutors.renderer.submit<Thread> { Thread.currentThread() }.get()
assertEquals(setOf(renderer), threads.toSet())
uris.forEach { File(Uri.parse(it).path!!).delete() }
}

// A laid out 320 x 240 dp canvas that holds the drawing, and the document it saved.
private fun drawnCanvas(): Pair<InkpadView, String> {
val density = base.resources.displayMetrics.density
val width = 320 * density
val height = 240 * density
assertTrue("320 x 240 dp is $width x $height px", width % 1f == 0f && height % 1f == 0f)
lateinit var view: InkpadView
onMain {
view = InkpadView(ThemedReactContext(context, base, null, -1))
view.layout(0, 0, width.toInt(), height.toInt())
view.setStrokes(1, drawing())
view.getStrokes(2)
}
settle()
val doc = payload(2)
assertEquals(4, DocumentJson.parse(doc).strokes.size)
onMain { view.setStrokes(3, doc) }
settle()
return view to doc
}

private fun onMain(block: () -> Unit) = instrumentation.runOnMainSync(block)

// Two rounds, since an answer that lands on the main thread can start the next background job.
private fun settle() = repeat(2) {
InkpadExecutors.worker.submit {}.get()
InkpadExecutors.exporter.submit {}.get()
instrumentation.waitForIdleSync()
}

private fun payload(requestId: Int): String {
var payload: String? = null
onMain {
payload = context.events
.firstOrNull { it.hasKey("requestId") && it.getInt("requestId") == requestId }
?.getString("payload")
}
return checkNotNull(payload) { "no answer to request $requestId" }
}

private fun render(document: String, options: String): Result<String> {
val latch = CountDownLatch(1)
var result: Result<String>? = null
DocumentRenderer.render(context, document, options) {
result = it
latch.countDown()
}
assertTrue("render still pending after 30 s", latch.await(30, TimeUnit.SECONDS))
return result!!
}

private fun decode(json: String): Bitmap {
val file = File(Uri.parse(JSONObject(json).getString("uri")).path!!)
val bitmap = checkNotNull(BitmapFactory.decodeFile(file.path)) { "could not decode $file" }
file.delete()
return bitmap
}

// The same background keys renderImage and toImage send, empty when unset.
private fun options(case: String, scale: Float): String {
val options = JSONObject()
.put("scale", scale.toDouble())
.put("background", true)
.put("backgroundColor", "")
.put("backgroundImageUri", "")
.put("backgroundFit", "contain")
val extra = JSONObject(case)
for (key in extra.keys()) options.put(key, extra.get(key))
return options.toString()
}

private fun drawing(): String = DocumentJson.write(
Doc(
320f,
240f,
listOf(
stroke(BrushType.PEN, InputType.TOUCH, 0xFF000000.toInt(), 3f, 40f),
stroke(BrushType.PEN, InputType.STYLUS, 0xFF1E40AF.toInt(), 4f, 90f),
stroke(BrushType.MARKER, InputType.TOUCH, 0xFFB91C1C.toInt(), 8f, 140f),
stroke(BrushType.HIGHLIGHTER, InputType.TOUCH, 0xFFFACC15.toInt(), 16f, 190f),
),
),
)

private fun stroke(type: BrushType, input: InputType, color: Int, size: Float, y: Float): DocStroke {
val stride = DocumentJson.STRIDE
val points = FloatArray(POINTS * stride) { k ->
val i = k / stride
when (k % stride) {
0 -> 30f + i * 10
1 -> y + if (i % 2 == 0) 0f else 8f
2 -> i * 8f
3 -> if (input == InputType.STYLUS) 0.2f + 0.7f * i / (POINTS - 1) else -1f
else -> -1f
}
}
return DocStroke(type, color, size, input, points)
}

private companion object {
const val POINTS = 24
val EMPTY = DocumentJson.write(Doc(320f, 240f, emptyList()))

val paper: String by lazy {
val bitmap = Bitmap.createBitmap(4, 4, Bitmap.Config.ARGB_8888).apply { eraseColor(0xFF2E7D32.toInt()) }
val bytes = ByteArrayOutputStream().use { out ->
bitmap.compress(Bitmap.CompressFormat.PNG, 100, out)
out.toByteArray()
}
"data:image/png;base64," + Base64.encodeToString(bytes, Base64.NO_WRAP)
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ class InkpadViewCommandsTest {

// Two rounds, since a load that lands on the main thread can start a save on the document thread.
private fun settle() = repeat(2) {
InkpadView.WORKER.submit {}.get()
InkpadExecutors.worker.submit {}.get()
instrumentation.waitForIdleSync()
}

Expand Down
Loading
Loading