Skip to content
Draft
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
24 changes: 24 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,30 @@ Each of these is a rule the code is expected to follow, not a description of
what it happens to do. They live here so there is one copy: `CLAUDE.md` and
`AGENTS.md` point at this file rather than restating it.

## Story map snapshot

On `com.exptech.dpip/map_snapshot`, `capture` returns PNG bytes.
`captureWithProjection` takes the same style, center, zoom, logical
`width`/`height`, `pixelRatio`, and optional `showLogo` arguments, plus
`points`, a nonempty list of maps with unique nonempty string `id` and numeric
`latitude`/`longitude` in degrees. Story uses a 360×640 logical viewport and
integer pixel ratios 1–3. The pixel ratio is required, and width and height
must be positive whole numbers.

The response is a single map with `png` (typed bytes), `pngWidth` and
`pngHeight` (integer raster pixels), `logicalWidth` and `logicalHeight`
(requested logical dimensions), and `points` (ID to `[x, y]` in logical
pixels from the top left). Off-canvas points are valid. All coordinates
come from the completed native snapshot that produced the PNG. Android
converts bitmap pixels against the actual bitmap dimensions. iOS converts
image points against the corresponding UIImage dimensions in points.

Story matches the reserved `epicenter` ID to the report epicenter and each
observation ID to its JSON-encoded `[area name, station name]` pair. The app
requires a finite point for every requested ID and matching PNG dimensions
before export. Invalid requests fail with `bad_args`, and unusable native
projections or mismatched dimensions fail with `invalid_projection`.

## Logging

Always log through `Log` (`lib/core/logging/log.dart`):
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
package com.exptech.dpip

import android.graphics.Bitmap
import android.graphics.BitmapFactory
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import io.flutter.plugin.common.MethodCall
import io.flutter.plugin.common.MethodChannel
import org.junit.Assert.assertArrayEquals
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
import org.junit.Test
import org.junit.runner.RunWith
import org.maplibre.android.MapLibre
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.Style
import org.maplibre.android.snapshotter.MapSnapshot
import org.maplibre.android.snapshotter.MapSnapshotter
import java.io.ByteArrayOutputStream
import java.util.concurrent.CompletableFuture
import java.util.concurrent.TimeUnit
import kotlin.math.hypot

@RunWith(AndroidJUnit4::class)
class MapSnapshotProjectionTest {
private val instrumentation = InstrumentationRegistry.getInstrumentation()
private val context = instrumentation.targetContext
private val channel = MapSnapshotChannel(context)
private var nativeControl: MapSnapshotter? = null

private val style = """
{"version":8,"sources":{},"layers":[
{"id":"background","type":"background","paint":{"background-color":"#66bbcc"}}
]}
""".trimIndent()
private val center = LatLng(22.458492717664083, 120.71)
private val zoom = 5.806293217527967
private val points = linkedMapOf(
"epicenter" to LatLng(22.64, 121.59),
"west" to LatLng(23.57, 119.56),
"north" to LatLng(25.08, center.longitude),
"south" to LatLng(21.90, center.longitude),
"center" to center,
)

@Test
fun projectsNorthUpInLogicalPixelsAndKeepsLegacyPngAtAllThreeScales() {
for (scale in 1..3) {
val args = arguments(scale)
val response = projected(args)
val png = response["png"] as ByteArray
val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
BitmapFactory.decodeByteArray(png, 0, png.size, bounds)
assertEquals(360 * scale, bounds.outWidth)
assertEquals(640 * scale, bounds.outHeight)
assertEquals(bounds.outWidth, response["pngWidth"])
assertEquals(bounds.outHeight, response["pngHeight"])
assertEquals(360.0, response["logicalWidth"])
assertEquals(640.0, response["logicalHeight"])
assertArrayEquals(png, capture("capture", args - "points").get(30, TimeUnit.SECONDS) as ByteArray)

val positions = response["points"] as Map<*, *>
assertEquals(points.keys, positions.keys)
val control = CompletableFuture<Unit>()
instrumentation.runOnMainSync {
MapLibre.getInstance(context)
val options = MapSnapshotter.Options(360, 640)
.withPixelRatio(scale.toFloat())
.withLogo(false)
.withStyleBuilder(Style.Builder().fromJson(style))
.withCameraPosition(
CameraPosition.Builder()
.target(center)
.zoom(zoom)
.bearing(0.0)
.tilt(0.0)
.build(),
)
val snapshotter = MapSnapshotter(context, options)
nativeControl = snapshotter
snapshotter.start({ snapshot ->
try {
val bitmapPng = ByteArrayOutputStream()
assertTrue(snapshot.bitmap.compress(Bitmap.CompressFormat.PNG, 100, bitmapPng))
assertArrayEquals(png, bitmapPng.toByteArray())
comparePoints(snapshot, scale, positions)
control.complete(Unit)
} catch (error: AssertionError) {
control.completeExceptionally(error)
} finally {
nativeControl = null
}
}, { message ->
nativeControl = null
control.completeExceptionally(AssertionError(message))
})
}
control.get(30, TimeUnit.SECONDS)
}
}

@Test
fun rejectsInvalidCoordinatesAndDuplicateIds() {
val original = arguments(2)
val invalid = mapOf("id" to "invalid", "latitude" to Double.NaN, "longitude" to 121.5)
val duplicate = mapOf("id" to "same", "latitude" to 22.64, "longitude" to 121.59)
for (points in listOf(emptyList(), listOf(invalid), listOf(duplicate, duplicate))) {
val response = capture("captureWithProjection", original + ("points" to points))
assertEquals("bad_args", response.get(30, TimeUnit.SECONDS))
}
}

@Test
fun reportsNativeStyleFailureThroughProjectionCapture() {
val response = capture("captureWithProjection", arguments(2) + ("style" to "invalid JSON"))
assertEquals("snapshot_failed", response.get(30, TimeUnit.SECONDS))
}

@Test
fun keepsConcurrentSnapshotsPairedWithTheirCameraAndDimensions() {
val first = capture("captureWithProjection", arguments(1))
val second = capture("captureWithProjection", arguments(3) + ("zoom" to 7.0))
val lowZoom = first.get(30, TimeUnit.SECONDS) as Map<*, *>
val highZoom = second.get(30, TimeUnit.SECONDS) as Map<*, *>
assertEquals(360, lowZoom["pngWidth"])
assertEquals(1080, highZoom["pngWidth"])
fun eastOffset(response: Map<*, *>): Double {
val locations = response["points"] as Map<*, *>
return ((locations["epicenter"] as List<*>)[0] as Double) - 180
}
assertEquals(
eastOffset(lowZoom) * Math.pow(2.0, 7.0 - zoom),
eastOffset(highZoom),
0.01,
)
}

private fun comparePoints(snapshot: MapSnapshot, scale: Int, projected: Map<*, *>) {
for ((id, coordinate) in points) {
val reference = snapshot.pixelForLatLng(coordinate)
val point = projected[id] as List<*>
val x = point[0] as Double
val y = point[1] as Double
val error = hypot(x - reference.x.toDouble() / scale, y - reference.y.toDouble() / scale)
assertTrue("$id at ${scale}x: $error logical px", error < 0.001)
// Three points on the camera's meridian must stay on one column.
when (id) {
"north" -> {
assertEquals(180.0, x, 0.001)
assertTrue(y < 320.0)
}
"south" -> {
assertEquals(180.0, x, 0.001)
assertTrue(y > 320.0)
}
"center" -> {
assertEquals(180.0, x, 0.001)
assertEquals(320.0, y, 0.001)
}
}
}
}

private fun arguments(scale: Int): Map<String, Any> = mapOf(
"style" to style,
"latitude" to center.latitude,
"longitude" to center.longitude,
"zoom" to zoom,
"width" to 360.0,
"height" to 640.0,
"pixelRatio" to scale.toDouble(),
"showLogo" to false,
"points" to points.map { (id, coordinate) ->
mapOf("id" to id, "latitude" to coordinate.latitude, "longitude" to coordinate.longitude)
},
)

private fun projected(args: Map<String, Any>): Map<*, *> =
capture("captureWithProjection", args).get(30, TimeUnit.SECONDS) as Map<*, *>

private fun capture(method: String, args: Map<String, Any>): CompletableFuture<Any?> {
val response = CompletableFuture<Any?>()
instrumentation.runOnMainSync {
channel.onMethodCall(MethodCall(method, args), object : MethodChannel.Result {
override fun success(result: Any?) { response.complete(result) }
override fun error(code: String, message: String?, details: Any?) {
response.complete(code)
}
override fun notImplemented() {
response.completeExceptionally(AssertionError("$method is not implemented"))
}
})
}
return response
}
}
53 changes: 34 additions & 19 deletions android/app/src/main/kotlin/com/exptech/dpip/ImageSaverChannel.kt
Original file line number Diff line number Diff line change
Expand Up @@ -85,14 +85,13 @@ class ImageSaverChannel(private val context: Context) :
try {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
saveToMediaStore(bytes, fileName, mimeType)
result.success(null)
} else {
saveToPicturesDirectory(bytes, fileName, mimeType)
saveToPicturesDirectory(bytes, fileName, mimeType, result)
}
result.success(null)
} catch (error: SecurityException) {
// The legacy grant, and only that: API 29+ needs no permission, so
// reaching this there means something else refused the write.
result.error("permission_denied", error.message, null)
val code = if (status() == "denied") "permission_denied" else "save_failed"
result.error(code, error.message, null)
} catch (error: Exception) {
result.error("save_failed", error.message, null)
}
Expand All @@ -118,23 +117,28 @@ class ImageSaverChannel(private val context: Context) :
val stream = resolver.openOutputStream(uri)
?: throw IOException("MediaStore could not open the image for writing")
stream.use { it.write(bytes) }
val published = resolver.update(
uri,
ContentValues().apply { put(MediaStore.Images.Media.IS_PENDING, 0) },
null,
null,
)
if (published != 1) throw IOException("MediaStore could not publish the image")
} catch (error: Exception) {
// A failed write must not leave a pending row behind: it would be
// invisible to the gallery and never cleaned up by it.
resolver.delete(uri, null, null)
runCatching { resolver.delete(uri, null, null) }
throw error
}

resolver.update(
uri,
ContentValues().apply { put(MediaStore.Images.Media.IS_PENDING, 0) },
null,
null,
)
}

/** API 26–28: the public Pictures directory, then tell the gallery about it. */
private fun saveToPicturesDirectory(bytes: ByteArray, fileName: String, mimeType: String) {
private fun saveToPicturesDirectory(
bytes: ByteArray,
fileName: String,
mimeType: String,
result: MethodChannel.Result,
) {
if (context.checkSelfPermission(Manifest.permission.WRITE_EXTERNAL_STORAGE) !=
PackageManager.PERMISSION_GRANTED
) {
Expand All @@ -153,11 +157,22 @@ class ImageSaverChannel(private val context: Context) :
}

val file = uniqueFile(album, fileName)
file.writeBytes(bytes)
// Writes outside MediaStore are invisible until something tells the
// gallery to index them; without this the picture exists but no Photos
// app lists it.
MediaScannerConnection.scanFile(context, arrayOf(file.absolutePath), arrayOf(mimeType), null)
try {
file.writeBytes(bytes)
MediaScannerConnection.scanFile(
context, arrayOf(file.absolutePath), arrayOf(mimeType),
) { _, uri ->
if (uri != null) {
result.success(null)
} else {
runCatching { file.delete() }
result.error("save_failed", "The gallery could not index the image", null)
}
}
} catch (error: Exception) {
runCatching { file.delete() }
throw error
}
}

/** [fileName] in [directory], or the first `name (n).ext` that is free. */
Expand Down
Loading
Loading