Files
meshcore-open/documentation/image-messages.md
T
zjs81 5fb67abdde Merge dev; fix share-location and discovered-contact import/export; update docs
Merge dev (#588 share location, #436 discovered-contact import/export)
into fix/review-fixes-and-issue-batch. Conflicts: keep the node-scan
button alongside dev's import/export menu; take dev's marker label
prompt.

Share location (#588):
- Never share a missing or 0,0 radio position; hide the chat action and
  show "Your radio has no location set"
- Sanitise marker labels ('|' -> '/', newlines -> spaces) on every path
- One shared MarkerLabelDialog owning its controller/focus node, with
  keyboard submit, replacing three copies
- Map pins default to "Point of interest" again; "Share my location"
  uses the node name
- Location shares honour the send cooldown and handle send errors

Discovered-contact import/export (#436):
- Per-entry decoding with imported/skipped/invalid counts; reject keys
  that are not 32 bytes; skip in-file duplicates and the radio's own key
- Strip routing paths on import and stop exporting them; clamp future
  timestamps; enforce the discovered-contact cap; require a connection;
  2 MB file limit
- Export via in-memory XFile (fixes web); pass sharePositionOrigin for
  iPad (also GPX export and image save); macOS user-selected read-write
  entitlement for save dialogs

Docs: cover share location, import/export, node scan, TCP reconnect,
channel auto-resend options, arrival ordering, badge, password length
and image limits.

Translations for all new strings in every locale.
2026-10-11 01:54:07 -07:00

41 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Image Messages
MeshCore Open can send a highly compressed image as channel GRP_DATA packets. Unlike a GIF reference or URL preview, the compressed image bytes travel over the mesh. A compatible recipient reconstructs them locally using the image model.
## Requirements and setup
- Companion firmware version code **11 or later** (identified in the connector as v1.15.0) for the current channel-data layout.
- A native runtime with a working ONNX backend. The web build has no image codec backend.
- The image model bundle installed through App Settings → Image model, and Enable image messages turned on.
- Enough storage for the roughly 1 GB bundle and enough available memory for reconstruction, which can peak above 2 GB. Actual latency and memory usage depend on hardware.
Downloads use the configured Hugging Face model bundle, support resume, and verify file checksums. Download the model while internet is available. Once installed, encoding and reconstruction run locally; photos are not uploaded for inference. Compatible recipients need the same supported codec/model format.
## Send an image
1. Open channel chat and tap the image button beside the composer.
2. Pick a photo from your gallery.
3. Wait for encoding. Inspect the source preview and, if available, the reconstructed preview.
4. Review transmitted bytes, packet count, and estimated send duration. Estimates use the current radio settings and are unavailable if those settings are unknown.
5. Choose whether to include a recovery packet, then send. The chat shows per-packet progress.
The current build ships one quality/model setting: **ft32**, with a 512×512 codec reconstruction and metadata used to restore a supported aspect ratio. Reserved rate/resolution codes are not additional selectable quality options.
The result is a lossy, AI-reconstructed image and can differ materially from the original. It is labeled accordingly. Send confirmation describes companion acceptance of packets, not end-to-end proof that every recipient reconstructed the image.
## Receive, reconstruct, and save
Chunks are reassembled into an image entry in channel chat. A partially received stream is retained for up to 60 seconds before expiry. An optional XOR parity packet can recover **one missing data chunk**, provided the parity and other required chunks arrive; it does not guarantee delivery.
With Process images automatically enabled, complete images are queued for local reconstruction. Automatic decoding runs only while the app is in the foreground, one image at a time, with at most 3 images queued; when more arrive, the newest 3 are kept and the rest wait for a tap. Otherwise, tap an image entry to process it. Download/enable the model if prompted. A failed reconstruction can be retried; missing chunks and inference errors are different failures.
Tap a reconstructed image to inspect it. Long-press or right-click its chat bubble for Packet info, Delete, and Save (available once decoded). Deletion is local. Encoded streams and reconstructed images are persisted in application storage, capped at 200 images, 64 MB, and 30 days, plus a limit of 400 image entries (including ones waiting to be decoded and your own sent images once their data has expired). When the cap is reached, the oldest reconstructed images are evicted first and show "Image no longer stored"; they can be decoded again while their small encoded stream remains. Past 30 days the stream is removed too.
## Other image features
[GIFs and URL image previews](additional-features.md#url-image-previews) transmit references and fetch image content over the internet. They do not use this mesh image transport.
## Implementation reference
[image_chunk_transport.dart](../lib/services/image_chunk_transport.dart) defines the wire layout, capacities, metadata, and recovery algorithm. The current transport uses command 62, response 27, and data type `0xAE1C`. See the [protocol reference](ble-protocol.md#regions-and-image-data) and [fixture regeneration guide](../tools/aeic/README.md).