Snapshot of the Umamo working tree as it is

Uploaded as-is from /home/litruv/dev/vtsmaker/umamo on 2026-11-03. 1347 files.
Includes the uncommitted work in progress in :edit, :runtime, and :ui, and the
untracked files under module/edit/src/jvmAndroidMain/.

History is not carried over. The source repo is https://github.com/umamoorg/umamo.
This commit is contained in:
litruv
2026-11-03 18:20:25 +11:00
commit 8bd8fa7a0b
1347 changed files with 246161 additions and 0 deletions
+46
View File
@@ -0,0 +1,46 @@
// :reimport — non-destructive reconcile over the model's source bindings. Depends on :format (the
// re-read art), :runtime (the bindings live on the model's atlas tiles), and :interop (the bridge that
// births a layer's mesh and mints the additions for the layers a file gained).
plugins {
alias(libs.plugins.kotlinMultiplatform)
alias(libs.plugins.androidKmpLibrary)
}
kotlin {
jvmToolchain(21)
jvm()
android {
namespace = "org.umamo.reimport"
compileSdk = libs.versions.android.compileSdk.get().toInt()
minSdk = libs.versions.android.minSdk.get().toInt()
}
sourceSets {
commonMain {
dependencies {
implementation(project(":format"))
implementation(project(":interop"))
// The content hash the watcher compares a save against, and okio (its `api`), which the
// polling watcher stats files through - the one file-system API that runs on every
// Kotlin target, so nothing here is JVM-bound.
implementation(project(":storage"))
api(project(":runtime"))
// The watch coordinator is coroutine-driven (settle timers, the idle wait); `api` because
// its scope and flows are its public surface.
api(libs.kotlinxCoroutinesCore)
}
}
commonTest {
dependencies {
implementation(kotlin("test"))
// runTest + the virtual clock the coordinator's settle and the watcher's polling are tested on.
implementation(libs.kotlinxCoroutinesTest)
// An in-memory file system for the polling watcher's test.
implementation(libs.okio.fakefilesystem)
}
}
}
}
@@ -0,0 +1,545 @@
package org.umamo.reimport
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerRaster
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceLayer
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.art.analyzeAlpha
import org.umamo.format.art.isFullyTransparent
import org.umamo.interop.art.ArtSourceDescriptor
import org.umamo.interop.art.SourceArtImport
import org.umamo.interop.art.SourceArtImportNotice
import org.umamo.interop.art.SourceArtImportOptions
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.ArtworkReload
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.ReplacedTile
import org.umamo.runtime.model.SourceLayerRef
import org.umamo.runtime.model.applyUvAffine
import org.umamo.runtime.model.isUntouchedBirthQuad
import org.umamo.runtime.model.reloadTileId
import org.umamo.runtime.model.storedToArtAffineForTile
/*
* The reload planner: the re-read file's matched and added halves turned into the model delta a
* reload commits. Pure over the model and the art - the pixels of the OLD tiles come in through a
* callback, the pixels of the new ones go out beside the delta - so the same plan runs against the
* live model and against the operation strip's base when a row is adjusted.
*
* What it never does: touch a tile whose layer the file lost without a confident match (the reconcile
* flags it for review), change a drawable's positions, or delete rig work - the one thing it removes
* is a fresh, untouched drawable whose layer a lost layer's rig work claims, and only when the caller
* names it. A drawable's mesh changes in only two ways: an untouched birth quad is re-born over the
* new art, and an edited mesh keeps its vertices with its texture coordinates carried so each vertex
* samples the canvas pixel it did before - Cubism's own re-import behavior, where the art moves under
* a mesh that stays. Its visibility follows the file's eye toggle only while it still shows the state
* the file last had: a toggle the rigger made in the outliner is rig work and stays.
*/
/**
* A planned reload: the delta, the new tiles' pixels, the reconcile it followed, its notes, and what
* the matcher proposed but did not apply.
*
* @property ArtworkReload reload The model delta.
* @property Map rasterByTile Each new tile's pixels, by its new id.
* @property ReconcileReport report The classification the plan followed (review items included).
* @property List notices What the reload could not carry as drawn, in document order.
* @property Map leftovers Each lost binding's best candidate that fell under the bar, by
* its lost key - scored before anything was minted, so a candidate the plan then minted a fresh
* drawable for is still named; what the caller publishes for the review chips.
*/
class ReloadPlan(
val reload: ArtworkReload,
val rasterByTile: Map<AtlasTileId, LayerRaster>,
val report: ReconcileReport,
val notices: List<SourceArtImportNotice>,
val leftovers: Map<String, LayerMatch> = emptyMap(),
)
/** One tile's replacement and everything that came with it. */
private class TileReplacement(
val replaced: ReplacedTile,
val raster: LayerRaster,
val meshes: Map<DrawableId, DrawableMesh>,
val outgrown: List<DrawableId>,
)
/** Half a pixel: how far a mesh may fall short of the opaque art before it counts as outgrown. */
private const val COVERAGE_TOLERANCE = 0.5f
/**
* Plans reloads and relinks. See the file comment for the rules.
*/
object ArtworkReloadPlanner {
/**
* Plans re-reading one listed file into [model].
*
* A bound tile is replaced when its layer's pixels, size, or canvas bounds differ from what the
* document holds; an unchanged layer costs nothing. A binding whose key the art lost is scored by
* [matcher] against the layers no tile is bound to BEFORE anything is minted: at or above
* [matchThreshold] its tile takes the best candidate's art (the layer re-created under a new key), so
* the rig work follows the layer and no fresh drawable is minted beside it; below the bar the layer
* is minted and the binding is left for review, the proposal kept in [ReloadPlan.leftovers] so the
* row can still offer it (accepting then retires the fresh drawable). The remaining raster layers
* no tile is bound to are minted through the bridge under the same source - except those the rigger
* ignored ([ArtSourceLayer.ignored]), which stay out however many reloads find them. A drawable whose
* layer's eye toggle changed since the last read follows it while it still shows the old state
* ([ArtworkReload.drawableVisibility]); one the rigger toggled since is left alone. The source record
* takes the inventory as just read. Null when the file is not one the model lists or when nothing at
* all changed - not even the inventory - so a reload with nothing to do pushes no step.
*
* @param PuppetModel model The model the plan applies to.
* @param ArtSourceId sourceId The listed file being re-read.
* @param SourceArt art The file as just read.
* @param SourceArtImportOptions options The threshold and margin every re-born quad and added layer use.
* @param Function oldRasterOf The document's pixels for a tile, or null when it has none.
* @param String? contentHash The whole-file content hash of the bytes [art] was read from,
* recorded on the refreshed source; null keeps the record's. A hash that changed while nothing in the
* layers did does not by itself make a plan - the watcher acknowledges such a save instead.
* @param ArtSourceDescriptor? replacement The file the record is repointed to (Replace Artwork): its
* name, path, and format take over, every binding the new art cannot resolve reads as SourceReplaced,
* and the plan is made even when no layer changed. Layers no tile is bound to are NOT minted under
* a replacement - they are the candidates the unresolved bindings are matched against, and a Reload
* brings in whatever is still unbound once the review is done. Null re-reads the record's own file.
* @param List<ArtSourceLayer> inventory The inventory of [art], for a caller that already computed it
* (it hashes every layer's pixels, so one read file should pay for it once); computed here by default.
* @param Long? lastModified The file's modification time when [art] was read, recorded on
* the refreshed source; null keeps the record's. A replacement records its own descriptor's instead.
* @param Float matchThreshold The confidence, 0..1 inclusive, at or above which a lost
* binding takes its best candidate in this plan.
* @param LayerMatcher matcher The matcher that ranks a lost binding's candidates.
* @return ReloadPlan? The plan, or null when there is nothing to commit.
*/
fun plan(
model: PuppetModel,
sourceId: ArtSourceId,
art: SourceArt,
options: SourceArtImportOptions,
oldRasterOf: (AtlasTileId) -> LayerRaster?,
contentHash: String? = null,
replacement: ArtSourceDescriptor? = null,
inventory: List<ArtSourceLayer> = SourceArtImport.inventoryOf(art),
lastModified: Long? = null,
matchThreshold: Float = InventoryLayerMatcher.DEFAULT_THRESHOLD,
matcher: LayerMatcher = InventoryLayerMatcher,
): ReloadPlan? {
val source = model.sources.firstOrNull { candidate -> candidate.id == sourceId } ?: return null
val layersByKey = rasterLayersByKey(art)
val boundTiles = model.atlas.tiles.filter { tile -> tile.source?.sourceId == sourceId }
val keyReport = KeyReconciler.reconcile(boundTiles.mapNotNull { tile -> tile.source }, art)
// The matcher runs over the review half before anything is minted: a lost layer's best candidate
// at or above the bar is that layer re-created under a new key, and the rig work over the lost
// layer's tile follows it.
val suggestions = suggestionsAgainstRead(model, sourceId, inventory, oldRasterOf, { key -> layersByKey[key]?.raster }, matcher)
val accepted = confidentMatches(suggestions, matchThreshold)
// The rigger's ignore marks live on the record's rows: a marked layer is left out of the rig however
// many reloads find it unbound.
val ignoredKeys = source.layers.filter { row -> row.ignored }.mapTo(HashSet()) { row -> row.key }
fun reboundFor(binding: SourceLayerRef): ReconcileResult.Rebound? {
val candidateKey = accepted[binding.layerKey] ?: return null
return ReconcileResult.Rebound(binding, candidateKey, suggestions.getValue(binding.layerKey).score)
}
val report =
ReconcileReport(
keyReport.results.mapNotNull { result ->
when (result) {
is ReconcileResult.Matched -> reboundFor(result.binding) ?: result
is ReconcileResult.NeedsReview ->
reboundFor(result.binding) ?: if (replacement != null) result.copy(reason = ReviewReason.SourceReplaced) else result
is ReconcileResult.Added -> result.takeIf { added -> added.layerKey !in accepted.values && added.layerKey !in ignoredKeys }
is ReconcileResult.Rebound -> result
}
},
)
val oldInventoryByKey = source.layers.associateBy { layer -> layer.key }
val taken = model.atlas.tiles.mapTo(HashSet()) { tile -> tile.id }
val replaced = ArrayList<ReplacedTile>()
val meshes = LinkedHashMap<DrawableId, DrawableMesh>()
val outgrown = ArrayList<DrawableId>()
val rasters = LinkedHashMap<AtlasTileId, LayerRaster>()
val notices = ArrayList<SourceArtImportNotice>()
val emptied = ArrayList<ReconcileResult>()
val visibility = LinkedHashMap<DrawableId, Boolean>()
for (tile in boundTiles) {
val ref = tile.source ?: continue
val candidateKey = accepted[ref.layerKey]
if (candidateKey != null) {
// The lost (or erased) layer's tile takes the re-created layer, the mesh over it carried the
// way a relink carries it.
val candidate = layersByKey[candidateKey] ?: continue
followVisibility(model, tile, oldInventoryByKey[ref.layerKey], candidate, visibility)
val candidateRef = SourceLayerRef(sourceId, candidateKey, stableKey = candidate.idIsStable)
val rebinding =
replaceTile(model, tile, candidate, candidateRef, oldInventoryByKey[ref.layerKey], options, oldRasterOf, taken, notices, force = true)
?: continue
replaced.add(rebinding.replaced)
rasters[rebinding.replaced.tile.id] = rebinding.raster
meshes.putAll(rebinding.meshes)
outgrown.addAll(rebinding.outgrown)
continue
}
val layer = layersByKey[ref.layerKey] ?: continue
followVisibility(model, tile, oldInventoryByKey[ref.layerKey], layer, visibility)
if (layer.raster.isFullyTransparent()) {
// Erased to nothing rather than deleted: the tile keeps its art and the binding goes to
// review, since the artist may have meant either (deleted the layer another way, or left
// it blank on purpose).
notices.add(SourceArtImportNotice.EmptyLayer(layer.name))
emptied.add(ReconcileResult.NeedsReview(ref, ReviewReason.LayerEmptied))
continue
}
val tileReplacement =
replaceTile(model, tile, layer, ref, oldInventoryByKey[ref.layerKey], options, oldRasterOf, taken, notices, force = false)
?: continue
replaced.add(tileReplacement.replaced)
rasters[tileReplacement.replaced.tile.id] = tileReplacement.raster
meshes.putAll(tileReplacement.meshes)
outgrown.addAll(tileReplacement.outgrown)
}
val addedKeys = report.results.filterIsInstance<ReconcileResult.Added>().mapTo(HashSet()) { result -> result.layerKey }
val added =
if (addedKeys.isEmpty() || replacement != null) {
null
} else {
// The whole file goes to the bridge with the gained layers named, so each new drawable is
// placed among the existing ones where the file puts it.
SourceArtImport.additionsFor(art, ArtSourceDescriptor(source.name, source.path, source.format), options, model, underSource = sourceId, layerKeys = addedKeys, inventory = inventory)
}
if (added != null) {
rasters.putAll(added.rasterByTile)
notices.addAll(added.notices)
}
// The file's bindings after the plan: a rebound tile binds its candidate.
val boundKeys = boundTiles.mapNotNullTo(HashSet()) { tile -> tile.source?.let { ref -> accepted[ref.layerKey] ?: ref.layerKey } }
val layers = inventoryWithMissing(source.layers, inventory, boundKeys, lostByReplacement = replacement != null)
val refreshed =
if (replacement == null) {
source.copy(layers = layers, contentHash = contentHash ?: source.contentHash, lastModified = lastModified ?: source.lastModified)
} else {
source.copy(
name = replacement.name,
path = replacement.path,
format = replacement.format,
layers = layers,
contentHash = contentHash,
lastModified = replacement.lastModified,
)
}
// The hash and the time say when the file was read, not what changed in it: masked out, so a save
// that changed no layer plans nothing (the watcher acknowledges it instead).
if (replacement == null && replaced.isEmpty() && added == null && refreshed.copy(contentHash = source.contentHash, lastModified = source.lastModified) == source) {
return null
}
val leftovers = suggestions.filterKeys { lostKey -> lostKey !in accepted }
return ReloadPlan(
ArtworkReload(refreshed, replaced, meshes, added?.additions, outgrown, drawableVisibility = visibility),
rasters,
ReconcileReport(report.results + emptied),
notices,
leftovers,
)
}
/**
* Plans rebinding every tile in [accepted] to the layer named beside it, with that layer's art pulled
* in - Match Automatically's step, a review row's accepted proposal, and the relink a tile chip
* makes, once per pair. A tile may come from another listed file (a relink across files): its old
* inventory row is read from that file, so the carried mesh still knows where its art sat. A pair
* whose tile the model lacks, whose key names no raster layer, or whose tile already holds exactly
* that binding over the same art is skipped; the file's record takes the inventory as just read, the
* lost rows the accepted tiles no longer bind dropped. The tiles in [retire] that are bound to a
* claimed key and carry no rig work ([retirableTiles]) leave with their drawables - the fresh
* drawable a reload minted for the layer, named by the proposal being accepted - so accepting after
* a reload merges rather than doubles; a tile with rig work over it is never retired, whatever the
* caller names. Null when the file is unknown or no pair could be applied.
*
* @param PuppetModel model The model the plan applies to.
* @param ArtSourceId sourceId The file whose layers the tiles move to.
* @param SourceArt art The file as just read.
* @param List accepted Each tile and the key of the layer it takes.
* @param SourceArtImportOptions options The threshold and margin a re-born quad uses.
* @param Function oldRasterOf The document's pixels for a tile, or null when it has none.
* @param String? contentHash The whole-file hash of the bytes [art] came from; null keeps the record's.
* @param List<ArtSourceLayer> inventory The inventory of [art], for a caller that already computed it; computed here by default.
* @param Long? lastModified The file's modification time when [art] was read; null keeps the record's.
* @param Set<AtlasTileId> retire The tiles the caller's proposal named as going with the move.
* @return ReloadPlan? The plan, or null when nothing could be rebound.
*/
fun planMatches(
model: PuppetModel,
sourceId: ArtSourceId,
art: SourceArt,
accepted: List<Pair<AtlasTileId, String>>,
options: SourceArtImportOptions,
oldRasterOf: (AtlasTileId) -> LayerRaster?,
contentHash: String? = null,
inventory: List<ArtSourceLayer> = SourceArtImport.inventoryOf(art),
lastModified: Long? = null,
retire: Set<AtlasTileId> = emptySet(),
): ReloadPlan? {
val source = model.sources.firstOrNull { candidate -> candidate.id == sourceId } ?: return null
val layersByKey = rasterLayersByKey(art)
val taken = model.atlas.tiles.mapTo(HashSet()) { tile -> tile.id }
val replaced = ArrayList<ReplacedTile>()
val meshes = LinkedHashMap<DrawableId, DrawableMesh>()
val outgrown = ArrayList<DrawableId>()
val rasters = LinkedHashMap<AtlasTileId, LayerRaster>()
val notices = ArrayList<SourceArtImportNotice>()
val results = ArrayList<ReconcileResult>()
val rebound = HashMap<AtlasTileId, String>()
val claiming = accepted.mapTo(HashSet()) { (tileId, _) -> tileId }
val retired = LinkedHashSet<AtlasTileId>()
for ((tileId, key) in accepted) {
val tile = model.atlas.tileById[tileId] ?: continue
val layer = layersByKey[key] ?: continue
val ref = SourceLayerRef(sourceId, key, stableKey = layer.idIsStable)
val oldRef = tile.source
val oldInventory = oldRef?.let { previous -> inventoryRowOf(model, previous) }
val replacement =
replaceTile(model, tile, layer, ref, oldInventory, options, oldRasterOf, taken, notices, force = oldRef != ref) ?: continue
replaced.add(replacement.replaced)
rasters[replacement.replaced.tile.id] = replacement.raster
meshes.putAll(replacement.meshes)
outgrown.addAll(replacement.outgrown)
results.add(ReconcileResult.Matched(ref, key))
rebound[tileId] = key
if (retire.isNotEmpty()) {
retired.addAll(retirableTiles(model, sourceId, key, except = claiming).filter { candidate -> candidate in retire })
}
}
if (replaced.isEmpty()) {
return null
}
// The file's bindings after the plan: a rebound tile binds its new key whichever file it came
// from, a retired tile nothing, every other tile of this file what it did.
val boundKeys =
model.atlas.tiles.filter { tile -> tile.id !in retired }.mapNotNullTo(HashSet()) { tile ->
rebound[tile.id] ?: tile.source?.takeIf { previous -> previous.sourceId == sourceId }?.layerKey
}
val layers = inventoryWithMissing(source.layers, inventory, boundKeys, untouchedKeys = boundKeys - rebound.values.toSet())
val refreshed = source.copy(layers = layers, contentHash = contentHash ?: source.contentHash, lastModified = lastModified ?: source.lastModified)
return ReloadPlan(ArtworkReload(refreshed, replaced, meshes, additions = null, outgrown = outgrown, retiredTiles = retired.toList()), rasters, ReconcileReport(results), notices)
}
/**
* The inventory row a binding names, read from the binding's own file - which need not be the file
* a tile is moving to.
*
* @param PuppetModel model The model the files are listed in.
* @param SourceLayerRef ref The binding.
* @return ArtSourceLayer? The row, or null when the file or the key is not listed.
*/
private fun inventoryRowOf(model: PuppetModel, ref: SourceLayerRef): ArtSourceLayer? =
model.sources.firstOrNull { candidate -> candidate.id == ref.sourceId }?.layers?.firstOrNull { row -> row.key == ref.layerKey }
/**
* Plans rebinding one tile to [ref]'s layer with that layer's art pulled in: the tile is replaced
* whenever the binding changes or the layer's art differs from what the tile holds, and the layer's
* file takes the inventory as just read. Null when the tile or the file is unknown, the layer is not
* a raster layer with art, or the tile already holds exactly this binding and this art - the caller
* then has nothing to pull and rewrites the binding alone if it differs. The one-pair form of
* [planMatches]; the replacement's binding says what the reader says about the key's strength.
*
* @param PuppetModel model The model the plan applies to.
* @param AtlasTileId tileId The tile being rebound.
* @param SourceLayerRef ref The binding it takes.
* @param SourceArt art The file [ref] names, as just read.
* @param SourceArtImportOptions options The threshold and margin a re-born quad uses.
* @param Function oldRasterOf The document's pixels for a tile, or null when it has none.
* @param List<ArtSourceLayer> inventory The inventory of [art], for a caller that already computed it; computed here by default.
* @return ReloadPlan? The plan, or null when there is nothing to pull.
*/
fun planRelink(
model: PuppetModel,
tileId: AtlasTileId,
ref: SourceLayerRef,
art: SourceArt,
options: SourceArtImportOptions,
oldRasterOf: (AtlasTileId) -> LayerRaster?,
inventory: List<ArtSourceLayer> = SourceArtImport.inventoryOf(art),
): ReloadPlan? = planMatches(model, ref.sourceId, art, listOf(tileId to ref.layerKey), options, oldRasterOf, inventory = inventory)
/**
* The raster layers of [art] by key - the only layers a tile can be bound to.
*
* @param SourceArt art The file as read.
* @return Map The raster layers, keyed by the reader's key.
*/
private fun rasterLayersByKey(art: SourceArt): Map<String, SourceLayer> =
art.layers.filter { layer -> layer.kind == SourceLayerKind.Raster }.associateBy { layer -> layer.id.raw }
/**
* Records, for the drawables over [tile], the visibility the file's eye toggle now asks for, when it
* changed since the last read: a drawable still showing the OLD file state follows the new one; a
* drawable the rigger toggled since (its flag already differs from the old state) is left alone, since
* that toggle is rig work. A document that never recorded the old state cannot tell the two apart and
* records nothing.
*
* @param PuppetModel model The model the tile lives in.
* @param AtlasTile tile The tile whose drawables are considered.
* @param ArtSourceLayer? oldInventory The layer's inventory row at the last read, or null.
* @param SourceLayer layer The layer as read now.
* @param MutableMap visibility Appended with each drawable that follows, keyed by its id.
*/
private fun followVisibility(
model: PuppetModel,
tile: AtlasTile,
oldInventory: ArtSourceLayer?,
layer: SourceLayer,
visibility: MutableMap<DrawableId, Boolean>,
) {
val oldVisible = oldInventory?.visible ?: return
if (oldVisible == layer.visible) {
return
}
for (drawable in model.drawables) {
if (drawable.atlasTileId == tile.id && drawable.isVisible == oldVisible) {
visibility[drawable.id] = layer.visible
}
}
}
/**
* Replaces one tile with [layer]'s art when the art differs from what the tile holds (or when
* [force] says the tile must change regardless, a rebinding), deciding each drawable's mesh over it.
*
* @param PuppetModel model The model the tile lives in.
* @param AtlasTile tile The tile being replaced.
* @param SourceLayer layer The layer whose art it takes.
* @param SourceLayerRef ref The binding the replacement carries.
* @param ArtSourceLayer? oldInventory The layer's inventory row at the last read, for the old
* art frame's canvas origin; null when the document never recorded one.
* @param SourceArtImportOptions options The threshold and margin a re-born quad uses.
* @param Function oldRasterOf The document's pixels for the tile.
* @param MutableSet taken Every tile id in use; the new id is added to it.
* @param MutableList notices Appended with anything the replacement could not carry.
* @param Boolean force Replace even when the art is unchanged.
* @return TileReplacement? The replacement, or null when there is nothing to change.
*/
private fun replaceTile(
model: PuppetModel,
tile: AtlasTile,
layer: SourceLayer,
ref: SourceLayerRef,
oldInventory: ArtSourceLayer?,
options: SourceArtImportOptions,
oldRasterOf: (AtlasTileId) -> LayerRaster?,
taken: MutableSet<AtlasTileId>,
notices: MutableList<SourceArtImportNotice>,
force: Boolean,
): TileReplacement? {
val raster = layer.raster
val old = oldRasterOf(tile.id)
val boundsUnchanged =
oldInventory != null &&
oldInventory.left == layer.bounds.left &&
oldInventory.top == layer.bounds.top &&
oldInventory.width == layer.bounds.width &&
oldInventory.height == layer.bounds.height
val pixelsUnchanged =
old != null && old.width == raster.width && old.height == raster.height && old.rgba.contentEquals(raster.rgba)
if (!force && boundsUnchanged && pixelsUnchanged) {
return null
}
// A layer erased to nothing has no art to give: the tile keeps what it has, and the note says why.
val analysis = layer.analyzeAlpha(alphaThreshold = options.alphaThreshold)
if (analysis == null) {
notices.add(SourceArtImportNotice.EmptyLayer(layer.name))
return null
}
val newId = reloadTileId(tile.id, taken)
taken.add(newId)
val newTile =
AtlasTile(
id = newId,
name = layer.name,
width = raster.width,
height = raster.height,
placement = null,
source = ref,
pinned = tile.pinned,
replaces = tile.id,
)
// The old art frame's canvas origin: the inventory's record of where the layer sat, else the
// layer's own bounds now (a document that never recorded it can only assume the art stayed put).
val oldLeft = (oldInventory?.left ?: layer.bounds.left).toFloat()
val oldTop = (oldInventory?.top ?: layer.bounds.top).toFloat()
val newLeft = layer.bounds.left.toFloat()
val newTop = layer.bounds.top.toFloat()
val opaqueOnCanvas =
LayerBounds(
left = layer.bounds.left + analysis.opaqueBounds.left,
top = layer.bounds.top + analysis.opaqueBounds.top,
width = analysis.opaqueBounds.width,
height = analysis.opaqueBounds.height,
)
val storedToArt = model.atlas.storedToArtAffineForTile(tile.id)
val meshes = LinkedHashMap<DrawableId, DrawableMesh>()
val outgrown = ArrayList<DrawableId>()
for (drawable in model.drawables) {
if (drawable.atlasTileId != tile.id) {
continue
}
val mesh = drawable.mesh ?: continue
if (storedToArt == null) {
// The tile's mapping cannot be read (a placement naming a page the atlas lacks); the mesh
// is left as it is rather than guessed at.
continue
}
val artUvs = applyUvAffine(mesh.uvs, storedToArt)
if (mesh.isUntouchedBirthQuad(artUvs, tile.width, tile.height, oldLeft, oldTop)) {
val reborn = SourceArtImport.birthMeshFor(layer, options.alphaThreshold, options.birthMeshMargin) ?: continue
meshes[drawable.id] = reborn
continue
}
// Canvas-attached: the vertex stays where it is and keeps sampling the canvas pixel under it,
// so the coordinate moves from the old art frame to the new one through the bounds delta.
val carried = FloatArray(artUvs.size)
for (vertex in 0 until artUvs.size / 2) {
carried[vertex * 2] = (artUvs[vertex * 2] * tile.width + oldLeft - newLeft) / raster.width
carried[vertex * 2 + 1] = (artUvs[vertex * 2 + 1] * tile.height + oldTop - newTop) / raster.height
}
meshes[drawable.id] = DrawableMesh(mesh.positions, carried, mesh.indices)
if (!covers(mesh.positions, opaqueOnCanvas)) {
outgrown.add(drawable.id)
}
}
return TileReplacement(ReplacedTile(tile.id, newTile), raster, meshes, outgrown)
}
/**
* Whether a mesh's canvas extent contains the opaque art's canvas rectangle, within half a pixel.
*
* @param FloatArray positions The mesh's canvas positions, x then y per vertex.
* @param LayerBounds opaque The opaque art's rectangle on the canvas.
* @return Boolean True when the art lies inside the mesh's reach.
*/
private fun covers(positions: FloatArray, opaque: LayerBounds): Boolean {
if (positions.size < 2) {
return false
}
var minX = Float.POSITIVE_INFINITY
var minY = Float.POSITIVE_INFINITY
var maxX = Float.NEGATIVE_INFINITY
var maxY = Float.NEGATIVE_INFINITY
for (vertex in 0 until positions.size / 2) {
val x = positions[vertex * 2]
val y = positions[vertex * 2 + 1]
minX = minOf(minX, x)
minY = minOf(minY, y)
maxX = maxOf(maxX, x)
maxY = maxOf(maxY, y)
}
return minX <= opaque.left + COVERAGE_TOLERANCE &&
minY <= opaque.top + COVERAGE_TOLERANCE &&
maxX >= opaque.left + opaque.width - COVERAGE_TOLERANCE &&
maxY >= opaque.top + opaque.height - COVERAGE_TOLERANCE
}
}
@@ -0,0 +1,276 @@
package org.umamo.reimport
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerRaster
import org.umamo.runtime.model.ArtSourceLayer
import kotlin.math.abs
import kotlin.math.max
import kotlin.math.min
/*
* The matcher over what the inventory knows plus, when the file could be read, the pixels: a layer
* that kept its pixels under a new name is recognized by its content hash outright; otherwise the
* name, the folder, where it sits on the canvas, how big it is, and what it looks like each vote,
* and the votes are averaged over the signals that could be read. Pixels are compared only for the
* candidates the metadata already likes, so a file of hundreds of layers costs a handful of small
* resamples, not hundreds of decodes.
*/
/** The weight each signal carries in the combined score. */
private const val WEIGHT_NAME = 0.35f
private const val WEIGHT_PATH = 0.10f
private const val WEIGHT_BOUNDS = 0.20f
private const val WEIGHT_SIZE = 0.10f
private const val WEIGHT_PIXELS = 0.25f
/** How many metadata-ranked candidates have their pixels compared. */
private const val PIXEL_CANDIDATES = 5
/** The grid both rasters are resampled to for the pixel comparison. */
private const val PIXEL_GRID = 32
/** The alpha byte at or above which a resampled pixel counts as opaque. */
private const val OPAQUE_ALPHA = 128
/**
* The [LayerMatcher] the Sources space and Match Automatically use. See the file comment.
*/
object InventoryLayerMatcher : LayerMatcher {
/** The confidence at or above which Match Automatically applies a match unasked, as a fraction. */
const val DEFAULT_THRESHOLD: Float = 0.7f
/**
* Ranks [candidates] for [missing]: metadata first, then the pixels of the best few.
*
* @param ArtSourceLayer missing The lost layer as the inventory recorded it.
* @param LayerRaster? missingRaster The pixels the document holds for it, or null.
* @param List<MatchCandidate> candidates The layers it could move to.
* @return List<LayerMatch> Every candidate scored, best first.
*/
override fun rank(missing: ArtSourceLayer, missingRaster: LayerRaster?, candidates: List<MatchCandidate>): List<LayerMatch> {
val byMetadata =
candidates
.map { candidate -> candidate to metadataSignals(missing, candidate.row) }
.sortedWith(compareByDescending<Pair<MatchCandidate, MatchSignals>> { (_, signals) -> combine(signals) }.thenBy { (candidate, _) -> candidate.row.name })
return byMetadata
.mapIndexed { index, (candidate, signals) ->
val pixels =
if (missingRaster != null && index < PIXEL_CANDIDATES) {
candidate.raster()?.let { raster -> pixelSimilarity(missingRaster, raster) }
} else {
null
}
val scored = signals.copy(pixels = pixels)
LayerMatch(candidate.row.key, combine(scored), scored)
}
.sortedWith(compareByDescending<LayerMatch> { match -> match.score }.thenBy { match -> candidates.first { candidate -> candidate.row.key == match.key }.row.name })
}
/**
* The signals the inventory alone can score.
*
* @param ArtSourceLayer missing The lost layer.
* @param ArtSourceLayer candidate The candidate.
* @return MatchSignals The scores, pixels unset.
*/
private fun metadataSignals(missing: ArtSourceLayer, candidate: ArtSourceLayer): MatchSignals {
val missingBounds = boundsOf(missing)
val candidateBounds = boundsOf(candidate)
val extentKnown = missingBounds.area > 0L && candidateBounds.area > 0L
return MatchSignals(
name = nameSimilarity(missing.name, candidate.name),
path = pathAgreement(missing.groupPath, candidate.groupPath),
bounds = if (extentKnown) missingBounds.intersectionOverUnion(candidateBounds) else null,
size = if (extentKnown) sizeSimilarity(missingBounds, candidateBounds) else null,
pixels = null,
hashEqual = missing.contentHash != null && missing.contentHash == candidate.contentHash,
)
}
/**
* The combined confidence: 1 on a content-hash match, else the weighted mean of the signals that
* could be scored.
*
* @param MatchSignals signals The per-signal scores.
* @return Float The confidence, 0..1.
*/
private fun combine(signals: MatchSignals): Float {
if (signals.hashEqual) {
return 1f
}
var total = WEIGHT_NAME * signals.name + WEIGHT_PATH * signals.path
var weight = WEIGHT_NAME + WEIGHT_PATH
val bounds = signals.bounds
if (bounds != null) {
total += WEIGHT_BOUNDS * bounds
weight += WEIGHT_BOUNDS
}
val size = signals.size
if (size != null) {
total += WEIGHT_SIZE * size
weight += WEIGHT_SIZE
}
val pixels = signals.pixels
if (pixels != null) {
total += WEIGHT_PIXELS * pixels
weight += WEIGHT_PIXELS
}
return (total / weight).coerceIn(0f, 1f)
}
/**
* A layer row's canvas rectangle.
*
* @param ArtSourceLayer row The row.
* @return LayerBounds Its rectangle.
*/
private fun boundsOf(row: ArtSourceLayer): LayerBounds = LayerBounds(row.left, row.top, row.width, row.height)
/**
* The smaller area over the larger.
*
* @param LayerBounds first One rectangle, with area.
* @param LayerBounds second The other, with area.
* @return Float The ratio, 0..1.
*/
private fun sizeSimilarity(first: LayerBounds, second: LayerBounds): Float =
min(first.area, second.area).toFloat() / max(first.area, second.area).toFloat()
}
/**
* How alike two layer names are: one minus the edit distance over the longer length, after lowercasing
* and collapsing whitespace, so "Hair Front" and "hair front" agree and "Hair Front" and "Hair
* Front 2" nearly do. Two empty names agree.
*
* @param String first One name.
* @param String second The other.
* @return Float The similarity, 0..1.
*/
fun nameSimilarity(first: String, second: String): Float {
val left = normalizeName(first)
val right = normalizeName(second)
if (left.isEmpty() && right.isEmpty()) {
return 1f
}
val longest = max(left.length, right.length)
return 1f - editDistance(left, right).toFloat() / longest.toFloat()
}
/**
* How far two folder paths agree: 1 for the same path, else the leading segments they share over the
* longer path's segment count (a layer that moved one folder deeper keeps most of its agreement).
*
* @param String first One slash-joined path ("" at the root).
* @param String second The other.
* @return Float The agreement, 0..1.
*/
fun pathAgreement(first: String, second: String): Float {
if (first == second) {
return 1f
}
val left = first.split('/').filter { segment -> segment.isNotEmpty() }
val right = second.split('/').filter { segment -> segment.isNotEmpty() }
val longest = max(left.size, right.size)
if (longest == 0) {
return 1f
}
var shared = 0
while (shared < min(left.size, right.size) && left[shared] == right[shared]) {
shared++
}
return shared.toFloat() / longest.toFloat()
}
/**
* How alike two rasters look, over a coarse grid each is resampled to: half the overlap of their opaque
* shapes, half one minus the mean color distance where both are opaque. Sizes need not agree - a
* layer that grew resamples to the same grid - and two empty rasters count as alike.
*
* @param LayerRaster first One raster.
* @param LayerRaster second The other.
* @return Float The similarity, 0..1.
*/
fun pixelSimilarity(first: LayerRaster, second: LayerRaster): Float {
if (first.width <= 0 || first.height <= 0 || second.width <= 0 || second.height <= 0) {
return 0f
}
var both = 0
var either = 0
var colorDistance = 0f
for (gridY in 0 until PIXEL_GRID) {
for (gridX in 0 until PIXEL_GRID) {
val firstIndex = sampleIndex(first, gridX, gridY)
val secondIndex = sampleIndex(second, gridX, gridY)
val firstOpaque = (first.rgba[firstIndex + 3].toInt() and 0xFF) >= OPAQUE_ALPHA
val secondOpaque = (second.rgba[secondIndex + 3].toInt() and 0xFF) >= OPAQUE_ALPHA
if (firstOpaque || secondOpaque) {
either++
}
if (firstOpaque && secondOpaque) {
both++
var channels = 0
for (channel in 0 until 3) {
channels += abs((first.rgba[firstIndex + channel].toInt() and 0xFF) - (second.rgba[secondIndex + channel].toInt() and 0xFF))
}
colorDistance += channels.toFloat() / (3f * 255f)
}
}
}
if (either == 0) {
return 1f
}
val shape = both.toFloat() / either.toFloat()
val color = if (both == 0) 0f else 1f - colorDistance / both.toFloat()
return (0.5f * shape + 0.5f * color).coerceIn(0f, 1f)
}
/**
* The byte offset of the raster pixel a grid cell samples (nearest neighbor).
*
* @param LayerRaster raster The raster.
* @param Int gridX The cell's column on the grid.
* @param Int gridY The cell's row on the grid.
* @return Int The offset of the pixel's red byte.
*/
private fun sampleIndex(raster: LayerRaster, gridX: Int, gridY: Int): Int {
val x = min(raster.width - 1, gridX * raster.width / PIXEL_GRID)
val y = min(raster.height - 1, gridY * raster.height / PIXEL_GRID)
return (y * raster.width + x) * 4
}
/**
* A name lowercased with its whitespace collapsed, so spelling differences that no artist means count for nothing.
*
* @param String name The name.
* @return String The normalized name.
*/
private fun normalizeName(name: String): String = name.trim().lowercase().split(Regex("\\s+")).filter { part -> part.isNotEmpty() }.joinToString(" ")
/**
* The Levenshtein distance between two strings.
*
* @param String first One string.
* @param String second The other.
* @return Int The edit distance.
*/
private fun editDistance(first: String, second: String): Int {
if (first.isEmpty()) {
return second.length
}
if (second.isEmpty()) {
return first.length
}
var previous = IntArray(second.length + 1) { column -> column }
var current = IntArray(second.length + 1)
for (row in 1..first.length) {
current[0] = row
for (column in 1..second.length) {
val substitution = previous[column - 1] + if (first[row - 1] == second[column - 1]) 0 else 1
current[column] = min(min(previous[column] + 1, current[column - 1] + 1), substitution)
}
val swap = previous
previous = current
current = swap
}
return previous[second.length]
}
@@ -0,0 +1,165 @@
package org.umamo.reimport
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Job
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import okio.FileSystem
import okio.Path
import okio.Path.Companion.toPath
import kotlin.coroutines.CoroutineContext
import kotlin.coroutines.EmptyCoroutineContext
/**
* A [SourceWatcher] that polls: every [pollMillis] each watched file is stat-ed through okio, and a
* change of size or modification time - or of existence - is a change. Polling rather than a
* platform notification API on purpose: okio's file system is the one that runs on every Kotlin
* target, JVM, Android, and Native alike, and a document watches a handful of files, so a stat per
* file per second is nothing. The coordinator above settles and hashes, so a poll only has to say
* "something happened"; an art program's temp-file-then-rename save changes the watched file's
* metadata like any other write.
*
* A file's baseline stamp is taken the moment it is watched, not at the loop's next tick: a caller
* that hashes the file right after subscribing (the coordinator's open-time check) waits on the
* subscription's [SourceWatcher.Subscription.awaitArmed], so the stamp precedes the hash and a save
* landing between the two is a change against the stamp rather than the stamp itself.
*
* Listeners are called in [scope]'s own dispatcher; the stats run under [statContext] (an IO
* dispatcher from the app), so a slow network drive never holds the UI.
*
* @param CoroutineScope scope The scope the poll loop and the deliveries run in.
* @param FileSystem fileSystem The file system the paths live on.
* @param Long pollMillis How often every watched file is stat-ed.
* @param CoroutineContext statContext Extra context for the stats; empty runs them in the scope.
*/
class PollingSourceWatcher(
private val scope: CoroutineScope,
private val fileSystem: FileSystem,
private val pollMillis: Long = DEFAULT_POLL_MILLIS,
private val statContext: CoroutineContext = EmptyCoroutineContext,
) : SourceWatcher, AutoCloseable {
/** What a stat sees of a file: absent, or its size and modification time. */
private data class Stamp(val size: Long?, val modifiedAtMillis: Long?)
/**
* One watch() call, the stamp it last saw, and the signal that it has seen one.
*
* @property String path The path as the caller gave it, echoed to the listener.
* @property Path filePath The path as okio reads it.
* @property ChangeListener listener Who hears the changes.
*/
private inner class Registration(val path: String, val filePath: Path, val listener: SourceWatcher.ChangeListener) : SourceWatcher.Subscription {
/** The stamp last seen, or null until the baseline stat lands. */
var last: Stamp? = null
/** Completed once [last] is set, or on close, so a waiter is never left hanging. */
val armed = CompletableDeferred<Unit>()
override suspend fun awaitArmed() {
armed.await()
}
override fun close() {
registrations.remove(this)
armed.complete(Unit)
if (registrations.isEmpty()) {
loop?.cancel()
loop = null
}
}
}
/** A subscription for a path that cannot be polled: armed from the start, hears nothing, closes to nothing. */
private object NoOpSubscription : SourceWatcher.Subscription {
override suspend fun awaitArmed() = Unit
override fun close() = Unit
}
private val registrations = ArrayList<Registration>()
private var loop: Job? = null
/**
* Begins polling [path]: its baseline stamp is taken at once (off the caller's thread), and every
* later tick compares against it.
*
* @param String path The file to watch; a uri gets a no-op subscription.
* @param ChangeListener listener Told in the scope whenever the file's size, modification time, or existence changes.
* @return Subscription The subscription.
*/
override fun watch(path: String, listener: SourceWatcher.ChangeListener): SourceWatcher.Subscription {
if (path.contains("://")) {
return NoOpSubscription
}
val filePath = runCatching { path.toPath() }.getOrNull() ?: return NoOpSubscription
val registration = Registration(path, filePath, listener)
registrations.add(registration)
scope.launch { baseline(registration) }
if (loop == null) {
loop = scope.launch { pollLoop() }
}
return registration
}
/** Stops polling; every subscription is dead after this. */
override fun close() {
for (registration in registrations.toList()) {
registration.armed.complete(Unit)
}
registrations.clear()
loop?.cancel()
loop = null
}
/**
* Takes a registration's baseline stamp and arms it. A tick that stat-ed the file first has already
* set the baseline; that one stands, since a change between the two stats must then be reported
* against it rather than folded into a later one.
*
* @param Registration registration The registration to baseline.
*/
private suspend fun baseline(registration: Registration) {
val stamp = withContext(statContext) { stampOf(registration.filePath) }
if (registration.last == null) {
registration.last = stamp
}
registration.armed.complete(Unit)
}
/**
* Stats every watched file each period and reports the ones whose stamp moved. A registration
* still waiting on its baseline takes this stat as it - a file is not "changed" by being watched.
*/
private suspend fun pollLoop() {
while (true) {
val snapshot = registrations.toList()
val stamps = withContext(statContext) { snapshot.map { registration -> stampOf(registration.filePath) } }
for ((registration, stamp) in snapshot.zip(stamps)) {
val previous = registration.last
registration.last = stamp
if (previous != null && previous != stamp && registration in registrations) {
registration.listener.onChanged(registration.path)
}
}
delay(pollMillis)
}
}
/**
* The stamp of one file now.
*
* @param Path filePath The file.
* @return Stamp Its size and modification time, both null when absent or unreadable.
*/
private fun stampOf(filePath: Path): Stamp {
val metadata = runCatching { fileSystem.metadataOrNull(filePath) }.getOrNull()
return Stamp(metadata?.size, metadata?.lastModifiedAtMillis)
}
private companion object {
/** How often the watched files are stat-ed; the coordinator's settle window sits on top of this. */
const val DEFAULT_POLL_MILLIS = 1_000L
}
}
@@ -0,0 +1,54 @@
package org.umamo.reimport
import org.umamo.runtime.model.SourceLayerRef
/*
* The reconcile's vocabulary. The binding itself is model state - `AtlasTile.source`, a
* SourceLayerRef naming the artwork file and the layer key the reader minted - so this module adds
* no identity type of its own: one key representation, minted by the readers, persisted on the tile,
* and diffed here. See CLAUDE.md "Source-art binding".
*/
/** Why a binding needs a person's decision rather than an automatic update. */
enum class ReviewReason {
/** The re-read art has no layer under the binding's key: removed, or renamed under a weak key. */
LayerMissing,
/** The file was repointed to art that mints different keys (another format), so the binding's key names nothing there. */
SourceReplaced,
/** The layer is still in the file but erased to nothing: deleted by another route, or meant to be blank - a person decides. */
LayerEmptied,
}
/**
* Outcome of reconciling one tile's binding against re-read art. Removals and renames are flagged,
* never silently applied - re-import must never destroy rig work (CLAUDE.md hard rule).
*/
sealed interface ReconcileResult {
/**
* The binding's layer is present under the same key; its art updates in place.
*
* @property SourceLayerRef binding The binding that matched.
* @property String layerKey The key it matched on - the binding's own, restated so a report
* reads uniformly with [Added].
*/
data class Matched(val binding: SourceLayerRef, val layerKey: String) : ReconcileResult
/** A layer the re-read art has that no tile is bound to; it becomes a new tile bound to it. */
data class Added(val layerKey: String) : ReconcileResult
/**
* A binding whose key the re-read art no longer has, rebound by the matcher to a layer no tile was
* bound to at or above the threshold - the lost layer re-created under a new key - so its tile
* takes that layer's art in the same step instead of a fresh drawable being minted beside it.
*
* @property SourceLayerRef binding The binding as it was, under the lost key.
* @property String layerKey The layer it moved to.
* @property Float score The matcher's confidence, 0..1.
*/
data class Rebound(val binding: SourceLayerRef, val layerKey: String, val score: Float) : ReconcileResult
/** Needs human review - surfaced, never deleted. */
data class NeedsReview(val binding: SourceLayerRef, val reason: ReviewReason) : ReconcileResult
}
@@ -0,0 +1,137 @@
package org.umamo.reimport
import org.umamo.format.art.LayerRaster
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceLayerKind
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.SourceLayerRef
/**
* Reconciles existing rig bindings (the model's per-tile [SourceLayerRef]s) against freshly-read
* source art - the headline "file refreshes" feature.
*
* Hard rule: re-import never destroys rig work. Matched layers update in place;
* added layers become new tiles bound to their layer; removed/renamed layers are flagged for review,
* never silently deleted. The output [ReconcileReport] is therefore a reviewable diff, not an applied
* mutation - [ArtworkReloadPlanner] turns the matched and added halves into a model delta.
*/
interface Reconciler {
fun reconcile(bindings: List<SourceLayerRef>, newArt: SourceArt): ReconcileReport
}
/**
* The result of a reconcile pass: every binding's outcome, plus a convenience view of the items a
* human must adjudicate before anything is applied.
*/
data class ReconcileReport(
val results: List<ReconcileResult>,
) {
/** Items that must not be auto-applied - removed/renamed/fuzzy-matched layers. */
val needsReview: List<ReconcileResult.NeedsReview>
get() = results.filterIsInstance<ReconcileResult.NeedsReview>()
}
/**
* The reconcile every reload runs: a binding matches when the re-read art has a raster layer under
* exactly its key, a raster layer no binding names is added, and a binding whose key the art no
* longer has needs review. Keys only - the readers mint them stable where the format allows (a CLIP
* or Krita uuid, Photoshop's lyid) and the fuzzy matching a weak key needs is a [LayerMatcher]'s work
* ([InventoryLayerMatcher], run over the review half by [suggestionsFor]), never this reconcile's.
*
* Non-raster layers (folders, text, adjustment layers) are invisible to it: they never became tiles
* at import, so they are neither matched nor added, and a raster layer that turned into one reads as
* missing, which is the honest answer.
*/
object KeyReconciler : Reconciler {
/**
* Classifies [bindings] against [newArt].
*
* @param List<SourceLayerRef> bindings The bindings of every tile bound to the re-read file.
* @param SourceArt newArt The file as just read.
* @return ReconcileReport One result per binding, then one per added layer, in the art's order.
*/
override fun reconcile(bindings: List<SourceLayerRef>, newArt: SourceArt): ReconcileReport {
val rasterKeys = LinkedHashSet<String>()
for (layer in newArt.layers.sortedBy { candidate -> candidate.order }) {
if (layer.kind == SourceLayerKind.Raster) {
rasterKeys.add(layer.id.raw)
}
}
val boundKeys = bindings.mapTo(HashSet()) { binding -> binding.layerKey }
val results = ArrayList<ReconcileResult>(bindings.size + rasterKeys.size)
for (binding in bindings) {
if (binding.layerKey in rasterKeys) {
results.add(ReconcileResult.Matched(binding, binding.layerKey))
} else {
results.add(ReconcileResult.NeedsReview(binding, ReviewReason.LayerMissing))
}
}
for (key in rasterKeys) {
if (key !in boundKeys) {
results.add(ReconcileResult.Added(key))
}
}
return ReconcileReport(results)
}
}
/**
* One layer a missing layer's binding could move to: its inventory row and, when the file could be
* read, its pixels on demand.
*
* @property ArtSourceLayer row The candidate as the inventory records it.
* @property Function raster Its pixels, decoded on first use; null when they cannot be read.
*/
class MatchCandidate(
val row: ArtSourceLayer,
val raster: () -> LayerRaster?,
)
/**
* How one candidate scored on each signal, kept beside the score so a person can see why.
*
* @property Float name Name similarity, 0..1.
* @property Float path Folder-path agreement, 0..1.
* @property Float? bounds Canvas overlap of the two rectangles, 0..1, or null when either has no known extent.
* @property Float? size The smaller area over the larger, 0..1, or null when either has no known extent.
* @property Float? pixels Pixel similarity, 0..1, or null when either side's pixels were not read.
* @property Boolean hashEqual Whether both rows carry a content hash and they agree - the same pixels.
*/
data class MatchSignals(
val name: Float,
val path: Float,
val bounds: Float?,
val size: Float?,
val pixels: Float?,
val hashEqual: Boolean,
)
/**
* One ranked candidate for a missing layer.
*
* @property String key The candidate's layer key.
* @property Float score The combined confidence, 0..1.
* @property MatchSignals signals The per-signal scores behind it.
*/
data class LayerMatch(
val key: String,
val score: Float,
val signals: MatchSignals,
)
/**
* The matcher for the hard case: a binding whose layer key the file no longer has, ranked against the
* file's layers no tile is bound to. Scored rather than decided - the caller applies a threshold or
* shows the ranking, and a person can always override.
*/
fun interface LayerMatcher {
/**
* Ranks [candidates] for [missing], best first.
*
* @param ArtSourceLayer missing The lost layer as the inventory recorded it.
* @param LayerRaster? missingRaster The pixels the document holds for it, or null.
* @param List<MatchCandidate> candidates The layers it could move to.
* @return List<LayerMatch> Every candidate with its score, best first; empty when there are none.
*/
fun rank(missing: ArtSourceLayer, missingRaster: LayerRaster?, candidates: List<MatchCandidate>): List<LayerMatch>
}
@@ -0,0 +1,56 @@
package org.umamo.reimport
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.applyUvAffine
import org.umamo.runtime.model.isUntouchedBirthQuad
import org.umamo.runtime.model.storedToArtAffineForTile
/*
* What a merge may remove. A reload that finds a layer no tile binds mints a fresh drawable for it;
* when that layer turns out to be a lost layer re-created (a duplicate, a paste), the rigged tile
* takes the layer and the fresh drawable is redundant - but only while nothing has been done to it.
* One predicate says so, read by the planner, the suggestions, and the Sources space alike, so the
* proposal, the step, and the chip's wording agree on what goes.
*/
/**
* Whether every drawable over [tileId] is exactly what an import mints and nothing more: a birth quad
* that still samples the whole tile at the layer's canvas place, no parent deformer, no clip mask
* either way, no glue, no geometry or channel keys, and no blend shapes. A tile no drawable samples
* qualifies too, since there is nothing over it to lose. Without [row], or without a readable mapping
* for the tile, the answer is false: the quad cannot be told untouched, so the drawable is kept; so is
* a tile the model lacks.
*
* @param AtlasTileId tileId The tile whose drawables are judged.
* @param ArtSourceLayer? row The tile's layer as the inventory records it, for the canvas origin the
* birth quad was born at; null when the inventory has no row for it.
* @return Boolean True when removing the tile's drawables would lose no rig work.
*/
fun PuppetModel.tileCarriesNoRigWork(tileId: AtlasTileId, row: ArtSourceLayer?): Boolean {
val tile = atlas.tileById[tileId] ?: return false
val over = drawables.filter { drawable -> drawable.atlasTileId == tileId }
if (over.isEmpty()) {
return true
}
if (row == null) {
return false
}
val storedToArt = atlas.storedToArtAffineForTile(tileId) ?: return false
val overIds = over.mapTo(HashSet()) { drawable -> drawable.id }
val masksAnother = drawables.any { drawable -> drawable.id !in overIds && drawable.maskedBy.any { maskId -> maskId in overIds } }
val glued = glues.any { glue -> glue.meshA in overIds || glue.meshB in overIds }
if (masksAnother || glued) {
return false
}
return over.all { drawable ->
val mesh = drawable.mesh ?: return@all false
drawable.parentDeformerId == null &&
drawable.maskedBy.isEmpty() &&
drawable.geometryGrid == null &&
drawable.channelGrids.isEmpty &&
drawable.blendShapes.isEmpty() &&
mesh.isUntouchedBirthQuad(applyUvAffine(mesh.uvs, storedToArt), tile.width, tile.height, row.left.toFloat(), row.top.toFloat())
}
}
@@ -0,0 +1,393 @@
package org.umamo.reimport
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Job
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import org.umamo.runtime.model.ArtSourceId
/*
* The policy between a file watcher and a reload: which files a document watches, when a burst of
* write events has settled, whether the settled file actually changed (its hash against what the
* document last read), and when the editor is idle enough to take the reload. Pure over injected
* time and hashing, so the whole of it runs under a test clock; the watcher and the hash are the only
* things that touch a disk.
*
* Every field is confined to the scope's dispatcher: the watcher delivers on it, the app calls on
* it, and the timers run on it. Nothing here is thread-safe by any other means.
*/
/**
* One listed artwork file the coordinator tracks.
*
* @property ArtSourceId sourceId The file's record in the model.
* @property String path The path the document recorded for it.
* @property String? recordedHash The content hash the document last read, or null when it never read bytes.
* @property Long? recordedModifiedAt The file's modification time (epoch milliseconds) the document
* recorded, or null; the stale-at-open check's fallback where no hash was recorded (a CMO3-origin file).
*/
class WatchedSource(
val sourceId: ArtSourceId,
val path: String,
val recordedHash: String?,
val recordedModifiedAt: Long? = null,
)
/** What the coordinator tells the app. */
sealed interface SourceWatchEvent {
/** Changed files have settled and the editor is idle: reload these as one operation. */
data class ReloadDue(val sourceIds: Set<ArtSourceId>) : SourceWatchEvent
/** Changed files have settled; the mode is notify, so a person decides. */
data class ChangedOnDisk(val sourceIds: Set<ArtSourceId>) : SourceWatchEvent
/** Files differed from their recorded hash when tracking began - edited while the document was closed. */
data class StaleAtOpen(val sourceIds: Set<ArtSourceId>) : SourceWatchEvent
/** A tracked file is no longer where the document recorded it. */
data class Missing(val sourceId: ArtSourceId) : SourceWatchEvent
}
/** How a reload the coordinator asked for ended, so it knows whether to wait, retry, or let go. */
enum class WatchedReloadResult {
/** The reload landed; the model's recorded hashes refresh through [SourceWatchCoordinator.track]. */
Applied,
/** The files were read and nothing in them changed the document; the hashes are acknowledged. */
NothingChanged,
/** An edit landed while the reload was planned; the coordinator tries again after a settle. */
Superseded,
/** The reload was refused or could not read the files; the person was told, so let go. */
Abandoned,
}
/** One tracked file's live state. */
private class TrackedSource(
var source: WatchedSource,
var handle: SourceWatcher.Subscription,
) {
/** The hash last read from the disk, or null when the file could not be read. */
var observedHash: String? = null
/** A disk hash a reload found nothing to change for; dropped rather than reported again. */
var acknowledgedHash: String? = null
/** Whether the last read found the file absent, so its return counts as a change. */
var missing: Boolean = false
/** The settle timer, restarted by every event. */
var settle: Job? = null
}
/**
* The reload policy over a [SourceWatcher]. See the file comment.
*
* @param CoroutineScope scope The scope everything runs in; its dispatcher confines the state.
* @param SourceWatcher watcher Where change notifications come from.
* @param Function hashOf The content hash of the file at a path, or null when unreadable.
* @param Function exists Whether a path exists, or null when the platform cannot say.
* @param Function isIdle Whether the editor can take a reload right now.
* @param Function mode The watch mode, read live at each decision.
* @param Long settleMillis How long after the last event a file is left alone before it is hashed.
* @param Long idlePollMillis How often the idle gate is re-asked while a reload waits.
*/
class SourceWatchCoordinator(
private val scope: CoroutineScope,
private val watcher: SourceWatcher,
private val hashOf: suspend (String) -> String?,
private val exists: suspend (String) -> Boolean?,
private val isIdle: () -> Boolean,
private val mode: () -> WatchMode,
private val settleMillis: Long = DEFAULT_SETTLE_MILLIS,
private val idlePollMillis: Long = DEFAULT_IDLE_POLL_MILLIS,
private val modifiedAtOf: suspend (String) -> Long? = { null },
) {
private val tracked = LinkedHashMap<ArtSourceId, TrackedSource>()
private val mutablePending = MutableStateFlow<Set<ArtSourceId>>(emptySet())
private val mutableSerial = MutableStateFlow(0)
private val mutableEvents = MutableSharedFlow<SourceWatchEvent>(extraBufferCapacity = EVENT_BUFFER)
private var dueWait: Job? = null
/** The files whose settled content differs from what the document last read, awaiting a reload. */
val pending: StateFlow<Set<ArtSourceId>> = mutablePending.asStateFlow()
/** Bumped whenever a file's presence changed, so a presence probe re-runs. */
val serial: StateFlow<Int> = mutableSerial.asStateFlow()
/** What the app acts on. */
val events: SharedFlow<SourceWatchEvent> = mutableEvents.asSharedFlow()
/**
* Tracks exactly [sources]: new files begin watching and are checked once against their recorded
* hash (a file edited while the document was closed is reported as stale), files no longer listed
* stop, and a file whose recorded hash caught up with the disk leaves the pending set. Called with
* the model's source list whenever it changes; with the mode off, tracks nothing.
*
* @param List<WatchedSource> sources The listed files with real paths.
*/
fun track(sources: List<WatchedSource>) {
if (mode() == WatchMode.Off) {
stopAll()
return
}
val wanted = sources.associateBy { source -> source.sourceId }
for (sourceId in tracked.keys.toList()) {
val entry = tracked.getValue(sourceId)
val next = wanted[sourceId]
if (next == null || next.path != entry.source.path) {
stop(sourceId)
}
}
val toCheck = ArrayList<TrackedSource>()
for (source in sources) {
val existing = tracked[source.sourceId]
if (existing != null) {
existing.source = source
// A reload landed: the record caught up with the disk, and this file is no longer owed one.
if (source.recordedHash != null && source.recordedHash == existing.observedHash) {
setPending(source.sourceId, false)
}
continue
}
val entry = TrackedSource(source, watcher.watch(source.path) { onChanged(source.sourceId) })
tracked[source.sourceId] = entry
toCheck.add(entry)
}
if (toCheck.isNotEmpty()) {
scope.launch { checkAtOpen(toCheck) }
}
}
/**
* Records how the reload asked for by a [SourceWatchEvent.ReloadDue] ended, for the files it named.
*
* @param Set sourceIds The files the reload covered.
* @param WatchedReloadResult result How it ended.
*/
fun reloadFinished(sourceIds: Set<ArtSourceId>, result: WatchedReloadResult) {
when (result) {
// The model's new hashes arrive through track(); nothing to do until then.
WatchedReloadResult.Applied -> Unit
WatchedReloadResult.NothingChanged, WatchedReloadResult.Abandoned -> {
for (sourceId in sourceIds) {
val entry = tracked[sourceId] ?: continue
entry.acknowledgedHash = entry.observedHash
setPending(sourceId, false)
}
}
WatchedReloadResult.Superseded -> {
for (sourceId in sourceIds) {
if (tracked.containsKey(sourceId)) {
onChanged(sourceId)
}
}
}
}
}
/** Stops watching everything and clears the pending set; the coordinator is done. */
fun close() {
stopAll()
dueWait?.cancel()
dueWait = null
}
/**
* A change notification for [sourceId]: restarts its settle timer.
*
* @param ArtSourceId sourceId The changed file.
*/
private fun onChanged(sourceId: ArtSourceId) {
val entry = tracked[sourceId] ?: return
entry.settle?.cancel()
entry.settle = scope.launch { settle(entry) }
}
/**
* Waits for the writes to stop, then reads the file's hash and decides: unreadable while present
* means the editor is still writing (wait again, up to a limit), absent means missing, a hash the
* document already holds or already acknowledged means nothing to do, and anything else is a change.
*
* @param TrackedSource entry The file.
*/
private suspend fun settle(entry: TrackedSource) {
var attempts = 0
while (true) {
delay(settleMillis)
val hash = hashOf(entry.source.path)
if (hash != null) {
val returned = entry.missing
entry.missing = false
entry.observedHash = hash
if (returned) {
mutableSerial.value = mutableSerial.value + 1
}
decide(entry, hash)
return
}
if (exists(entry.source.path) == false) {
if (!entry.missing) {
entry.missing = true
entry.observedHash = null
setPending(entry.source.sourceId, false)
mutableSerial.value = mutableSerial.value + 1
mutableEvents.tryEmit(SourceWatchEvent.Missing(entry.source.sourceId))
}
return
}
attempts++
if (attempts >= MAX_SETTLE_ATTEMPTS) {
return
}
}
}
/**
* A settled file's hash against what the document holds.
*
* @param TrackedSource entry The file.
* @param String hash Its content hash as just read.
*/
private fun decide(entry: TrackedSource, hash: String) {
val sourceId = entry.source.sourceId
if (hash == entry.source.recordedHash || hash == entry.acknowledgedHash) {
setPending(sourceId, false)
return
}
setPending(sourceId, true)
when (mode()) {
WatchMode.Auto -> requestReload()
WatchMode.Notify -> mutableEvents.tryEmit(SourceWatchEvent.ChangedOnDisk(setOf(sourceId)))
WatchMode.Off -> Unit
}
}
/**
* Arranges one reload of everything pending once the editor is idle; a wait already under way
* picks the new files up when it fires.
*/
private fun requestReload() {
if (dueWait?.isActive == true) {
return
}
dueWait =
scope.launch {
while (!isIdle()) {
delay(idlePollMillis)
}
val due = mutablePending.value
if (due.isNotEmpty()) {
mutableEvents.tryEmit(SourceWatchEvent.ReloadDue(due))
}
}
}
/**
* The one-time check a newly tracked file gets: its disk hash against the recorded one - or, for a
* file the document recorded no hash for (a CMO3-origin source), its modification time against the
* recorded one - so a file edited while the document was closed is reported before anyone asks.
* Batched per track call. The hash is the surer signal and wins wherever it exists; a time can move
* with no change in the bytes, which a reload then finds and acknowledges.
*
* Each file is hashed only once its watch is armed: the watcher's baseline stamp then precedes the
* hash, so a save landing between the two reads as a change against that stamp on the next tick
* instead of becoming the stamp and going unreported.
*
* @param List<TrackedSource> entries The files that just began tracking.
*/
private suspend fun checkAtOpen(entries: List<TrackedSource>) {
val stale = LinkedHashSet<ArtSourceId>()
for (entry in entries) {
entry.handle.awaitArmed()
if (!tracked.containsValue(entry)) {
continue
}
val hash = hashOf(entry.source.path)
if (hash == null) {
entry.missing = exists(entry.source.path) == false
continue
}
entry.observedHash = hash
if (isStaleAtOpen(entry.source, hash)) {
stale.add(entry.source.sourceId)
setPending(entry.source.sourceId, true)
}
}
if (stale.isNotEmpty()) {
mutableEvents.tryEmit(SourceWatchEvent.StaleAtOpen(stale))
}
}
/**
* Whether a newly tracked file differs from what the document recorded: by hash when one was
* recorded, else by modification time when one was, else not knowable.
*
* @param WatchedSource source The file as recorded.
* @param String hash Its hash on disk now.
* @return Boolean True when the file changed while the document was closed.
*/
private suspend fun isStaleAtOpen(source: WatchedSource, hash: String): Boolean {
val recordedHash = source.recordedHash
if (recordedHash != null) {
return hash != recordedHash
}
val recordedModifiedAt = source.recordedModifiedAt ?: return false
val modifiedAt = modifiedAtOf(source.path) ?: return false
return modifiedAt != recordedModifiedAt
}
/**
* Adds or removes [sourceId] from the pending set.
*
* @param ArtSourceId sourceId The file.
* @param Boolean pending Whether it awaits a reload.
*/
private fun setPending(sourceId: ArtSourceId, pending: Boolean) {
val current = mutablePending.value
val next = if (pending) current + sourceId else current - sourceId
if (next != current) {
mutablePending.value = next
}
}
/**
* Stops watching one file.
*
* @param ArtSourceId sourceId The file.
*/
private fun stop(sourceId: ArtSourceId) {
val entry = tracked.remove(sourceId) ?: return
entry.settle?.cancel()
entry.handle.close()
setPending(sourceId, false)
}
/** Stops watching every file. */
private fun stopAll() {
for (sourceId in tracked.keys.toList()) {
stop(sourceId)
}
}
private companion object {
/** How long a file is left alone after its last event before it is read - past the pause a save's writes leave. */
const val DEFAULT_SETTLE_MILLIS = 750L
/** How often the idle gate is re-asked while a reload waits for a gesture to end. */
const val DEFAULT_IDLE_POLL_MILLIS = 250L
/** How many settle windows an unreadable, present file is retried over before it is left for the next event. */
const val MAX_SETTLE_ATTEMPTS = 8
/** Events buffered for a slow collector before the newest are dropped. */
const val EVENT_BUFFER = 64
}
}
@@ -0,0 +1,42 @@
package org.umamo.reimport
/**
* Watches a source-art file for on-disk changes - the trigger of the headline "file refreshes"
* workflow.
*
* Modelled with a `fun interface` (SAM) listener and an [AutoCloseable] subscription so the contract
* carries no coroutine/Flow dependency at this layer. [PollingSourceWatcher] is the one
* implementation, over okio so it runs on every Kotlin target; a platform notification API could
* back another, but none is needed. The policy above it - settling a burst of events, hashing to
* skip a save that changed nothing, waiting for the editor to go idle - is [SourceWatchCoordinator]'s,
* so an implementation only has to say "this path changed".
*/
interface SourceWatcher {
/** Receives change notifications for a watched path. */
fun interface ChangeListener {
fun onChanged(path: String)
}
/**
* One watch of one file: close it to stop the notifications, and wait on [awaitArmed] before
* reading the file for a baseline of your own.
*/
interface Subscription : AutoCloseable {
/**
* Suspends until the watcher holds the file's baseline, from which point every change is
* reported. A change the watcher first sees while taking that baseline is folded into it, so a
* caller that reads the file BEFORE this returns and takes what it read as current could have the
* file change under it, unreported, in between. Returns at once for a closed subscription.
*/
suspend fun awaitArmed()
}
/**
* Begins watching [path]; close the returned subscription to stop.
*
* @param String path The file to watch.
* @param ChangeListener listener Told whenever the file is written, replaced, created, or deleted.
* @return Subscription The subscription; closing it stops the notifications.
*/
fun watch(path: String, listener: ChangeListener): Subscription
}
@@ -0,0 +1,209 @@
package org.umamo.reimport
import org.umamo.format.art.LayerRaster
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
/*
* What the document proposes for a binding its file no longer resolves. The inventory keeps a lost
* layer's row, flagged not present, for as long as a tile binds it - its name, bounds, and hash are
* what the matcher scores candidates against and what the Sources space names the row by - and the
* row leaves the inventory on the first refresh after nothing binds it. A suggestion is only ever a
* proposal: accepting one is the same relink a person makes by hand.
*/
/**
* The inventory a refresh records: [fresh] as read, plus every [previous] row whose key the fresh art
* lacks and a tile still binds, marked not present. A previous row already not present stays so, and
* a lost row nothing binds is dropped - there is no binding left to review. A row losing its presence
* in this refresh records why ([ArtSourceLayer.replaced]): the file was repointed at art that mints
* other keys when [lostByReplacement] says so, else the layer left the file.
*
* A plan that pulls art for some tiles and not others (a relink, an accepted match) names the bound
* keys it left alone in [untouchedKeys]: their previous rows are kept over the fresh ones, so a change
* to those layers the plan did not carry into their tiles is still seen by the next reload instead of
* being recorded as already taken.
*
* A row that reads as erased keeps the canvas frame its art last had: an art program saves an erased
* layer with a collapsed rectangle, and the tile still holds the art from the frame before, so a
* reload that finds the art back (an undo in the art program) measures it against that frame rather
* than against the collapse - which would carry every coordinate by the bogus difference.
*
* The rigger's ignore mark ([ArtSourceLayer.ignored]) is the document's, not the file's, so a fresh
* row carries its previous row's mark; a layer new to the file starts unmarked.
*
* @param List<ArtSourceLayer> previous The inventory as the document held it.
* @param List<ArtSourceLayer> fresh The inventory of the art as just read.
* @param Set<String> boundKeys The keys the tiles bound to this file carry after the plan.
* @param Set<String> untouchedKeys The bound keys whose tiles the plan did not update.
* @param Boolean lostByReplacement Whether the rows lost in this refresh were lost to a Replace Artwork.
* @return List<ArtSourceLayer> The rows to record, the fresh ones first in their order, then the kept lost ones in theirs.
*/
fun inventoryWithMissing(
previous: List<ArtSourceLayer>,
fresh: List<ArtSourceLayer>,
boundKeys: Set<String>,
untouchedKeys: Set<String> = emptySet(),
lostByReplacement: Boolean = false,
): List<ArtSourceLayer> {
val previousByKey = previous.associateBy { row -> row.key }
val freshKeys = fresh.mapTo(HashSet()) { row -> row.key }
val refreshed =
fresh.map { row ->
val previousRow = previousByKey[row.key]
val carried = if (previousRow?.ignored == true) row.copy(ignored = true) else row
when {
row.key in untouchedKeys && previousRow != null && previousRow.present -> previousRow
// The previous row already holds the last frame with art when it was itself erased.
row.empty && previousRow != null ->
carried.copy(left = previousRow.left, top = previousRow.top, width = previousRow.width, height = previousRow.height)
else -> carried
}
}
val lost =
previous
.filter { row -> row.key !in freshKeys && row.key in boundKeys }
.map { row -> if (row.present) row.copy(present = false, replaced = lostByReplacement) else row }
return refreshed + lost
}
/**
* The row the matcher scores a lost binding by: the inventory's not-present row when it kept one, else
* a row made from the tile itself - its name and size, at an unknown place - so a binding the
* inventory never listed (a CMO3 walk's stray) still gets candidates.
*
* @param ArtSourceLayer? row The inventory's row for the key, or null.
* @param AtlasTile tile The tile bound to it.
* @return ArtSourceLayer The row to score with.
*/
private fun missingRowFor(row: ArtSourceLayer?, tile: AtlasTile): ArtSourceLayer =
row ?: ArtSourceLayer(tile.source?.layerKey ?: tile.id.raw, tile.name, "", 0, 0, 0, 0, visible = true, present = false)
/**
* The best candidate for every binding to [sourceId] its inventory does not list as present - or lists
* as erased to nothing - keyed by the lost layer's key. The candidates are the file's present layers
* with art that no tile is bound to and the rigger has not ignored - never a bound one, since on the
* model alone nothing tells a re-created layer's fresh drawable from any other untouched drawable; the
* proposal that names a
* bound layer comes only from a reload that scored the binding before it minted the layer. Without
* rasters the ranking rests on the inventory alone; with them the matcher compares pixels too.
*
* @param PuppetModel model The document's model.
* @param ArtSourceId sourceId The file whose lost layers are scored.
* @param Function missingRasterOf The document's pixels for a tile, or null when unread.
* @param Function candidateRasterOf The pixels of a present layer by key, or null when unread.
* @param LayerMatcher matcher The matcher to rank with.
* @return Map<String, LayerMatch> Each lost binding's best match by its key; one with no candidate is absent.
*/
fun suggestionsFor(
model: PuppetModel,
sourceId: ArtSourceId,
missingRasterOf: (AtlasTileId) -> LayerRaster? = { null },
candidateRasterOf: (String) -> LayerRaster? = { null },
matcher: LayerMatcher = InventoryLayerMatcher,
): Map<String, LayerMatch> {
val source = model.sources.firstOrNull { candidate -> candidate.id == sourceId } ?: return emptyMap()
val boundTiles = model.atlas.tiles.filter { tile -> tile.source?.sourceId == sourceId }
val tileByKey = HashMap<String, AtlasTileId>()
for (tile in boundTiles) {
val key = tile.source?.layerKey ?: continue
tileByKey.putIfAbsent(key, tile.id)
}
val candidates =
source.layers
.filter { row -> row.present && !row.empty && !row.ignored && row.key !in tileByKey && row.width > 0 && row.height > 0 }
.map { row -> MatchCandidate(row) { candidateRasterOf(row.key) } }
if (candidates.isEmpty()) {
return emptyMap()
}
val rowByKey = source.layers.associateBy { row -> row.key }
val suggestions = LinkedHashMap<String, LayerMatch>()
for (tile in boundTiles) {
val key = tile.source?.layerKey ?: continue
if (key in suggestions || tileByKey[key] != tile.id) {
continue
}
val row = rowByKey[key]
if (row != null && row.present && !row.empty) {
continue
}
val best = matcher.rank(missingRowFor(row, tile), missingRasterOf(tile.id), candidates).firstOrNull() ?: continue
suggestions[key] = best
}
return suggestions
}
/**
* The suggestions for [sourceId]'s unresolved bindings against its art as just read: the record's
* inventory refreshed with [inventory] first - the lost rows kept, and every bound layer's previous row
* kept too, since nothing here carries a change into a tile - so a file never reloaded still scores,
* then [suggestionsFor] over that. What the reload planner scores before it mints, and what an
* operation that read the file publishes for the review chips.
*
* @param PuppetModel model The model as it stands.
* @param ArtSourceId sourceId The file.
* @param List<ArtSourceLayer> inventory The inventory of the file as just read.
* @param Function missingRasterOf The document's pixels for a tile, or null when unread.
* @param Function candidateRasterOf The pixels of a present layer by key, or null when unread.
* @param LayerMatcher matcher The matcher to rank with.
* @return Map<String, LayerMatch> Each unresolved binding's best match by its key; one with no candidate is absent.
*/
fun suggestionsAgainstRead(
model: PuppetModel,
sourceId: ArtSourceId,
inventory: List<ArtSourceLayer>,
missingRasterOf: (AtlasTileId) -> LayerRaster? = { null },
candidateRasterOf: (String) -> LayerRaster? = { null },
matcher: LayerMatcher = InventoryLayerMatcher,
): Map<String, LayerMatch> {
val source = model.sources.firstOrNull { candidate -> candidate.id == sourceId } ?: return emptyMap()
val boundKeys = model.atlas.tiles.filter { tile -> tile.source?.sourceId == sourceId }.mapNotNullTo(HashSet()) { tile -> tile.source?.layerKey }
val refreshed = source.copy(layers = inventoryWithMissing(source.layers, inventory, boundKeys, untouchedKeys = boundKeys))
val scoringModel = model.copy(sources = model.sources.map { candidate -> if (candidate.id == sourceId) refreshed else candidate })
return suggestionsFor(scoringModel, sourceId, missingRasterOf, candidateRasterOf, matcher)
}
/**
* The matches to apply out of [suggestions]: those at or above [threshold], best first, each candidate
* taken once - two lost layers that both prefer one candidate are settled in favor of the more
* confident, the other left for a person (its suggestion stands).
*
* @param Map<String, LayerMatch> suggestions The best candidate per lost key.
* @param Float threshold The confidence bar, 0..1, inclusive.
* @return Map<String, String> The candidate key each accepted lost key moves to, most confident first.
*/
fun confidentMatches(suggestions: Map<String, LayerMatch>, threshold: Float): Map<String, String> {
val takenCandidates = HashSet<String>()
val accepted = LinkedHashMap<String, String>()
for ((lostKey, match) in suggestions.entries.sortedByDescending { (_, match) -> match.score }) {
if (match.score < threshold || !takenCandidates.add(match.key)) {
continue
}
accepted[lostKey] = match.key
}
return accepted
}
/**
* The tiles a rebinding onto [candidateKey] may retire: every tile of [sourceId] bound to that key
* other than [except] whose drawables carry no rig work - the fresh drawable a reload minted for the
* layer before the lost layer's rig work claimed it. A tile with rig work over it stays bound; two
* tiles then share the layer, which a person sorts out. What the Sources space shows against a
* proposal naming a bound layer, and what a match re-checks before it retires anything.
*
* @param PuppetModel model The model the rebinding applies to.
* @param ArtSourceId sourceId The file.
* @param String candidateKey The layer being claimed.
* @param Set<AtlasTileId> except The tiles doing the claiming.
* @return List<AtlasTileId> The tiles to retire, in atlas order.
*/
fun retirableTiles(model: PuppetModel, sourceId: ArtSourceId, candidateKey: String, except: Set<AtlasTileId>): List<AtlasTileId> {
val row = model.sources.firstOrNull { source -> source.id == sourceId }?.layers?.firstOrNull { layer -> layer.key == candidateKey }
return model.atlas.tiles
.filter { tile -> tile.id !in except && tile.source?.sourceId == sourceId && tile.source?.layerKey == candidateKey }
.filter { tile -> model.tileCarriesNoRigWork(tile.id, row) }
.map { tile -> tile.id }
}
@@ -0,0 +1,32 @@
package org.umamo.reimport
/**
* What a document does when a watched artwork file changes on disk - the `import.watchMode` setting.
*
* @property String key The setting value.
*/
enum class WatchMode(val key: String) {
/** Reload the changed files as soon as the editor is idle, as one undo step. */
Auto("auto"),
/** Say that files changed and light the Reload button; nothing changes until it is pressed. */
Notify("notify"),
/** Watch nothing. */
Off("off"),
;
companion object {
/** The mode a fresh install runs with. */
val Default: WatchMode = Auto
/**
* The mode a setting value names, or [Default] for a value no mode carries (a stale or absent
* setting must not turn watching off by accident).
*
* @param String? key The setting value.
* @return WatchMode The mode.
*/
fun fromKey(key: String?): WatchMode = entries.firstOrNull { mode -> mode.key == key } ?: Default
}
}
@@ -0,0 +1,515 @@
package org.umamo.reimport
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerRaster
import org.umamo.interop.art.ArtSourceDescriptor
import org.umamo.interop.art.CanvasOffset
import org.umamo.interop.art.SourceArtImport
import org.umamo.interop.art.SourceArtImportNotice
import org.umamo.interop.art.SourceArtImportOptions
import org.umamo.interop.art.placedBy
import org.umamo.interop.art.placedFor
import org.umamo.runtime.model.ArtSource
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.OrgInsertion
import org.umamo.runtime.model.OrgSlot
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.SourceLayerRef
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertSame
import kotlin.test.assertTrue
/**
* The reload planner over a hand-built model and in-memory art: what a changed, unchanged, moved,
* added, and removed layer each turn into, and what a relink pulls.
*/
class ArtworkReloadPlannerTest {
private val source = ArtSourceId("art-0")
private val options = SourceArtImportOptions(alphaThreshold = 1, birthMeshMargin = 2)
private val ref1 = SourceLayerRef(source, "lyid:1", true)
private val ref2 = SourceLayerRef(source, "lyid:2", true)
private val tile1 = AtlasTileId("art-0/lyid:1")
private val tile2 = AtlasTileId("art-0/lyid:2")
/** Layer 1 at (10, 20), 4x4, and layer 2 at (30, 40), 4x4, as the document last read them. */
private val layer1 = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 4, 4), solidRaster(4, 4, 1))
private val layer2 = TestLayer("lyid:2", "Two", 1, LayerBounds(30, 40, 4, 4), solidRaster(4, 4, 2))
private val oldRasters = mapOf(tile1 to layer1.raster, tile2 to layer2.raster)
private val oldRasterOf: (AtlasTileId) -> LayerRaster? = { tileId -> oldRasters[tileId] }
/** The mesh an untouched drawable over layer 1 carries: its birth quad. */
private val birthQuad1: DrawableMesh = SourceArtImport.birthMeshFor(layer1, options.alphaThreshold, options.birthMeshMargin)!!
/** An edited mesh over layer 2: a triangle covering only the layer's top-left pixel. */
private val editedMesh2 = DrawableMesh(floatArrayOf(30f, 40f, 31f, 40f, 30f, 41f), floatArrayOf(0f, 0f, 0.25f, 0f, 0f, 0.25f), intArrayOf(0, 1, 2))
private fun drawable(id: String, tileId: AtlasTileId, mesh: DrawableMesh): Drawable =
Drawable(DrawableId(id), id, null, BlendMode.Normal, emptyList(), mesh, null, atlasTileId = tileId)
private fun model(): PuppetModel {
val drawables = listOf(drawable("d1", tile1, birthQuad1), drawable("d2", tile2, editedMesh2))
return PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables,
rootChildren = drawables.map { drawable -> OrgChild.Drawable(drawable.id) },
rootPartId = null,
atlas =
PuppetAtlas(
tiles =
listOf(
AtlasTile(tile1, "One", 4, 4, source = ref1, pinned = true),
AtlasTile(tile2, "Two", 4, 4, source = ref2),
),
),
sources = listOf(ArtSource(source, "a.psd", "/a.psd", "psd", SourceArtImport.inventoryOf(TestArt(listOf(layer1, layer2))))),
)
}
@Test
fun anUnchangedFilePlansNothing() {
assertNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(layer1, layer2)), options, oldRasterOf))
}
@Test
fun changedPixelsMintAReplacementAndRebirthAnUntouchedQuad() {
val repainted = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 6, 6), solidRaster(6, 6, 9))
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(repainted, layer2)), options, oldRasterOf))
val replaced = plan.reload.replacedTiles.single()
assertEquals(tile1, replaced.oldId)
assertEquals(AtlasTileId("art-0/lyid:1~1"), replaced.tile.id)
assertEquals(6, replaced.tile.width)
assertEquals(6, replaced.tile.height)
assertNull(replaced.tile.placement, "the replacement is unplaced until the pack")
assertTrue(replaced.tile.pinned, "the pin is carried")
assertEquals(tile1, replaced.tile.replaces)
assertEquals(ref1, replaced.tile.source)
assertSame(repainted.raster, plan.rasterByTile.getValue(replaced.tile.id))
val reborn = plan.reload.drawableMeshes.getValue(DrawableId("d1"))
val expected = SourceArtImport.birthMeshFor(repainted, options.alphaThreshold, options.birthMeshMargin)!!
assertContentEquals(expected.positions, reborn.positions, "an untouched birth quad is re-born over the new art")
assertContentEquals(expected.uvs, reborn.uvs)
assertTrue(plan.reload.outgrown.isEmpty())
assertNull(plan.reload.additions)
assertEquals(listOf(6, 6), plan.reload.source.layers.first { layer -> layer.key == "lyid:1" }.let { layer -> listOf(layer.width, layer.height) }, "the inventory is refreshed")
}
@Test
fun aMovedLayerUnderAnEditedMeshKeepsThePositionsAndCarriesTheCoordinates() {
// Layer 2 moved right by 3 and down by 1 with the same pixels: the mesh stays on the canvas and
// each vertex keeps sampling the canvas pixel under it, which is 3 art pixels further left now.
val moved = TestLayer("lyid:2", "Two", 1, LayerBounds(33, 41, 4, 4), layer2.raster)
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(layer1, moved)), options, oldRasterOf))
assertEquals(listOf(tile2), plan.reload.replacedTiles.map { replaced -> replaced.oldId })
val carried = plan.reload.drawableMeshes.getValue(DrawableId("d2"))
assertSame(editedMesh2.positions, carried.positions, "positions pass through by reference")
assertContentEquals(floatArrayOf(-0.75f, -0.25f, -0.5f, -0.25f, -0.75f, 0f), carried.uvs)
assertEquals(listOf(DrawableId("d2")), plan.reload.outgrown, "the moved art now reaches past the small mesh")
}
@Test
fun addedAndRemovedLayersLandUnderTheSameFile() {
val third = TestLayer("lyid:3", "Three", 2, LayerBounds(50, 50, 2, 2), solidRaster(2, 2, 3))
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(layer1, third)), options, oldRasterOf))
assertTrue(plan.reload.replacedTiles.isEmpty(), "neither kept layer changed")
val additions = assertNotNull(plan.reload.additions)
assertEquals(listOf(AtlasTileId("art-0/lyid:3")), additions.tiles.map { tile -> tile.id })
assertEquals(SourceLayerRef(source, "lyid:3", true), additions.tiles.single().source, "the added tile binds under the existing file")
assertEquals(listOf("ArtMesh1"), additions.drawables.map { drawable -> drawable.id.raw }, "ids mint past the model's")
assertEquals(listOf("lyid:1", "lyid:3", "lyid:2"), plan.reload.source.layers.map { layer -> layer.key }, "the removed layer's row is kept after the fresh ones while a tile binds it")
assertEquals(listOf(true, true, false), plan.reload.source.layers.map { layer -> layer.present })
assertTrue(plan.reload.source.layers.none { layer -> layer.replaced }, "a layer that left the file is not a replacement's loss")
assertEquals(listOf(ReconcileResult.NeedsReview(ref2, ReviewReason.LayerMissing)), plan.report.needsReview)
assertTrue(plan.rasterByTile.containsKey(AtlasTileId("art-0/lyid:3")))
}
/**
* A reload that finds a new layer inside a folder the document already holds as a part (the case
* of every CMO3-origin document, whose parts are the PSD's folders) lands it in that part and mints
* no part for any folder it added nothing to.
*/
@Test
fun anAddedLayerJoinsTheExistingPartOfItsFolderAndUntouchedFoldersMintNothing() {
val headLayer1 = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 4, 4), solidRaster(4, 4, 1), groupPath = "Head")
val bodyLayer2 = TestLayer("lyid:2", "Two", 1, LayerBounds(30, 40, 4, 4), solidRaster(4, 4, 2), groupPath = "Body")
val base = model()
val headPart = PartId("Part1")
val bodyPart = PartId("Part2")
val model =
base.copy(
parts =
listOf(
Part(headPart, "Head", listOf(OrgChild.Drawable(DrawableId("d1")))),
Part(bodyPart, "Body", listOf(OrgChild.Drawable(DrawableId("d2")))),
),
rootChildren = listOf(OrgChild.Part(headPart), OrgChild.Part(bodyPart)),
sources = listOf(ArtSource(source, "a.psd", "/a.psd", "psd", SourceArtImport.inventoryOf(TestArt(listOf(headLayer1, bodyLayer2))))),
)
val brow = TestLayer("lyid:3", "Brow", 2, LayerBounds(50, 50, 2, 2), solidRaster(2, 2, 3), groupPath = "Head")
val art = TestArt(listOf(headLayer1, bodyLayer2, brow), groups = listOf(TestGroup("Head"), TestGroup("Body"), TestGroup("Legs")))
val plan = assertNotNull(ArtworkReloadPlanner.plan(model, source, art, options, oldRasterOf))
val additions = assertNotNull(plan.reload.additions)
assertTrue(additions.parts.isEmpty(), "no part is minted: Head exists, and Body and Legs gained nothing")
assertTrue(additions.rootChildren.isEmpty())
assertEquals(
listOf(OrgInsertion(headPart, OrgChild.Drawable(DrawableId("ArtMesh1")), OrgSlot.After(OrgChild.Drawable(DrawableId("d1"))))),
additions.insertions,
"the brow joins the Head part, right after the layer above it in the file",
)
}
@Test
fun aRelinkPullsTheTargetLayer() {
val art = TestArt(listOf(layer1, layer2))
val plan = assertNotNull(ArtworkReloadPlanner.planRelink(model(), tile1, ref2, art, options, oldRasterOf))
val replaced = plan.reload.replacedTiles.single()
assertEquals(tile1, replaced.oldId)
assertEquals(ref2, replaced.tile.source, "the replacement carries the new binding")
assertEquals("Two", replaced.tile.name)
assertSame(layer2.raster, plan.rasterByTile.getValue(replaced.tile.id))
assertNull(ArtworkReloadPlanner.planRelink(model(), tile1, ref1, art, options, oldRasterOf), "the same binding over the same art pulls nothing")
assertNull(ArtworkReloadPlanner.planRelink(model(), tile1, SourceLayerRef(source, "lyid:9", true), art, options, oldRasterOf), "a layer the file lacks pulls nothing")
}
@Test
fun aRelinkAcrossFilesReadsTheOldRowFromTheTilesOwnFile() {
// Tile 2 (file a, layer at (30, 40)) moves to file b's layer at (50, 60). The edited mesh stays on
// the canvas, so its coordinates carry by the delta between the OLD row in file a and the new
// layer: read the old row from file b instead and the carry would be zero.
val other = ArtSourceId("art-1")
val layer3 = TestLayer("lyid:3", "Three", 0, LayerBounds(50, 60, 4, 4), solidRaster(4, 4, 3))
val otherArt = TestArt(listOf(layer3))
val model = model().let { base -> base.copy(sources = base.sources + ArtSource(other, "b.psd", "/b.psd", "psd", SourceArtImport.inventoryOf(otherArt))) }
val target = SourceLayerRef(other, "lyid:3", true)
val plan = assertNotNull(ArtworkReloadPlanner.planMatches(model, other, otherArt, listOf(tile2 to "lyid:3"), options, oldRasterOf))
val replaced = plan.reload.replacedTiles.single()
assertEquals(tile2, replaced.oldId)
assertEquals(target, replaced.tile.source)
val carried = plan.reload.drawableMeshes.getValue(DrawableId("d2"))
assertContentEquals(floatArrayOf(-5f, -5f, -4.75f, -5f, -5f, -4.75f), carried.uvs, "carried by the old row's origin in file a")
assertEquals(other, plan.reload.source.id, "the target file's record is the one refreshed")
assertEquals(listOf("lyid:3"), plan.reload.source.layers.map { layer -> layer.key })
assertTrue(plan.reload.source.layers.single().present, "the new binding's row is present, not lost")
}
/**
* A file placed on the document canvas (its record carries an offset) reloads in the document frame:
* the read is placed by the record before the planner sees it, so an unchanged file plans nothing, a
* repainted layer's untouched quad is re-born at the PLACED position, and the refreshed record keeps
* the offset.
*/
@Test
fun aPlacedFileReloadsInTheDocumentFrameAndKeepsItsOffset() {
// Placed 100 px right and 200 px DOWN the canvas, which is z = -200 in the world axes.
val offset = CanvasOffset(100, -200)
val placedArt = TestArt(listOf(layer1, layer2)).placedBy(offset)
val placedQuad1 = SourceArtImport.birthMeshFor(placedArt.layers[0], options.alphaThreshold, options.birthMeshMargin)!!
val base = model()
val placedModel =
base.copy(
drawables = base.drawables.map { drawable -> if (drawable.id == DrawableId("d1")) drawable.copy(mesh = placedQuad1) else drawable },
sources = listOf(ArtSource(source, "a.psd", "/a.psd", "psd", SourceArtImport.inventoryOf(placedArt), offsetX = offset.x, offsetZ = offset.z)),
)
val record = placedModel.sources.single()
assertEquals(110 to 220, record.layers.first().let { row -> row.left to row.top }, "the inventory is in the document frame")
assertNull(ArtworkReloadPlanner.plan(placedModel, source, TestArt(listOf(layer1, layer2)).placedFor(record), options, oldRasterOf), "the same file, placed the same way, plans nothing")
val repainted = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 6, 6), solidRaster(6, 6, 9))
val plan = assertNotNull(ArtworkReloadPlanner.plan(placedModel, source, TestArt(listOf(repainted, layer2)).placedFor(record), options, oldRasterOf))
assertEquals(listOf(tile1), plan.reload.replacedTiles.map { replaced -> replaced.oldId })
val reborn = plan.reload.drawableMeshes.getValue(DrawableId("d1"))
assertContentEquals(floatArrayOf(108f, 218f, 118f, 218f, 118f, 228f, 108f, 228f), reborn.positions, "re-born over the repainted art at its placed position")
assertEquals(offset.x to offset.z, plan.reload.source.offsetX to plan.reload.source.offsetZ, "the refreshed record keeps the offset")
assertEquals(110 to 220, plan.reload.source.layers.first { row -> row.key == "lyid:1" }.let { row -> row.left to row.top }, "and its rows stay in the document frame")
}
/**
* A relink onto a placed file carries the mesh by the OLD row in the tile's own file against the
* target layer's PLACED bounds, so the canvas-attached vertex keeps sampling the same canvas pixel.
*/
@Test
fun aRelinkOntoAPlacedFileCarriesAgainstThePlacedLayer() {
val other = ArtSourceId("art-1")
val layer3 = TestLayer("lyid:3", "Three", 0, LayerBounds(50, 60, 4, 4), solidRaster(4, 4, 3))
val otherRecord = ArtSource(other, "b.psd", "/b.psd", "psd", offsetX = -20, offsetZ = 19)
val otherArt = TestArt(listOf(layer3)).placedFor(otherRecord)
val model = model().let { base -> base.copy(sources = base.sources + otherRecord.copy(layers = SourceArtImport.inventoryOf(otherArt))) }
val plan = assertNotNull(ArtworkReloadPlanner.planMatches(model, other, otherArt, listOf(tile2 to "lyid:3"), options, oldRasterOf))
val carried = plan.reload.drawableMeshes.getValue(DrawableId("d2"))
// The target sits at (30, 41) placed: the old row's (30, 40) is one pixel above it, so every
// coordinate moves up by a quarter of the 4 px raster.
assertContentEquals(floatArrayOf(0f, -0.25f, 0.25f, -0.25f, 0f, 0f), carried.uvs, "carried against the placed bounds")
assertEquals(-20 to 19, plan.reload.source.offsetX to plan.reload.source.offsetZ, "the target's record keeps its offset")
}
/** The read's modification time rides the refreshed record like the hash, and alone plans nothing. */
@Test
fun theModificationTimeIsRecordedLikeTheHashAndAloneChangesNothing() {
val art = TestArt(listOf(layer1, layer2))
assertNull(ArtworkReloadPlanner.plan(model(), source, art, options, oldRasterOf, contentHash = "h", lastModified = 5L), "a time and hash alone plan nothing")
val repainted = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 4, 4), solidRaster(4, 4, 9))
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(repainted, layer2)), options, oldRasterOf, contentHash = "h", lastModified = 5L))
assertEquals(5L, plan.reload.source.lastModified)
assertEquals("h", plan.reload.source.contentHash)
val matched = assertNotNull(ArtworkReloadPlanner.planMatches(model(), source, art, listOf(tile1 to "lyid:2"), options, oldRasterOf, lastModified = 7L))
assertEquals(7L, matched.reload.source.lastModified)
val replaced = assertNotNull(ArtworkReloadPlanner.plan(model(), source, art, options, oldRasterOf, replacement = ArtSourceDescriptor("b.psd", "/b.psd", "psd", lastModified = 9L)))
assertEquals(9L, replaced.reload.source.lastModified, "a replacement records its own file's time")
}
/**
* A layer erased to nothing is not a deletion the reconcile can act on: the tile keeps its art, the
* inventory records the layer as empty, and the binding goes to review with its own reason - the
* artist may have deleted it this way or left it blank on purpose.
*/
@Test
fun aLayerErasedToNothingLeavesItsTileAndGoesToReview() {
val erased = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 4, 4), LayerRaster(4, 4, ByteArray(64)))
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(erased, layer2)), options, oldRasterOf))
assertTrue(plan.reload.replacedTiles.isEmpty())
assertEquals(listOf(SourceArtImportNotice.EmptyLayer("One")), plan.notices)
assertEquals(listOf(ReconcileResult.NeedsReview(ref1, ReviewReason.LayerEmptied)), plan.report.needsReview)
val row = plan.reload.source.layers.first { layer -> layer.key == "lyid:1" }
assertTrue(row.present && row.empty, "still in the file, recorded as empty")
assertEquals(listOf(10, 20, 4, 4), listOf(row.left, row.top, row.width, row.height), "with the frame the art last had, not the collapse")
// The artist undoes the erasure (the art program saves the layer collapsed to nothing meanwhile):
// the art is back where the tile's art came from, so nothing is replaced and no coordinate moves.
val collapsed = TestLayer("lyid:1", "One", 0, LayerBounds(0, 0, 0, 0), LayerRaster(0, 0, ByteArray(0)))
val whileErased = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(collapsed, layer2)), options, oldRasterOf))
val erasedModel = model().copy(sources = listOf(whileErased.reload.source))
val restored = assertNotNull(ArtworkReloadPlanner.plan(erasedModel, source, TestArt(listOf(layer1, layer2)), options, oldRasterOf))
assertTrue(restored.reload.replacedTiles.isEmpty(), "the same art at the same frame replaces nothing")
assertTrue(restored.reload.drawableMeshes.isEmpty(), "and moves no coordinate")
assertTrue(restored.report.needsReview.isEmpty(), "and the review is over")
val back = restored.reload.source.layers.first { layer -> layer.key == "lyid:1" }
assertTrue(back.present && !back.empty, "the row reads as art again")
}
@Test
fun acceptedMatchesReplaceTheirTilesInOnePlanAndDropTheLostRows() {
// Layer 2 was renamed under a new key and left for review by an earlier reload (its bar raised
// past the match), so its row is kept not present and the tile still binds the old key; the
// matcher's accepted pair moves the tile to the new layer.
val renamed = TestLayer("lyid:5", "Two (final)", 1, LayerBounds(30, 40, 4, 4), layer2.raster)
val previous = model().sources.single()
val lostRows = inventoryWithMissing(previous.layers, SourceArtImport.inventoryOf(TestArt(listOf(layer1, renamed))), boundKeys = setOf("lyid:1", "lyid:2"))
assertEquals(listOf(true, true, false), lostRows.map { layer -> layer.present })
val model = model().copy(sources = listOf(previous.copy(layers = lostRows)))
val plan = assertNotNull(ArtworkReloadPlanner.planMatches(model, source, TestArt(listOf(layer1, renamed)), listOf(tile2 to "lyid:5"), options, oldRasterOf))
val replaced = plan.reload.replacedTiles.single()
assertEquals(tile2, replaced.oldId)
assertEquals(SourceLayerRef(source, "lyid:5", true), replaced.tile.source)
assertEquals("Two (final)", replaced.tile.name)
assertEquals(listOf(ReconcileResult.Matched(SourceLayerRef(source, "lyid:5", true), "lyid:5")), plan.report.results)
assertEquals(listOf("lyid:1", "lyid:5"), plan.reload.source.layers.map { layer -> layer.key }, "the lost row leaves once nothing binds it")
assertNull(plan.reload.additions)
assertNull(ArtworkReloadPlanner.planMatches(model, source, TestArt(listOf(layer1, renamed)), listOf(tile2 to "lyid:9"), options, oldRasterOf), "a key the file lacks rebinds nothing")
}
@Test
fun aReplacementRewritesTheRecordReboundsTheConfidentBindingsAndFlagsTheRest() {
// The same art saved from another program: new keys for the same layers, so both bindings are
// rebound by their pixels inside the replace step itself.
val clipOne = TestLayer("clip:a", "One", 0, LayerBounds(10, 20, 4, 4), layer1.raster)
val clipTwo = TestLayer("clip:b", "Two", 1, LayerBounds(30, 40, 4, 4), layer2.raster)
val descriptor = ArtSourceDescriptor("a.clip", "/a.clip", "clip")
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(clipOne, clipTwo)), options, oldRasterOf, contentHash = "h", replacement = descriptor))
assertEquals("a.clip", plan.reload.source.name)
assertEquals("/a.clip", plan.reload.source.path)
assertEquals("clip", plan.reload.source.format)
assertEquals("h", plan.reload.source.contentHash)
assertEquals(listOf(tile1, tile2), plan.reload.replacedTiles.map { replaced -> replaced.oldId }, "both bindings rebound")
assertEquals(listOf(SourceLayerRef(source, "clip:a", true), SourceLayerRef(source, "clip:b", true)), plan.reload.replacedTiles.map { replaced -> replaced.tile.source })
assertEquals(listOf(ReconcileResult.Rebound(ref1, "clip:a", 1f), ReconcileResult.Rebound(ref2, "clip:b", 1f)), plan.report.results)
assertEquals(listOf("clip:a", "clip:b"), plan.reload.source.layers.map { layer -> layer.key }, "no lost row remains")
assertNull(plan.reload.additions)
// Art that resolves nothing: every binding is flagged as replaced, and the new file's layers stay
// unbound as the candidates the review matches against.
val strangers =
TestArt(
listOf(
TestLayer("clip:y", "Why", 0, LayerBounds(200, 200, 8, 8), solidRaster(8, 8, 7)),
TestLayer("clip:z", "Zed", 1, LayerBounds(300, 300, 8, 8), solidRaster(8, 8, 8)),
),
)
val flagged = assertNotNull(ArtworkReloadPlanner.plan(model(), source, strangers, options, oldRasterOf, contentHash = "h", replacement = descriptor))
assertEquals(listOf("clip:y", "clip:z", "lyid:1", "lyid:2"), flagged.reload.source.layers.map { layer -> layer.key })
assertEquals(listOf(true, true, false, false), flagged.reload.source.layers.map { layer -> layer.present })
assertEquals(listOf(false, false, true, true), flagged.reload.source.layers.map { layer -> layer.replaced }, "the rows the replace lost say so")
assertTrue(flagged.reload.replacedTiles.isEmpty(), "no binding resolved by key or by match")
assertNull(flagged.reload.additions, "the new file's layers stay unbound as the candidates the review matches against")
assertEquals(
listOf(ReconcileResult.NeedsReview(ref1, ReviewReason.SourceReplaced), ReconcileResult.NeedsReview(ref2, ReviewReason.SourceReplaced)),
flagged.report.needsReview,
)
// A same-format twin resolves by key and the plan still lands, if only to rewrite the record.
val twin = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(layer1, layer2)), options, oldRasterOf, replacement = ArtSourceDescriptor("b.psd", "/b.psd", "psd")))
assertEquals("b.psd", twin.reload.source.name)
assertTrue(twin.report.needsReview.isEmpty())
// The replacement stands in for the same art, so the record's placement on the canvas is kept.
val placedModel = model().let { base -> base.copy(sources = base.sources.map { record -> record.copy(offsetX = 5, offsetZ = 6) }) }
val placedTwin = assertNotNull(ArtworkReloadPlanner.plan(placedModel, source, TestArt(listOf(layer1, layer2)), options, oldRasterOf, replacement = ArtSourceDescriptor("b.psd", "/b.psd", "psd")))
assertEquals(5 to 6, placedTwin.reload.source.offsetX to placedTwin.reload.source.offsetZ, "the replaced record keeps its offset")
}
@Test
fun aReCreatedLayerIsReboundInTheReloadInsteadOfMinted() {
// Layer 1 deleted and re-created under a new key (a duplicate, a paste) with its pixels and place:
// the rigged tile follows it in the same step and nothing is minted beside it.
val recreated = TestLayer("lyid:3", "One", 0, LayerBounds(10, 20, 4, 4), layer1.raster)
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(recreated, layer2)), options, oldRasterOf))
val replaced = plan.reload.replacedTiles.single()
assertEquals(tile1, replaced.oldId)
assertEquals(SourceLayerRef(source, "lyid:3", true), replaced.tile.source)
assertEquals("One", replaced.tile.name)
assertSame(recreated.raster, plan.rasterByTile.getValue(replaced.tile.id))
assertNull(plan.reload.additions, "the re-created layer is not minted beside the rebound tile")
assertTrue(plan.reload.retiredTiles.isEmpty())
assertEquals(listOf(ReconcileResult.Rebound(ref1, "lyid:3", 1f), ReconcileResult.Matched(ref2, "lyid:2")), plan.report.results)
assertTrue(plan.report.needsReview.isEmpty())
assertEquals(listOf("lyid:3", "lyid:2"), plan.reload.source.layers.map { layer -> layer.key }, "no lost row is kept")
assertTrue(plan.reload.source.layers.all { layer -> layer.present })
assertTrue(plan.leftovers.isEmpty())
val expected = SourceArtImport.birthMeshFor(recreated, options.alphaThreshold, options.birthMeshMargin)!!
assertContentEquals(expected.positions, plan.reload.drawableMeshes.getValue(DrawableId("d1")).positions, "the untouched quad is re-born over the layer")
}
@Test
fun belowTheBarTheLayerIsMintedAndTheRowStaysForReviewWhileALowerBarRebinds() {
// Layer 1 deleted and an unrelated layer added: nothing near the bar, so the stranger is minted
// and the binding waits for a person; the same read at a lower bar rebinds instead.
val stranger = TestLayer("lyid:3", "Something else", 0, LayerBounds(200, 200, 8, 8), solidRaster(8, 8, 7))
val art = TestArt(listOf(stranger, layer2))
val atBar = assertNotNull(ArtworkReloadPlanner.plan(model(), source, art, options, oldRasterOf))
assertEquals(listOf(ReconcileResult.NeedsReview(ref1, ReviewReason.LayerMissing)), atBar.report.needsReview)
assertEquals(listOf(AtlasTileId("art-0/lyid:3")), assertNotNull(atBar.reload.additions).tiles.map { tile -> tile.id }, "the stranger is minted")
assertTrue(atBar.reload.replacedTiles.isEmpty())
assertEquals(listOf(true, true, false), atBar.reload.source.layers.map { layer -> layer.present })
val leftover = assertNotNull(atBar.leftovers["lyid:1"], "the proposal under the bar is handed out, scored before the mint")
assertEquals("lyid:3", leftover.key)
val lowered = assertNotNull(ArtworkReloadPlanner.plan(model(), source, art, options, oldRasterOf, matchThreshold = 0f))
assertEquals(tile1, lowered.reload.replacedTiles.single().oldId)
assertNull(lowered.reload.additions)
val rebound = lowered.report.results.filterIsInstance<ReconcileResult.Rebound>().single()
assertEquals("lyid:3", rebound.layerKey)
assertTrue(rebound.score < InventoryLayerMatcher.DEFAULT_THRESHOLD, "well under the default bar: ${rebound.score}")
assertTrue(lowered.report.needsReview.isEmpty())
assertTrue(lowered.leftovers.isEmpty())
}
@Test
fun twoLostKeysPreferringOneAddedLayerSettleOnTheMoreConfident() {
// Both layers deleted and one re-created with layer 1's pixels; the other lost binding hashes to
// it too (the same pixels), so the first in binding order takes it and the other waits.
val samePixels = TestLayer("lyid:2", "Two", 1, LayerBounds(30, 40, 4, 4), layer1.raster)
val model = model().copy(sources = listOf(ArtSource(source, "a.psd", "/a.psd", "psd", SourceArtImport.inventoryOf(TestArt(listOf(layer1, samePixels))))))
val rasters = mapOf(tile1 to layer1.raster, tile2 to layer1.raster)
val twin = TestLayer("lyid:3", "One", 0, LayerBounds(10, 20, 4, 4), layer1.raster)
val plan = assertNotNull(ArtworkReloadPlanner.plan(model, source, TestArt(listOf(twin)), options, { tileId -> rasters[tileId] }))
assertEquals(listOf(tile1), plan.reload.replacedTiles.map { replaced -> replaced.oldId }, "one binding takes the twin")
assertEquals(listOf(ReconcileResult.NeedsReview(ref2, ReviewReason.LayerMissing)), plan.report.needsReview, "the other stays for review")
assertNull(plan.reload.additions, "the twin is not minted, it was claimed")
assertEquals(listOf("lyid:3", "lyid:2"), plan.reload.source.layers.map { layer -> layer.key })
assertEquals(listOf(true, false), plan.reload.source.layers.map { layer -> layer.present })
}
@Test
fun anAcceptedMatchRetiresTheUntouchedDrawableOverItsLayerAndKeepsARiggedOne() {
// Layer 1 was re-created under lyid:3 and an earlier reload minted a fresh drawable for it (the
// match scored under the bar); accepting the reload's proposal now moves the rigged tile onto the
// layer and retires the fresh drawable with its tile - the tile the proposal named, and only
// when it still carries no rig work: the same fresh drawable, once edited, stays, and the layer
// is then bound twice for a person to sort out.
val recreated = TestLayer("lyid:3", "One", 0, LayerBounds(10, 20, 4, 4), layer1.raster)
val freshQuad = SourceArtImport.birthMeshFor(recreated, options.alphaThreshold, options.birthMeshMargin)!!
val tile3 = AtlasTileId("art-0/lyid:3")
val base = model()
val freshInventory =
inventoryWithMissing(base.sources.single().layers, SourceArtImport.inventoryOf(TestArt(listOf(recreated, layer2))), boundKeys = setOf("lyid:1", "lyid:2", "lyid:3"))
val afterMint =
base.copy(
drawables = base.drawables + drawable("d3", tile3, freshQuad),
rootChildren = base.rootChildren + OrgChild.Drawable(DrawableId("d3")),
atlas = base.atlas.copy(tiles = base.atlas.tiles + AtlasTile(tile3, "One", 4, 4, source = SourceLayerRef(source, "lyid:3", true))),
sources = listOf(base.sources.single().copy(layers = freshInventory)),
)
val rasters = oldRasters + (tile3 to recreated.raster)
val art = TestArt(listOf(recreated, layer2))
assertTrue(suggestionsFor(afterMint, source).isEmpty(), "on the model alone the bound layer is no candidate; the proposal is the reload's")
val plan = assertNotNull(ArtworkReloadPlanner.planMatches(afterMint, source, art, listOf(tile1 to "lyid:3"), options, { tileId -> rasters[tileId] }, retire = setOf(tile3)))
assertEquals(tile1, plan.reload.replacedTiles.single().oldId)
assertEquals(listOf(tile3), plan.reload.retiredTiles, "the fresh drawable's tile goes with the move")
assertEquals(listOf("lyid:3", "lyid:2"), plan.reload.source.layers.map { layer -> layer.key }, "the lost row leaves; the claimed layer stays bound through the rebound tile")
val unnamed = assertNotNull(ArtworkReloadPlanner.planMatches(afterMint, source, art, listOf(tile1 to "lyid:3"), options, { tileId -> rasters[tileId] }))
assertTrue(unnamed.reload.retiredTiles.isEmpty(), "a relink that names nothing retires nothing")
val editedFresh = DrawableMesh(floatArrayOf(10f, 20f, 11f, 20f, 10f, 21f), floatArrayOf(0f, 0f, 0.25f, 0f, 0f, 0.25f), intArrayOf(0, 1, 2))
val edited = afterMint.copy(drawables = afterMint.drawables.map { drawable -> if (drawable.id.raw == "d3") drawable.copy(mesh = editedFresh) else drawable })
val kept = assertNotNull(ArtworkReloadPlanner.planMatches(edited, source, art, listOf(tile1 to "lyid:3"), options, { tileId -> rasters[tileId] }, retire = setOf(tile3)))
assertTrue(kept.reload.retiredTiles.isEmpty(), "rig work over the layer is never removed, whatever the proposal named")
}
@Test
fun anIgnoredLayerIsNeverMintedUntilTheMarkIsCleared() {
// A third layer the rigger ignored (a sketch kept in the file): every reload finds it unbound and
// leaves it out, the mark rides the refreshed inventory, and the matcher never proposes it; clear
// the mark and the next reload mints it.
val third = TestLayer("lyid:3", "Sketch", 2, LayerBounds(50, 50, 2, 2), solidRaster(2, 2, 3))
val art = TestArt(listOf(layer1, layer2, third))
val base = model()
val listed = base.copy(sources = listOf(base.sources.single().copy(layers = SourceArtImport.inventoryOf(art).map { row -> if (row.key == "lyid:3") row.copy(ignored = true) else row })))
assertNull(ArtworkReloadPlanner.plan(listed, source, art, options, oldRasterOf), "nothing to do: the ignored layer is not an addition")
val repainted = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 4, 4), solidRaster(4, 4, 9))
val plan = assertNotNull(ArtworkReloadPlanner.plan(listed, source, TestArt(listOf(repainted, layer2, third)), options, oldRasterOf))
assertNull(plan.reload.additions, "the ignored layer stays out while another layer reloads")
assertTrue(plan.report.results.none { result -> result is ReconcileResult.Added })
assertTrue(plan.reload.source.layers.first { layer -> layer.key == "lyid:3" }.ignored, "the mark rides the refreshed inventory")
assertTrue(suggestionsFor(listed, source).isEmpty(), "and the matcher never proposes it")
val cleared = listed.copy(sources = listOf(listed.sources.single().copy(layers = listed.sources.single().layers.map { row -> row.copy(ignored = false) })))
val minted = assertNotNull(ArtworkReloadPlanner.plan(cleared, source, art, options, oldRasterOf))
assertEquals(listOf(AtlasTileId("art-0/lyid:3")), assertNotNull(minted.reload.additions).tiles.map { tile -> tile.id }, "un-ignored, the next reload mints it")
}
@Test
fun aLayerEyeToggleFollowsIntoAnUntouchedDrawableAndLeavesAToggledOne() {
// Layer 1 hidden in the file: d1 still shows the state the file last had (shown), so it follows,
// with no tile replaced. Hidden by the rigger first, d1 already differs from that state - its
// toggle is rig work - so the file's toggle changes nothing.
val hidden = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 4, 4), layer1.raster, visible = false)
val plan = assertNotNull(ArtworkReloadPlanner.plan(model(), source, TestArt(listOf(hidden, layer2)), options, oldRasterOf))
assertEquals(mapOf(DrawableId("d1") to false), plan.reload.drawableVisibility)
assertTrue(plan.reload.replacedTiles.isEmpty(), "an eye toggle replaces no tile")
assertEquals(false, plan.reload.source.layers.first { layer -> layer.key == "lyid:1" }.visible, "the inventory records the new state")
// d1 hidden while the inventory still says shown: the rigger's own toggle, so the file hiding the
// layer changes nothing; once the inventory records hidden too, the file showing it again is
// followed, since d1 then shows exactly the state the file last had.
val riggerHid = model().let { base -> base.copy(drawables = base.drawables.map { drawable -> if (drawable.id.raw == "d1") drawable.copy(isVisible = false) else drawable }) }
val untouched = assertNotNull(ArtworkReloadPlanner.plan(riggerHid, source, TestArt(listOf(hidden, layer2)), options, oldRasterOf))
assertTrue(untouched.reload.drawableVisibility.isEmpty(), "a drawable the rigger already hid is left alone")
assertEquals(false, untouched.reload.source.layers.first { layer -> layer.key == "lyid:1" }.visible, "while the inventory still records the file's state")
val recorded = riggerHid.copy(sources = listOf(untouched.reload.source))
assertNull(ArtworkReloadPlanner.plan(recorded, source, TestArt(listOf(hidden, layer2)), options, oldRasterOf), "recorded and unchanged: nothing to do")
val shownAgain = assertNotNull(ArtworkReloadPlanner.plan(recorded, source, TestArt(listOf(layer1, layer2)), options, oldRasterOf))
assertEquals(mapOf(DrawableId("d1") to true), shownAgain.reload.drawableVisibility, "shown again in the file, a hidden drawable that matches the recorded state follows back")
}
}
@@ -0,0 +1,108 @@
package org.umamo.reimport
import org.umamo.format.art.LayerRaster
import org.umamo.runtime.model.ArtSourceLayer
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* The inventory matcher's signals and their combination: a hash match is certain, a rename at the
* same place scores high, a namesake far away scores low, pixels count when they can be read, and
* only the best few candidates pay for a pixel comparison.
*/
class InventoryLayerMatcherTest {
private fun row(key: String, name: String, left: Int, top: Int, width: Int, height: Int, groupPath: String = "", hash: String? = null): ArtSourceLayer =
ArtSourceLayer(key, name, groupPath, left, top, width, height, visible = true, contentHash = hash)
private fun candidate(row: ArtSourceLayer, raster: LayerRaster? = null): MatchCandidate = MatchCandidate(row) { raster }
@Test
fun aContentHashMatchIsCertainWhateverTheNameAndPlace() {
val missing = row("lyid:1", "Hair Front", 10, 20, 40, 40, hash = "abc")
val ranked =
InventoryLayerMatcher.rank(
missing,
null,
listOf(candidate(row("lyid:7", "Hair Front", 12, 22, 40, 40)), candidate(row("lyid:9", "Untitled 3", 500, 500, 8, 8, hash = "abc"))),
)
assertEquals("lyid:9", ranked.first().key)
assertEquals(1f, ranked.first().score)
assertTrue(ranked.first().signals.hashEqual)
}
@Test
fun aRenamedLayerAtTheSamePlaceScoresAboveTheThresholdAndANamesakeFarAwayBelowIt() {
val missing = row("lyid:1", "Hair Front", 10, 20, 40, 40, groupPath = "Head")
val ranked =
InventoryLayerMatcher.rank(
missing,
null,
listOf(candidate(row("lyid:2", "Hair Front 2", 10, 20, 40, 40, groupPath = "Head")), candidate(row("lyid:3", "Hair Front", 900, 900, 400, 10, groupPath = "Body"))),
)
assertEquals(listOf("lyid:2", "lyid:3"), ranked.map { match -> match.key })
assertTrue(ranked[0].score >= InventoryLayerMatcher.DEFAULT_THRESHOLD, "renamed in place: ${ranked[0].score}")
assertTrue(ranked[1].score < InventoryLayerMatcher.DEFAULT_THRESHOLD, "a namesake elsewhere: ${ranked[1].score}")
assertNull(ranked[0].signals.pixels, "no pixels were read")
}
@Test
fun aRowWithNoKnownExtentScoresOnNameAndPathAlone() {
val missing = row("lyid:1", "Hair Front", 0, 0, 0, 0)
val match = InventoryLayerMatcher.rank(missing, null, listOf(candidate(row("lyid:2", "Hair Front", 300, 300, 40, 40)))).single()
assertNull(match.signals.bounds)
assertNull(match.signals.size)
assertEquals(1f, match.score, "the name and path agree, and nothing else could be scored")
}
@Test
fun nameSimilarityIgnoresCaseAndSpacing() {
assertEquals(1f, nameSimilarity("Hair Front", "hair front"))
assertEquals(1f, nameSimilarity("", ""))
assertTrue(nameSimilarity("Hair Front", "Hair Front 2") > 0.8f)
assertTrue(nameSimilarity("Eye L", "Mouth") < 0.3f)
}
@Test
fun pathAgreementCountsSharedLeadingFolders() {
assertEquals(1f, pathAgreement("", ""))
assertEquals(1f, pathAgreement("Head/Hair", "Head/Hair"))
assertEquals(0.5f, pathAgreement("Head", "Head/Hair"))
assertEquals(0f, pathAgreement("Head", "Body"))
}
@Test
fun pixelSimilarityCountsShapeAndColorAcrossSizes() {
val white = solidRaster(4, 4, 0xFF.toByte())
assertEquals(1f, pixelSimilarity(white, white))
assertEquals(1f, pixelSimilarity(white, solidRaster(16, 8, 0xFF.toByte())), "the same picture at another size resamples alike")
val black = solidRaster(4, 4, 0)
assertEquals(0.5f, pixelSimilarity(white, black), "the same shape, opposite colors")
val empty = LayerRaster(4, 4, ByteArray(64))
assertEquals(0f, pixelSimilarity(white, empty), "nothing in common")
assertEquals(1f, pixelSimilarity(empty, empty))
assertEquals(0f, pixelSimilarity(white, LayerRaster(0, 0, ByteArray(0))))
}
@Test
fun pixelsJoinTheScoreWhenReadAndOnlyForTheBestFewCandidates() {
val missing = row("lyid:1", "Hair", 0, 0, 4, 4)
val missingRaster = solidRaster(4, 4, 0xFF.toByte())
var reads = 0
val candidates =
(0 until 8).map { index ->
MatchCandidate(row("lyid:${index + 2}", "Hair $index", 0, 0, 4, 4)) {
reads++
if (index == 6) missingRaster else solidRaster(4, 4, 0)
}
}
val ranked = InventoryLayerMatcher.rank(missing, missingRaster, candidates)
assertEquals(5, reads, "only the top five metadata candidates are pixel-scored")
assertEquals(5, ranked.count { match -> match.signals.pixels != null })
val withPixels = ranked.filter { match -> match.signals.pixels != null }
val without = ranked.filter { match -> match.signals.pixels == null }
assertTrue(withPixels.all { match -> match.score < without.first().score }, "opposite pixels pull a candidate below one whose pixels were not read")
assertTrue(without.map { match -> match.key }.contains("lyid:8"), "the seventh candidate by name was never read")
}
}
@@ -0,0 +1,35 @@
package org.umamo.reimport
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.SourceLayerKind
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.SourceLayerRef
import kotlin.test.Test
import kotlin.test.assertEquals
/** The reconcile by key: matched, added, and missing, with non-raster layers invisible to it. */
class KeyReconcilerTest {
private val source = ArtSourceId("art-0")
private fun layer(key: String, order: Int, kind: SourceLayerKind = SourceLayerKind.Raster): TestLayer =
TestLayer(key, key, order, LayerBounds(0, 0, 2, 2), solidRaster(2, 2, 1), kind = kind)
@Test
fun bindingsMatchByKeyAndTheRestClassify() {
val art = TestArt(listOf(layer("lyid:2", 0), layer("lyid:1", 1), layer("text", 2, SourceLayerKind.Text), layer("lyid:9", 3)))
val bindings = listOf(SourceLayerRef(source, "lyid:1", true), SourceLayerRef(source, "lyid:7", true), SourceLayerRef(source, "text", true))
val report = KeyReconciler.reconcile(bindings, art)
assertEquals(
listOf(
ReconcileResult.Matched(bindings[0], "lyid:1"),
ReconcileResult.NeedsReview(bindings[1], ReviewReason.LayerMissing),
ReconcileResult.NeedsReview(bindings[2], ReviewReason.LayerMissing),
ReconcileResult.Added("lyid:2"),
ReconcileResult.Added("lyid:9"),
),
report.results,
"bindings first in their order, then the added raster layers in the art's order; a folder is neither",
)
assertEquals(2, report.needsReview.size)
}
}
@@ -0,0 +1,108 @@
package org.umamo.reimport
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.test.advanceTimeBy
import kotlinx.coroutines.test.runTest
import okio.Path.Companion.toPath
import okio.fakefilesystem.FakeFileSystem
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* The polling watcher over an in-memory file system under the test clock: a write, a temp-file-then-
* rename replace, and a delete each reach the listener of the file they touch; a sibling's write does
* not; watching a file is not a change; and a closed subscription hears nothing.
*/
@OptIn(ExperimentalCoroutinesApi::class)
class PollingSourceWatcherTest {
@Test
fun changesToTheWatchedFileReachItsListenerAndNothingElseDoes() =
runTest {
val fileSystem = FakeFileSystem()
val directory = "/art".toPath()
val watched = directory / "art.psd"
val sibling = directory / "other.psd"
fileSystem.createDirectories(directory)
fileSystem.write(watched) { writeUtf8("1") }
fileSystem.write(sibling) { writeUtf8("1") }
val watcher = PollingSourceWatcher(this, fileSystem, pollMillis = 100)
val deliveries = ArrayList<String>()
val handle = watcher.watch(watched.toString()) { path -> deliveries.add(path) }
advanceTimeBy(250)
assertTrue(deliveries.isEmpty(), "watching a file is not a change")
// A write that grows the file.
fileSystem.write(watched) { writeUtf8("22") }
advanceTimeBy(100)
assertEquals(listOf(watched.toString()), deliveries, "the listener hears its own path")
// A sibling's write is not this file's change.
fileSystem.write(sibling) { writeUtf8("22") }
advanceTimeBy(300)
assertEquals(1, deliveries.size, "a sibling file is nobody's change")
// The save an art program performs: a temporary file renamed over the watched one.
val temporary = directory / "art.psd.tmp"
fileSystem.write(temporary) { writeUtf8("333") }
fileSystem.atomicMove(temporary, watched)
advanceTimeBy(100)
assertEquals(2, deliveries.size, "a rename-replace is a change")
// A delete is a change, and so is the file returning.
fileSystem.delete(watched)
advanceTimeBy(100)
assertEquals(3, deliveries.size, "a delete is a change")
fileSystem.write(watched) { writeUtf8("4444") }
advanceTimeBy(100)
assertEquals(4, deliveries.size, "a return is a change")
// Closed: silence, and the poll loop is gone.
handle.close()
fileSystem.write(watched) { writeUtf8("55555") }
advanceTimeBy(300)
assertEquals(4, deliveries.size, "a closed subscription hears nothing")
watcher.close()
}
@Test
fun aFileWatchedWhileTheLoopRunsIsBaselinedAtOnceSoASaveBeforeTheNextTickIsSeen() =
runTest {
// The loop is already ticking for one file. A second file joins mid-period and is saved
// before the next tick: its baseline must be the stamp at watch time, not the tick's, or the
// save would become the baseline and never be reported.
val fileSystem = FakeFileSystem()
val directory = "/art".toPath()
val first = directory / "a.psd"
val second = directory / "b.psd"
fileSystem.createDirectories(directory)
fileSystem.write(first) { writeUtf8("1") }
fileSystem.write(second) { writeUtf8("1") }
val watcher = PollingSourceWatcher(this, fileSystem, pollMillis = 100)
val deliveries = ArrayList<String>()
watcher.watch(first.toString()) { path -> deliveries.add(path) }
advanceTimeBy(150)
assertTrue(deliveries.isEmpty())
val late = watcher.watch(second.toString()) { path -> deliveries.add(path) }
late.awaitArmed()
fileSystem.write(second) { writeUtf8("22") }
advanceTimeBy(100)
assertEquals(listOf(second.toString()), deliveries, "the save after the watch-time baseline is a change")
// Arming is a one-time event; a closed subscription arms too, so a waiter never hangs.
late.close()
late.awaitArmed()
watcher.close()
}
@Test
fun aUriGetsANoOpHandle() =
runTest {
val watcher = PollingSourceWatcher(this, FakeFileSystem(), pollMillis = 100)
watcher.watch("content://documents/1") {}.close()
advanceTimeBy(300)
watcher.close()
}
}
@@ -0,0 +1,84 @@
package org.umamo.reimport
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.AtlasPage
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.Glue
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.SourceLayerRef
import kotlin.test.Test
import kotlin.test.assertFalse
import kotlin.test.assertTrue
/** What counts as rig work over a tile: anything beyond the birth an import mints. */
class RigWorkTest {
private val source = ArtSourceId("art-0")
private val tile = AtlasTileId("t")
private val row = ArtSourceLayer("k", "K", "", 50, 50, 10, 10, visible = true)
/** The birth quad over a 10 x 10 tile whose layer sits at (50, 50). */
private val birthQuad = DrawableMesh(floatArrayOf(50f, 50f, 60f, 50f, 60f, 60f, 50f, 60f), floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f, 0f, 1f), intArrayOf(0, 1, 2, 0, 2, 3))
/** The same quad with one corner dragged. */
private val moved = DrawableMesh(floatArrayOf(50f, 50f, 60f, 50f, 61f, 61f, 50f, 60f), floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f, 0f, 1f), intArrayOf(0, 1, 2, 0, 2, 3))
private val boundTile = AtlasTile(tile, "K", 10, 10, source = SourceLayerRef(source, "k", true))
private fun drawable(id: String, mesh: DrawableMesh? = birthQuad, tileId: AtlasTileId? = tile): Drawable =
Drawable(DrawableId(id), id, null, BlendMode.Normal, emptyList(), mesh, null, atlasTileId = tileId)
private fun model(vararg drawables: Drawable, atlas: PuppetAtlas = PuppetAtlas(tiles = listOf(boundTile)), glues: List<Glue> = emptyList()): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables.toList(),
rootChildren = emptyList(),
rootPartId = null,
atlas = atlas,
glues = glues,
sources = emptyList(),
)
@Test
fun aFreshBirthOverTheTileCarriesNoRigWorkAndAnythingMoreDoes() {
assertTrue(model(drawable("d")).tileCarriesNoRigWork(tile, row), "a birth quad sampling the whole tile at the layer's place")
assertTrue(model().tileCarriesNoRigWork(tile, row), "nothing over the tile at all")
assertTrue(model(drawable("d"), drawable("e")).tileCarriesNoRigWork(tile, row), "two fresh births")
assertFalse(model(drawable("d")).tileCarriesNoRigWork(tile, row = null), "without the row the quad cannot be told untouched")
assertFalse(model(drawable("d")).tileCarriesNoRigWork(AtlasTileId("nope"), row), "a tile the model lacks")
assertFalse(model(drawable("d", mesh = moved)).tileCarriesNoRigWork(tile, row), "a moved vertex")
assertFalse(model(drawable("d"), drawable("e", mesh = moved)).tileCarriesNoRigWork(tile, row), "one of two moved")
assertFalse(model(drawable("d", mesh = null)).tileCarriesNoRigWork(tile, row), "no mesh to judge")
assertFalse(model(drawable("d").copy(parentDeformerId = DeformerId("warp"))).tileCarriesNoRigWork(tile, row), "a parent deformer")
assertFalse(model(drawable("d").copy(maskedBy = listOf(DrawableId("other")))).tileCarriesNoRigWork(tile, row), "a clip mask on it")
assertFalse(model(drawable("d"), drawable("other", tileId = null).copy(maskedBy = listOf(DrawableId("d")))).tileCarriesNoRigWork(tile, row), "it masking another")
assertFalse(model(drawable("d").copy(geometryGrid = KeyformGrid(emptyList(), emptyList()))).tileCarriesNoRigWork(tile, row), "geometry keys")
assertFalse(
model(drawable("d").copy(channelGrids = ChannelGrids(mapOf(FormChannel.OPACITY to KeyformGrid(emptyList(), emptyList()))))).tileCarriesNoRigWork(tile, row),
"a channel track",
)
assertFalse(
model(drawable("d").copy(blendShapes = listOf(BlendShapeBinding(ParameterId("p"), floatArrayOf(0f), 0, listOf<MeshForm?>(null))))).tileCarriesNoRigWork(tile, row),
"a blend shape",
)
assertFalse(model(drawable("d"), glues = listOf(Glue(DrawableId("d"), DrawableId("other"), emptyList()))).tileCarriesNoRigWork(tile, row), "a glue")
val degenerate = PuppetAtlas(pages = listOf(AtlasPage(16, 16)), tiles = listOf(boundTile.copy(placement = AtlasPlacement(0, 0f, 0f, 0f, 0f, 0f))))
assertFalse(model(drawable("d"), atlas = degenerate).tileCarriesNoRigWork(tile, row), "a mapping that cannot be read")
}
}
@@ -0,0 +1,334 @@
package org.umamo.reimport
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.Job
import kotlinx.coroutines.launch
import kotlinx.coroutines.test.TestScope
import kotlinx.coroutines.test.advanceTimeBy
import kotlinx.coroutines.test.advanceUntilIdle
import kotlinx.coroutines.test.runTest
import org.umamo.runtime.model.ArtSourceId
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* The reload policy under a test clock: settling, the hash check that drops a no-op save, the idle
* gate, the three modes, a missing and returning file, the open-time staleness check, and how a
* finished reload feeds back. The watcher is a fake that fires on demand; the disk is a map.
*/
@OptIn(ExperimentalCoroutinesApi::class)
class SourceWatchCoordinatorTest {
private val fileA = ArtSourceId("art-0")
private val fileB = ArtSourceId("art-1")
/**
* A watcher the test fires by hand, recording who watches what. Every subscription is armed at
* once unless [armByHand] is set, in which case the test arms it through [arm].
*/
private class FakeWatcher(private val armByHand: Boolean = false) : SourceWatcher {
val listeners = LinkedHashMap<String, MutableList<SourceWatcher.ChangeListener>>()
val armed = LinkedHashMap<String, CompletableDeferred<Unit>>()
override fun watch(path: String, listener: SourceWatcher.ChangeListener): SourceWatcher.Subscription {
listeners.getOrPut(path) { ArrayList() }.add(listener)
val signal = armed.getOrPut(path) { CompletableDeferred() }
if (!armByHand) {
signal.complete(Unit)
}
return object : SourceWatcher.Subscription {
override suspend fun awaitArmed() {
signal.await()
}
override fun close() {
listeners[path]?.remove(listener)
signal.complete(Unit)
}
}
}
fun fire(path: String) {
listeners[path].orEmpty().toList().forEach { listener -> listener.onChanged(path) }
}
fun arm(path: String) {
armed.getValue(path).complete(Unit)
}
}
/** The disk: a hash per path, or null for a file that cannot be read; absent means missing. */
private class Disk {
val hashByPath = HashMap<String, String?>()
val modifiedAtByPath = HashMap<String, Long>()
fun hashOf(path: String): String? = hashByPath[path]
fun exists(path: String): Boolean = hashByPath.containsKey(path)
fun modifiedAt(path: String): Long? = modifiedAtByPath[path]
}
/**
* The coordinator over the TEST scope itself (this coroutines-test version does not advance
* backgroundScope work on advanceUntilIdle), so every test ends by calling [finish].
*/
private class Harness(scope: TestScope, val mode: () -> WatchMode, val idle: () -> Boolean = { true }, armByHand: Boolean = false) {
val watcher = FakeWatcher(armByHand)
val disk = Disk()
val events = ArrayList<SourceWatchEvent>()
val coordinator =
SourceWatchCoordinator(
scope = scope,
watcher = watcher,
hashOf = { path -> disk.hashOf(path) },
exists = { path -> disk.exists(path) },
isIdle = idle,
mode = mode,
settleMillis = 100,
idlePollMillis = 10,
modifiedAtOf = { path -> disk.modifiedAt(path) },
)
private val collector: Job = scope.launch { coordinator.events.collect { event -> events.add(event) } }
fun finish() {
coordinator.close()
collector.cancel()
}
}
private fun TestScope.harness(mode: WatchMode = WatchMode.Auto, idle: () -> Boolean = { true }, armByHand: Boolean = false): Harness =
Harness(this, { mode }, idle, armByHand)
@Test
fun theOpenTimeHashWaitsForTheWatchToArm() =
runTest {
// The hash must not be read before the watcher holds its baseline: a save between the two
// would otherwise become the baseline and go unreported. Here the disk changes while the
// watch is still arming, and the check reads the state AFTER arming.
val harness = harness(armByHand = true)
harness.disk.hashByPath["/a.psd"] = "h1"
harness.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h1")))
advanceTimeBy(1_000)
assertTrue(harness.events.isEmpty(), "nothing is read while the watch arms")
assertTrue(harness.coordinator.pending.value.isEmpty())
harness.disk.hashByPath["/a.psd"] = "h2"
harness.watcher.arm("/a.psd")
advanceTimeBy(1)
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.StaleAtOpen(setOf(fileA))), harness.events, "the check ran once armed and saw the change")
assertEquals(setOf(fileA), harness.coordinator.pending.value)
harness.finish()
}
@Test
fun aWatchStoppedWhileArmingIsSkippedWithoutHanging() =
runTest {
val harness = harness(armByHand = true)
harness.disk.hashByPath["/a.psd"] = "h2"
harness.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h1")))
harness.coordinator.track(emptyList())
advanceTimeBy(1_000)
assertTrue(harness.events.isEmpty(), "an untracked file is never checked")
harness.finish()
}
@Test
fun aSettledChangeReloadsOnceAndANoOpSaveIsDropped() =
runTest {
val harness = harness()
harness.disk.hashByPath["/a.psd"] = "h1"
harness.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h1")))
advanceUntilIdle()
assertTrue(harness.events.isEmpty(), "a file matching its record is quiet at open")
// A save that changed nothing: the hash is the record's.
harness.watcher.fire("/a.psd")
advanceTimeBy(200)
advanceUntilIdle()
assertTrue(harness.events.isEmpty(), "the same hash is dropped")
assertTrue(harness.coordinator.pending.value.isEmpty())
// A real change, written in two bursts inside one settle window.
harness.disk.hashByPath["/a.psd"] = "h2"
harness.watcher.fire("/a.psd")
advanceTimeBy(50)
harness.watcher.fire("/a.psd")
advanceTimeBy(50)
assertTrue(harness.events.isEmpty(), "the second event restarted the settle")
advanceTimeBy(100)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.ReloadDue(setOf(fileA))), harness.events)
assertEquals(setOf(fileA), harness.coordinator.pending.value)
// The reload landed: the model's record caught up, and tracking it clears the debt.
harness.coordinator.reloadFinished(setOf(fileA), WatchedReloadResult.Applied)
harness.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h2")))
advanceUntilIdle()
assertTrue(harness.coordinator.pending.value.isEmpty())
harness.finish()
}
@Test
fun anUnreadableFileWaitsAndAMissingOneIsReported() =
runTest {
val harness = harness()
harness.disk.hashByPath["/a.psd"] = "h1"
harness.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h1")))
advanceUntilIdle()
// Mid-write: present but unreadable for two windows, then done.
harness.disk.hashByPath["/a.psd"] = null
harness.watcher.fire("/a.psd")
advanceTimeBy(250)
assertTrue(harness.events.isEmpty(), "an unreadable file is waited for")
harness.disk.hashByPath["/a.psd"] = "h2"
advanceTimeBy(100)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.ReloadDue(setOf(fileA))), harness.events)
harness.events.clear()
// Deleted: reported once, the pending debt dropped, the presence serial bumped.
val serialBefore = harness.coordinator.serial.value
harness.disk.hashByPath.remove("/a.psd")
harness.watcher.fire("/a.psd")
advanceTimeBy(100)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.Missing(fileA)), harness.events)
assertTrue(harness.coordinator.pending.value.isEmpty())
assertEquals(serialBefore + 1, harness.coordinator.serial.value)
harness.events.clear()
// Back, with new content: a change, and the serial moves again.
harness.disk.hashByPath["/a.psd"] = "h3"
harness.watcher.fire("/a.psd")
advanceTimeBy(100)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.ReloadDue(setOf(fileA))), harness.events)
assertEquals(serialBefore + 2, harness.coordinator.serial.value)
harness.finish()
}
@Test
fun autoWaitsForTheEditorToGoIdleAndGathersWhatArrivedMeanwhile() =
runTest {
var idle = false
val harness = harness(idle = { idle })
harness.disk.hashByPath["/a.psd"] = "h1"
harness.disk.hashByPath["/b.psd"] = "k1"
harness.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h1"), WatchedSource(fileB, "/b.psd", "k1")))
advanceUntilIdle()
harness.disk.hashByPath["/a.psd"] = "h2"
harness.watcher.fire("/a.psd")
advanceTimeBy(500)
assertTrue(harness.events.isEmpty(), "nothing fires while a gesture is in flight")
harness.disk.hashByPath["/b.psd"] = "k2"
harness.watcher.fire("/b.psd")
advanceTimeBy(500)
idle = true
advanceTimeBy(20)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.ReloadDue(setOf(fileA, fileB))), harness.events, "one reload for both once idle")
harness.finish()
}
@Test
fun notifyReportsAndOffTracksNothing() =
runTest {
val notify = harness(WatchMode.Notify)
notify.disk.hashByPath["/a.psd"] = "h1"
notify.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h1")))
advanceUntilIdle()
notify.disk.hashByPath["/a.psd"] = "h2"
notify.watcher.fire("/a.psd")
advanceTimeBy(100)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.ChangedOnDisk(setOf(fileA))), notify.events)
assertEquals(setOf(fileA), notify.coordinator.pending.value, "the debt stays until Reload is pressed")
val off = harness(WatchMode.Off)
off.disk.hashByPath["/a.psd"] = "h1"
off.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h0")))
advanceUntilIdle()
assertTrue(off.watcher.listeners.values.all { listeners -> listeners.isEmpty() }, "off watches nothing")
assertTrue(off.events.isEmpty())
notify.finish()
off.finish()
}
/**
* A file the document recorded no hash for (a CMO3-origin source) is judged at open by its
* modification time against the recorded one; a recorded hash always outranks the time; and with
* neither recorded there is nothing to judge by.
*/
@Test
fun aFileWithNoRecordedHashIsStaleAtOpenByItsModificationTime() =
runTest {
val harness = harness()
harness.disk.hashByPath["/a.psd"] = "h1"
harness.disk.modifiedAtByPath["/a.psd"] = 2_000L
harness.disk.hashByPath["/b.psd"] = "h2"
harness.disk.modifiedAtByPath["/b.psd"] = 2_000L
harness.disk.hashByPath["/c.psd"] = "h3"
harness.disk.modifiedAtByPath["/c.psd"] = 2_000L
harness.coordinator.track(
listOf(
WatchedSource(fileA, "/a.psd", recordedHash = null, recordedModifiedAt = 1_000L),
WatchedSource(fileB, "/b.psd", recordedHash = "h2", recordedModifiedAt = 1_000L),
WatchedSource(ArtSourceId("art-2"), "/c.psd", recordedHash = null, recordedModifiedAt = null),
),
)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.StaleAtOpen(setOf(fileA))), harness.events, "only the hash-less file whose time moved is stale; a matching hash outranks a moved time, and no record at all is silent")
assertEquals(setOf(fileA), harness.coordinator.pending.value)
harness.finish()
}
@Test
fun aFileEditedWhileClosedIsStaleAtOpenAndAFinishedReloadFeedsBack() =
runTest {
val harness = harness()
harness.disk.hashByPath["/a.psd"] = "h9"
harness.coordinator.track(listOf(WatchedSource(fileA, "/a.psd", "h1")))
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.StaleAtOpen(setOf(fileA))), harness.events, "reported, never auto-reloaded")
assertEquals(setOf(fileA), harness.coordinator.pending.value)
harness.events.clear()
// A reload that found nothing to change acknowledges the disk hash: no further report for it.
harness.coordinator.reloadFinished(setOf(fileA), WatchedReloadResult.NothingChanged)
assertTrue(harness.coordinator.pending.value.isEmpty())
harness.watcher.fire("/a.psd")
advanceTimeBy(100)
advanceUntilIdle()
assertTrue(harness.events.isEmpty(), "the acknowledged hash is dropped")
// A superseded reload is tried again after a settle.
harness.disk.hashByPath["/a.psd"] = "h10"
harness.watcher.fire("/a.psd")
advanceTimeBy(100)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.ReloadDue(setOf(fileA))), harness.events)
harness.events.clear()
harness.coordinator.reloadFinished(setOf(fileA), WatchedReloadResult.Superseded)
advanceTimeBy(100)
advanceUntilIdle()
assertEquals(listOf<SourceWatchEvent>(SourceWatchEvent.ReloadDue(setOf(fileA))), harness.events, "asked again")
// Untracked files stop; the coordinator closes clean.
harness.coordinator.track(emptyList())
assertTrue(harness.watcher.listeners.values.all { listeners -> listeners.isEmpty() })
assertTrue(harness.coordinator.pending.value.isEmpty())
harness.finish()
}
@Test
fun theModeKeyRoundTripsAndAStaleValueFallsBack() {
for (mode in WatchMode.entries) {
assertEquals(mode, WatchMode.fromKey(mode.key))
}
assertEquals(WatchMode.Default, WatchMode.fromKey("not-a-mode"))
assertEquals(WatchMode.Default, WatchMode.fromKey(null))
}
}
@@ -0,0 +1,179 @@
package org.umamo.reimport
import org.umamo.runtime.model.ArtSource
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.SourceLayerRef
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/** The lost-row retention, the per-row suggestions over a model alone and against a read, and the confident picks. */
class SuggestionsTest {
private val source = ArtSourceId("art-0")
private fun row(key: String, name: String, left: Int, top: Int, present: Boolean = true): ArtSourceLayer =
ArtSourceLayer(key, name, "", left, top, 10, 10, visible = true, present = present)
/** A birth quad over a 10 x 10 tile whose layer sits at (50, 50): what an import mints, and nothing more. */
private val freshQuad = DrawableMesh(floatArrayOf(50f, 50f, 60f, 50f, 60f, 60f, 50f, 60f), floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f, 0f, 1f), intArrayOf(0, 1, 2, 0, 2, 3))
/** A three-vertex mesh: edited, so rig work. */
private val editedMesh = DrawableMesh(floatArrayOf(50f, 50f, 51f, 50f, 50f, 51f), floatArrayOf(0f, 0f, 0.1f, 0f, 0f, 0.1f), intArrayOf(0, 1, 2))
private fun drawable(id: String, tileId: String, mesh: DrawableMesh): Drawable =
Drawable(DrawableId(id), id, null, BlendMode.Normal, emptyList(), mesh, null, atlasTileId = AtlasTileId(tileId))
private fun model(drawables: List<Drawable>, tiles: List<AtlasTile>, layers: List<ArtSourceLayer>): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables,
rootChildren = emptyList(),
rootPartId = null,
atlas = PuppetAtlas(tiles = tiles),
sources = listOf(ArtSource(source, "a.psd", null, "psd", layers)),
)
@Test
fun theRefreshKeepsOnlyTheLostRowsATileStillBinds() {
val previous = listOf(row("a", "A", 0, 0), row("b", "B", 0, 0), row("c", "C", 0, 0, present = false))
val fresh = listOf(row("a", "A", 5, 5), row("d", "D", 0, 0))
val refreshed = inventoryWithMissing(previous, fresh, boundKeys = setOf("a", "b", "c"))
assertEquals(listOf("a", "d", "b", "c"), refreshed.map { layer -> layer.key })
assertEquals(listOf(true, true, false, false), refreshed.map { layer -> layer.present })
assertEquals(5, refreshed.first().left, "the fresh row wins over the previous one")
assertEquals(listOf("a", "d"), inventoryWithMissing(previous, fresh, boundKeys = setOf("a")).map { layer -> layer.key }, "an unbound lost row is dropped")
val untouched = inventoryWithMissing(previous, fresh, boundKeys = setOf("a"), untouchedKeys = setOf("a"))
assertEquals(0, untouched.first().left, "a bound layer the plan left alone keeps its previous row, so the next reload still sees its change")
// An erased layer saves with a collapsed rectangle; its row keeps the frame the art last had.
val erasedFresh = listOf(row("a", "A", 0, 0).copy(width = 0, height = 0, empty = true, contentHash = "blank"))
val erased = inventoryWithMissing(listOf(row("a", "A", 30, 40)), erasedFresh, boundKeys = setOf("a")).single()
assertEquals(listOf(30, 40, 10, 10), listOf(erased.left, erased.top, erased.width, erased.height), "the frame the art last had")
assertTrue(erased.empty && erased.contentHash == "blank", "while the erasure itself is recorded")
val stillErased = inventoryWithMissing(listOf(erased), erasedFresh, boundKeys = setOf("a")).single()
assertEquals(listOf(30, 40, 10, 10), listOf(stillErased.left, stillErased.top, stillErased.width, stillErased.height), "and keeps it across further saves")
// A row lost to Replace Artwork says so; one lost before the replace keeps the deletion reading.
val replaced = inventoryWithMissing(previous, fresh, boundKeys = setOf("a", "b", "c"), lostByReplacement = true)
assertEquals(listOf(false, false, true, false), replaced.map { layer -> layer.replaced }, "only the row lost in this refresh reads as replaced")
assertTrue(inventoryWithMissing(previous, fresh, boundKeys = setOf("a", "b", "c")).none { layer -> layer.replaced }, "a plain reload records a deletion")
// The rigger's ignore mark is the document's, not the file's: it rides the fresh row, and a new layer starts unmarked.
val marked = inventoryWithMissing(listOf(row("a", "A", 0, 0).copy(ignored = true)), fresh, boundKeys = emptySet())
assertEquals(listOf(true, false), marked.map { layer -> layer.ignored })
val markedErased = inventoryWithMissing(listOf(row("a", "A", 30, 40).copy(ignored = true)), erasedFresh, boundKeys = emptySet()).single()
assertTrue(markedErased.ignored && markedErased.left == 30, "the mark and the kept frame ride together")
}
@Test
fun eachLostRowGetsItsBestUnboundCandidate() {
// The Nose has an edited mesh over its tile: rig work, so it is never a candidate.
val model =
model(
drawables = listOf(drawable("nose", "t3", editedMesh)),
tiles =
listOf(
AtlasTile(AtlasTileId("t1"), "Eye L", 10, 10, source = SourceLayerRef(source, "name:Eye L#1", false)),
AtlasTile(AtlasTileId("t2"), "Mouth", 10, 10, source = SourceLayerRef(source, "lyid:9", true)),
AtlasTile(AtlasTileId("t3"), "Nose", 10, 10, source = SourceLayerRef(source, "lyid:3", true)),
AtlasTile(AtlasTileId("t4"), "Brow", 10, 10, source = SourceLayerRef(source, "lyid:77", true)),
),
layers =
listOf(
row("lyid:3", "Nose", 50, 50),
row("lyid:4", "Eye Left", 0, 0),
row("lyid:5", "Mouth Open", 100, 100),
row("lyid:6", "Brow Left", 20, 0),
row("name:Eye L#1", "Eye L", 0, 0, present = false),
row("lyid:9", "Mouth", 100, 100, present = false),
),
)
val suggestions = suggestionsFor(model, source)
assertEquals(setOf("name:Eye L#1", "lyid:9", "lyid:77"), suggestions.keys)
assertEquals("lyid:4", suggestions.getValue("name:Eye L#1").key, "the bound Nose, under rig work, is never a candidate")
assertEquals("lyid:5", suggestions.getValue("lyid:9").key)
assertEquals("lyid:6", suggestions.getValue("lyid:77").key, "a binding the inventory never listed is scored from its tile")
// A layer erased to nothing is reviewed like a lost one, and never offered as a candidate.
val erasedModel =
model.copy(
sources =
listOf(
model.sources.single().copy(
layers =
listOf(
row("lyid:3", "Nose", 50, 50).copy(empty = true),
row("lyid:4", "Eye Left", 0, 0),
row("lyid:8", "Nose (blank)", 50, 50).copy(empty = true),
row("lyid:9", "Mouth", 100, 100, present = false),
row("lyid:5", "Mouth Open", 100, 100),
),
),
),
)
val erased = suggestionsFor(erasedModel, source)
val proposedForNose = erased.getValue("lyid:3").key
assertTrue(proposedForNose == "lyid:4" || proposedForNose == "lyid:5", "the emptied Nose is proposed a layer with art, got $proposedForNose")
assertTrue(erased.values.none { match -> match.key == "lyid:8" }, "the blank namesake is never a candidate")
// An ignored layer is never a candidate either: the rigger keeps it out of the rig.
val ignoredModel =
model.copy(sources = listOf(model.sources.single().copy(layers = model.sources.single().layers.map { layer -> if (layer.key == "lyid:4") layer.copy(ignored = true) else layer })))
assertTrue(suggestionsFor(ignoredModel, source).values.none { match -> match.key == "lyid:4" }, "an ignored layer is no candidate")
assertTrue(suggestionsFor(model, ArtSourceId("art-9")).isEmpty(), "an unknown file proposes nothing")
}
@Test
fun aBoundLayerIsNeverProposedOnTheModelAloneAndTheConfidentPicksTakeEachCandidateOnce() {
// The lost Nose was re-created as lyid:3 and a reload minted a fresh drawable for it. On the
// model alone the layer is bound and so not a candidate - nothing here tells that fresh drawable
// from any other untouched one - but a proposal that names it (the reload's own, scored before it
// minted) retires exactly that tile, and never a tile with rig work over it.
val fresh = drawable("fresh", "t3", freshQuad)
val tiles =
listOf(
AtlasTile(AtlasTileId("t1"), "Nose", 10, 10, source = SourceLayerRef(source, "lyid:1", true)),
AtlasTile(AtlasTileId("t3"), "Nose", 10, 10, source = SourceLayerRef(source, "lyid:3", true)),
)
val layers = listOf(row("lyid:3", "Nose", 50, 50), row("lyid:1", "Nose", 50, 50, present = false))
val model = model(listOf(fresh), tiles, layers)
assertTrue(suggestionsFor(model, source).isEmpty(), "a bound layer is no candidate on the model alone")
assertEquals(listOf(AtlasTileId("t3")), retirableTiles(model, source, "lyid:3", except = setOf(AtlasTileId("t1"))), "what a proposal naming the layer retires")
val deformed = model.copy(drawables = listOf(fresh.copy(parentDeformerId = DeformerId("warp"))))
assertTrue(retirableTiles(deformed, source, "lyid:3", except = setOf(AtlasTileId("t1"))).isEmpty(), "under a deformer it is rig work, and stays")
assertTrue(retirableTiles(model, source, "lyid:3", except = setOf(AtlasTileId("t3"))).isEmpty(), "the tiles doing the claiming are never retired")
val signals = MatchSignals(1f, 1f, 1f, 1f, null, hashEqual = false)
val suggestions =
mapOf(
"a" to LayerMatch("x", 0.9f, signals),
"b" to LayerMatch("x", 0.95f, signals),
"c" to LayerMatch("y", 0.7f, signals),
"d" to LayerMatch("z", 0.69f, signals),
)
assertEquals(mapOf("b" to "x", "c" to "y"), confidentMatches(suggestions, 0.7f), "best first, each candidate once, the bar inclusive")
assertEquals(listOf("b", "c"), confidentMatches(suggestions, 0.7f).keys.toList(), "most confident first")
assertTrue(confidentMatches(suggestions, 1f).isEmpty())
}
@Test
fun scoringAgainstAReadRefreshesTheInventoryFirst() {
// The model still lists lyid:1 as present (the file was never reloaded); the art as read has
// lyid:3 in its place. On the model alone nothing is lost; against the read, the binding is.
val model = model(emptyList(), listOf(AtlasTile(AtlasTileId("t1"), "Nose", 10, 10, source = SourceLayerRef(source, "lyid:1", true))), listOf(row("lyid:1", "Nose", 50, 50)))
val read = listOf(row("lyid:3", "Nose", 50, 50))
assertTrue(suggestionsFor(model, source).isEmpty())
assertEquals("lyid:3", suggestionsAgainstRead(model, source, read).getValue("lyid:1").key)
assertTrue(suggestionsAgainstRead(model, ArtSourceId("art-9"), read).isEmpty(), "an unknown file proposes nothing")
}
}
@@ -0,0 +1,70 @@
package org.umamo.reimport
import org.umamo.format.art.LayerBlend
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerId
import org.umamo.format.art.LayerRaster
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceGroup
import org.umamo.format.art.SourceLayer
import org.umamo.format.art.SourceLayerKind
/**
* An in-memory source layer, so the engine's tests need no file: a raster of one color at a canvas
* position, keyed the way a reader keys it.
*/
internal class TestLayer(
id: String,
override val name: String,
override val order: Int,
override val bounds: LayerBounds,
override val raster: LayerRaster,
override val groupPath: String = "",
override val kind: SourceLayerKind = SourceLayerKind.Raster,
override val idIsStable: Boolean = true,
override val visible: Boolean = true,
) : SourceLayer {
override val id: LayerId = LayerId(id)
override val opacity: Float = 1f
override val clipped: Boolean = false
override val blend: LayerBlend = LayerBlend.Normal
}
/** An in-memory source document over [layers], with the folders [groups] describes. */
internal class TestArt(
override val layers: List<SourceLayer>,
override val widthPx: Int = 64,
override val heightPx: Int = 64,
override val groups: List<SourceGroup> = emptyList(),
) : SourceArt
/** An in-memory plain folder at [path], named by its last segment. */
internal class TestGroup(
override val path: String,
) : SourceGroup {
override val name: String = path.substringAfterLast('/')
override val visible: Boolean = true
override val opacity: Float = 1f
override val clipped: Boolean = false
override val blend: LayerBlend = LayerBlend.Normal
override val passThrough: Boolean = true
}
/**
* A raster filled with one opaque color.
*
* @param Int width The width in pixels.
* @param Int height The height in pixels.
* @param Byte value The byte every color channel takes.
* @return LayerRaster The raster.
*/
internal fun solidRaster(width: Int, height: Int, value: Byte): LayerRaster {
val rgba = ByteArray(width * height * 4)
for (pixel in 0 until width * height) {
rgba[pixel * 4] = value
rgba[pixel * 4 + 1] = value
rgba[pixel * 4 + 2] = value
rgba[pixel * 4 + 3] = 0xFF.toByte()
}
return LayerRaster(width, height, rgba)
}
@@ -0,0 +1,125 @@
package org.umamo.reimport
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.LayerRaster
import org.umamo.format.binary.contentHashOf
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.format.uma.Uma
import org.umamo.format.uma.UmaModel
import org.umamo.format.uma.UmaWriterInfo
import org.umamo.format.uma.textures.UmaPixelSource
import org.umamo.format.uma.textures.UmaRenderPagePixels
import org.umamo.interop.art.ArtSourceDescriptor
import org.umamo.interop.art.CanvasOffset
import org.umamo.interop.art.SourceArtImport
import org.umamo.interop.art.SourceArtImportOptions
import org.umamo.interop.art.placedBy
import org.umamo.interop.art.placedFor
import org.umamo.interop.uma.UmaDocumentBridge
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
/**
* The reopen-then-reload promise the native format makes (docs/format/UMA.md §5, §6): a reload planned against a
* document before it was saved and one planned against the same document reopened from its `.uma` are the same
* plan, because the file carries the whole re-import baseline - the inventory with its flags and hashes, the
* bindings, the lineage, the file's placement on the canvas, and the tiles' pixels byte for byte.
*/
class UmaReopenReloadTest {
private val options = SourceArtImportOptions(alphaThreshold = 1, birthMeshMargin = 2)
private val repainted = TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 4, 4), solidRaster(4, 4, 1))
private val kept = TestLayer("lyid:2", "Two", 1, LayerBounds(30, 40, 4, 4), solidRaster(4, 4, 2))
private val removed = TestLayer("lyid:3", "Three", 2, LayerBounds(50, 10, 6, 6), solidRaster(6, 6, 3), visible = false)
private val ignored = TestLayer("lyid:4", "Sketch", 3, LayerBounds(0, 0, 8, 8), LayerRaster(8, 8, ByteArray(8 * 8 * 4)))
/**
* A reloaded file's lines, reduced to text that is equal exactly when the plans are: meshes by their arrays,
* rasters by their content hash, and everything else by its data-class form.
*
* @param ReloadPlan? plan The plan, or null when there is nothing to do.
* @return List<String> The lines.
*/
private fun fingerprintOf(plan: ReloadPlan?): List<String> {
if (plan == null) {
return listOf("no plan")
}
/**
* A mesh as text.
*
* @param DrawableMesh? mesh The mesh.
* @return String The text.
*/
fun meshText(mesh: DrawableMesh?): String = mesh?.let { present -> "${present.positions.contentToString()} ${present.uvs.contentToString()} ${present.indices.contentToString()}" } ?: "none"
val reload = plan.reload
val lines = ArrayList<String>()
lines += "source ${reload.source}"
reload.replacedTiles.forEach { replaced -> lines += "replaced ${replaced.oldId.raw} with ${replaced.tile}" }
reload.drawableMeshes.entries.sortedBy { (drawableId, _) -> drawableId.raw }.forEach { (drawableId, mesh) -> lines += "mesh ${drawableId.raw} ${meshText(mesh)}" }
reload.additions?.let { additions ->
lines += "added source ${additions.source}"
additions.tiles.forEach { tile -> lines += "added tile $tile" }
additions.drawables.forEach { drawable -> lines += "added drawable ${drawable.copy(mesh = null)} ${meshText(drawable.mesh)}" }
additions.parts.forEach { part -> lines += "added part $part" }
lines += "added root ${additions.rootChildren} insertions ${additions.insertions}"
}
lines += "outgrown ${reload.outgrown} retired ${reload.retiredTiles} visibility ${reload.drawableVisibility}"
plan.rasterByTile.entries.sortedBy { (tileId, _) -> tileId.raw }.forEach { (tileId, raster) -> lines += "raster ${tileId.raw} ${raster.width}x${raster.height} ${contentHashOf(raster.rgba)}" }
lines += "report ${plan.report.results}"
lines += "notices ${plan.notices}"
lines += "leftovers ${plan.leftovers}"
return lines
}
/**
* A reload of a file whose first layer was repainted, whose third was deleted, whose ignored layer gained pixels,
* and which gained a fifth layer plans the same against the document and against its reopened `.uma`.
*/
@Test
fun aReopenedDocumentReloadsAsTheOriginalDoes() {
val fileBytes = "the file as imported".encodeToByteArray()
// The file was placed on the canvas when it was added, so every read of it is placed the same way.
val offset = CanvasOffset(7, 11)
val imported = SourceArtImport.fromSourceArt(TestArt(listOf(repainted, kept, removed, ignored)).placedBy(offset), ArtSourceDescriptor("a.clip", "/art/a.clip", "clip", contentHashOf(fileBytes), 1_757_894_400_000L), options)
val sourceId = imported.puppet.sources.single().id
// Rig work the reload must respect: the rigger ignored the sketch layer.
val source = imported.puppet.sources.single().copy(offsetX = offset.x, offsetZ = offset.z)
val model = imported.puppet.copy(sources = listOf(source.copy(layers = source.layers.map { layer -> if (layer.key == "lyid:4") layer.copy(ignored = true) else layer })))
assertTrue(model.sources.single().layers.single { layer -> layer.key == "lyid:4" }.empty, "the sketch reads as an empty layer")
val pngByTile = imported.rasterByTile.mapKeys { (tileId, _) -> tileId.raw }.mapValues { (_, raster) -> PngCodec.write(RasterImage(raster.width, raster.height, raster.rgba)) }
val saved = UmaDocumentBridge.documentOf(UmaModel.create(UmaWriterInfo("Umamo", "test")), model, UmaPixelSource({ tileId -> pngByTile[tileId] }, UmaRenderPagePixels.Derived, null))
val document = Uma.read(Uma.write(saved))
val reopened: PuppetModel = UmaDocumentBridge.modelOf(document)
assertEquals(offset.x to offset.z, reopened.sources.single().let { record -> record.offsetX to record.offsetZ }, "the placement survives the save")
val pages = UmaDocumentBridge.pagesOf(document)
val reopenedRasterOf: (AtlasTileId) -> LayerRaster? = { tileId -> pages.tilePng(tileId)?.let(PngCodec::read)?.let { image -> LayerRaster(image.width, image.height, image.rgba) } }
val newArt =
TestArt(
listOf(
TestLayer("lyid:1", "One", 0, LayerBounds(10, 20, 5, 4), solidRaster(5, 4, 9)),
kept,
TestLayer("lyid:4", "Sketch", 2, LayerBounds(0, 0, 8, 8), solidRaster(8, 8, 4)),
TestLayer("lyid:5", "Five", 3, LayerBounds(60, 60, 3, 3), solidRaster(3, 3, 5)),
),
).placedFor(reopened.sources.single())
val newHash = contentHashOf("the file as saved again".encodeToByteArray())
val before = ArtworkReloadPlanner.plan(model, sourceId, newArt, options, { tileId -> imported.rasterByTile[tileId] }, newHash)
val after = ArtworkReloadPlanner.plan(reopened, sourceId, newArt, options, reopenedRasterOf, newHash)
val plan = assertNotNull(before, "the changed file plans a reload")
assertTrue(plan.reload.replacedTiles.isNotEmpty(), "the repainted layer supersedes its tile")
assertTrue(plan.reload.additions != null, "the new layer is added")
assertTrue(plan.report.needsReview.isNotEmpty(), "the deleted layer is left for review")
assertEquals(offset.x to offset.z, plan.reload.source.let { record -> record.offsetX to record.offsetZ }, "the refreshed record keeps the placement")
assertEquals(fingerprintOf(before), fingerprintOf(after))
}
}