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
+84
View File
@@ -0,0 +1,84 @@
// :interop — format↔runtime conversion. CMO3/MOC3 ingest into the PuppetModel, the CMO3 export
// reconcile, the MOC3 export lowering, the model diff, and the RuntimeTarget↔format-version
// mapping. Depends on BOTH
// :format and :runtime so that neither has to know the other: :format stays a standalone codec
// library and :runtime stays a pure puppet runtime.
plugins {
alias(libs.plugins.kotlinMultiplatform)
alias(libs.plugins.androidKmpLibrary)
// Umamo's own conventions (gradle/build-logic): the shared jvmAndroidMain source-set group, the
// iosArm64 → `check` wiring, and the corpus/-D forwarding configured by `umamoTestCorpus` below.
id("umamo.kmp-jvmandroid")
id("umamo.kmp-ios-gate")
id("umamo.test-corpus")
}
kotlin {
jvmToolchain(21)
// The `jvmAndroidMain` group comes from the `umamo.kmp-jvmandroid` convention plugin. This module
// needs it because the CMO3 export lowering (Cmo3Export) mutates a Cmo3Model graph, which lives in
// :format's own jvmAndroidMain (the JDOM-backed codec) — so it can't sit in commonMain.
jvm()
// The iPadOS ship target, mirroring :format and :runtime (see :format's docblock for the full
// rationale). It keeps the commonMain conversions (MOC3 ingest for a future iOS viewer, the CMO3
// ingest and model diff) a compiler-checked iOS citizen rather than the root regex gate's
// convention. Compiles on Linux/CI (klib only, no Xcode linker); a device target has no runnable
// test task, so `umamo.kmp-ios-gate` wires `check` to the compiles.
iosArm64()
android {
namespace = "org.umamo.interop"
compileSdk = libs.versions.android.compileSdk.get().toInt()
minSdk = libs.versions.android.minSdk.get().toInt()
}
sourceSets {
commonMain {
dependencies {
// Both `api` (not `implementation`): the conversion surface exposes both sides —
// CModelSource/Cmo3Model/MocDocument parameters from :format, PuppetModel and the
// diff types from :runtime — so consumers (:ui, tests) see them transitively.
api(project(":format"))
api(project(":runtime"))
}
}
commonTest {
dependencies {
implementation(kotlin("test"))
}
}
jvmTest {
dependencies {
// The skeleton gate compares emitted XML structure against the corpus blank; JDOM is
// :format's own (implementation-scoped) backend, so the test declares it directly.
implementation(libs.jdom)
// TEST-ONLY: the MOC3 conversion round trip mirrors the app's document loader, which
// normalizes rest meshes to canvas space through :render's evaluator before export
// (production :interop code never depends on :render - siblings over :runtime).
implementation(project(":render"))
}
}
}
}
// Corpus wiring for the gated tests (the `umamo.test-corpus` convention plugin):
// `./gradlew :interop:jvmTest -Dcmo3.sample=… -Dmoc3.sample=… -Dmoc3.samples=…`.
//
// cmo3.sample and cmo3.probe take the shared corpus defaults, so Cmo3ImportTest's probe loop exercises
// the whole corpus by default when the local (gitignored) corpus is present; moc3.samples points at the
// whole moc3 tree, which CompositeImportTest joins against ingested CMO3s and the MOC3 export/downgrade
// round-trip gates walk in full. moc3.sample (singular, read by Moc3ImportTest's golden-count test) has
// no default and only takes effect when passed as -D.
umamoTestCorpus {
// The probe loop inflates every corpus CMO3 (Model C's main.xml alone is ~10 MB of JDOM). Raised
// from 4g when modelF joined the corpus: at 57.8 MB and ~6.5 M keyform vertex positions its
// MOC3→CMO3 conversion in Cmo3ConversionRoundTripTest OOMs at 4g and passes at 8g, because the
// conversion holds the PuppetModel and the whole synthesized JDOM graph at once. Do not trim this
// back without re-running that test against modelF.
maxHeap("8g")
sample("cmo3.sample", "cmo3.probe", "moc3.sample", "moc3.samples")
}
@@ -0,0 +1,30 @@
package org.umamo.interop
/**
* A document's atlas pages as its source format carries them: the encoded page bytes plus which page
* each drawable samples.
*
* The format-neutral half of texture ingest. Every container answers "which pages are there, and who
* samples which" its own way - a CMO3 walks its drawable sources to embedded image resources, a MOC3
* reads a per-mesh index into the manifest's texture list - but the answer is the same shape, and
* decoding it is not a format concern. So the walk lives here with the rest of the format ingest and
* the decode stays in the renderer, which is what keeps container knowledge out of `:render`.
*
* Pages are referenced by position: a drawable's value in [atlasIndexByDrawableId] indexes [pageBytes].
*
* @property List<ByteArray> pageBytes The encoded pages, in the source's own page order.
* @property Map<String, Int> atlasIndexByDrawableId Raw drawable id to its page's index in [pageBytes].
* @property Boolean premultipliedAlpha The source's texture-upload-convention flag, carried
* through for the renderer's own record; it is not a claim about the encoded bytes, which are always
* straight alpha. Only CMO3 sets it.
*/
public class AtlasPageSet(
public val pageBytes: List<ByteArray>,
public val atlasIndexByDrawableId: Map<String, Int>,
public val premultipliedAlpha: Boolean = false,
) {
public companion object {
/** No pages and nothing bound - what a document with no atlas ingests to. */
public val EMPTY: AtlasPageSet = AtlasPageSet(emptyList(), emptyMap())
}
}
@@ -0,0 +1,261 @@
package org.umamo.interop
import org.umamo.format.cmo3.model.gen.AlphaComposition
import org.umamo.format.cmo3.model.gen.ColorComposition
import org.umamo.format.moc3.moc.ConstantFlag
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
/*
* The blend-mode bijections shared by both importers, per the extraction tables in
* docs/plan/offscreen-support.md: CMO3 serializes enum tokens (ColorComposition /
* AlphaComposition), MOC3 packs ints (sections 153/157, colorMode or (alphaMode shl 8)).
* The bare legacy tokens (NORMAL/ADD/MULTIPLY) are the pre-5.3 modes in every era; each
* 5.3 mode has its own token and int.
*/
/**
* Maps a CMO3 ColorComposition token to the runtime color blend mode.
*
* @param String? name The serialized enum constant name (e.g. "MULTIPLY_R2"), or null when absent.
* @return BlendMode The runtime mode; Normal for null or an unknown token.
*/
internal fun colorBlendOfToken(name: String?): BlendMode =
// CMO3: ColorComposition constants, matched by name (the generated enum is observed-only).
when (name) {
"NORMAL" -> BlendMode.Normal
"ADD" -> BlendMode.AdditivePremultiplied
"MULTIPLY" -> BlendMode.MultiplyPremultiplied
"ADD_R2_TSL" -> BlendMode.Additive
"ADD_R2" -> BlendMode.AdditiveGlow
"DARKEN" -> BlendMode.Darken
"MULTIPLY_R2" -> BlendMode.Multiply
"COLORBURN_TSL" -> BlendMode.ColorBurn
"LINEARBURN_TSL" -> BlendMode.LinearBurn
"LIGHTEN" -> BlendMode.Lighten
"SCREEN" -> BlendMode.Screen
"COLORDODGE_TSL" -> BlendMode.ColorDodge
"OVERLAY" -> BlendMode.Overlay
"SOFTLIGHT" -> BlendMode.SoftLight
"HARDLIGHT" -> BlendMode.HardLight
"LINEARLIGHT_TSL" -> BlendMode.LinearLight
"HSL_HUE" -> BlendMode.Hue
"HSL_COLOR" -> BlendMode.Color
else -> BlendMode.Normal
}
/**
* Maps a runtime color blend mode to its CMO3 ColorComposition constant - the export inverse of
* [colorBlendOfToken].
*
* @param BlendMode mode The runtime mode.
* @return ColorComposition The serialized enum constant.
*/
internal fun colorCompositionOf(mode: BlendMode): ColorComposition =
// CMO3: ColorComposition constants (see colorBlendOfToken's forward table).
when (mode) {
BlendMode.Normal -> ColorComposition.NORMAL
BlendMode.AdditivePremultiplied -> ColorComposition.ADD
BlendMode.MultiplyPremultiplied -> ColorComposition.MULTIPLY
BlendMode.Additive -> ColorComposition.ADD_R2_TSL
BlendMode.AdditiveGlow -> ColorComposition.ADD_R2
BlendMode.Darken -> ColorComposition.DARKEN
BlendMode.Multiply -> ColorComposition.MULTIPLY_R2
BlendMode.ColorBurn -> ColorComposition.COLORBURN_TSL
BlendMode.LinearBurn -> ColorComposition.LINEARBURN_TSL
BlendMode.Lighten -> ColorComposition.LIGHTEN
BlendMode.Screen -> ColorComposition.SCREEN
BlendMode.ColorDodge -> ColorComposition.COLORDODGE_TSL
BlendMode.Overlay -> ColorComposition.OVERLAY
BlendMode.SoftLight -> ColorComposition.SOFTLIGHT
BlendMode.HardLight -> ColorComposition.HARDLIGHT
BlendMode.LinearLight -> ColorComposition.LINEARLIGHT_TSL
BlendMode.Hue -> ColorComposition.HSL_HUE
BlendMode.Color -> ColorComposition.HSL_COLOR
}
/**
* Maps a CMO3 AlphaComposition token to the runtime alpha blend mode.
*
* @param String? name The serialized enum constant name (e.g. "DISJOINT"), or null when absent
* (pre-5.3 sources carry no alpha mode).
* @return AlphaBlendMode The runtime mode; Over for null or an unknown token.
*/
internal fun alphaBlendOfToken(name: String?): AlphaBlendMode =
// CMO3: AlphaComposition constants, matched by name.
when (name) {
"OVER" -> AlphaBlendMode.Over
"ATOP" -> AlphaBlendMode.Atop
"OUT" -> AlphaBlendMode.Out
"CONJOINT" -> AlphaBlendMode.Conjoint
"DISJOINT" -> AlphaBlendMode.Disjoint
else -> AlphaBlendMode.Over
}
/**
* Maps a runtime alpha blend mode to its CMO3 AlphaComposition constant - the export inverse of
* [alphaBlendOfToken].
*
* @param AlphaBlendMode mode The runtime mode.
* @return AlphaComposition The serialized enum constant.
*/
internal fun alphaCompositionOf(mode: AlphaBlendMode): AlphaComposition =
// CMO3: AlphaComposition constants (see alphaBlendOfToken's forward table).
when (mode) {
AlphaBlendMode.Over -> AlphaComposition.OVER
AlphaBlendMode.Atop -> AlphaComposition.ATOP
AlphaBlendMode.Out -> AlphaComposition.OUT
AlphaBlendMode.Conjoint -> AlphaComposition.CONJOINT
AlphaBlendMode.Disjoint -> AlphaComposition.DISJOINT
}
/**
* Unpacks the color half of a MOC3 packed blend int (sections 153/157).
*
* @param Int packed The stored int, colorMode or (alphaMode shl 8).
* @return BlendMode The runtime mode; Normal for an unknown colorMode.
*/
internal fun colorBlendOfPacked(packed: Int): BlendMode =
// MOC3 v6 §5.6 s153/s157: colorMode 0-17 in editor-dropdown order (legacy first).
when (packed and 0xFF) {
0 -> BlendMode.Normal
1 -> BlendMode.AdditivePremultiplied
2 -> BlendMode.MultiplyPremultiplied
3 -> BlendMode.Additive
4 -> BlendMode.AdditiveGlow
5 -> BlendMode.Darken
6 -> BlendMode.Multiply
7 -> BlendMode.ColorBurn
8 -> BlendMode.LinearBurn
9 -> BlendMode.Lighten
10 -> BlendMode.Screen
11 -> BlendMode.ColorDodge
12 -> BlendMode.Overlay
13 -> BlendMode.SoftLight
14 -> BlendMode.HardLight
15 -> BlendMode.LinearLight
16 -> BlendMode.Hue
17 -> BlendMode.Color
else -> BlendMode.Normal
}
/**
* Unpacks the alpha half of a MOC3 packed blend int (sections 153/157).
*
* @param Int packed The stored int, colorMode or (alphaMode shl 8).
* @return AlphaBlendMode The runtime mode; Over for an unknown alphaMode.
*/
internal fun alphaBlendOfPacked(packed: Int): AlphaBlendMode =
// MOC3 v6 §5.6 s153/s157: alphaMode 0-4 in editor-dropdown order.
when ((packed shr 8) and 0xFF) {
0 -> AlphaBlendMode.Over
1 -> AlphaBlendMode.Atop
2 -> AlphaBlendMode.Out
3 -> AlphaBlendMode.Conjoint
4 -> AlphaBlendMode.Disjoint
else -> AlphaBlendMode.Over
}
/**
* The LEGACY 2-bit constant-flag encoding of [mode] - the only blend a moc below v6 can express.
*
* The pre-5.3 fixed-function set is just Normal / Add / Multiply, so every 5.3+ mode has to fall back
* to its nearest premultiplied ancestor: the 5.3 additive family reads as Add and the multiply family
* as Multiply, and anything with no fixed-function equivalent reads as Normal. A v6 export writes the
* packed extended blend instead and leaves these bits at Normal, so this is only reached when the
* target version genuinely cannot carry the authored mode.
*
* @param BlendMode mode The runtime blend mode.
* @return Int The constant-flag bits (0 for Normal).
*/
internal fun legacyBlendFlagOf(mode: BlendMode): Int =
when (nearestLegacyBlendMode(mode)) {
BlendMode.AdditivePremultiplied -> ConstantFlag.BLEND_ADDITIVE
BlendMode.MultiplyPremultiplied -> ConstantFlag.BLEND_MULTIPLICATIVE
else -> 0
}
/**
* The pre-5.3 mode [mode] degrades to when the target version cannot carry it.
*
* The same nearest-ancestor rule [legacyBlendFlagOf] encodes, as a runtime mode rather than as flag
* bits, so a version downgrade rewrites the MODEL to what the file will actually say instead of
* leaving the two to disagree about what "additive" means.
*
* @param BlendMode mode The authored blend mode.
* @return BlendMode The nearest mode a pre-5.3 runtime understands.
*/
internal fun nearestLegacyBlendMode(mode: BlendMode): BlendMode =
when (mode) {
BlendMode.AdditivePremultiplied, BlendMode.Additive, BlendMode.AdditiveGlow ->
BlendMode.AdditivePremultiplied
BlendMode.MultiplyPremultiplied, BlendMode.Multiply -> BlendMode.MultiplyPremultiplied
else -> BlendMode.Normal
}
/**
* The constant-flag bits of [mode] when the pair names the mode EXACTLY, else 0.
*
* Unlike [legacyBlendFlagOf] this never approximates: only the two premultiplied modes have a legacy
* bit that means the same thing, so Additive (non-premultiplied), AdditiveGlow, and Multiply all read
* as Normal here. That is what a moc 6 offscreen's flag byte contains - every corpus offscreen sets
* the bit for colorMode 1 or 2 and clears it for every other mode - because on v6 the packed section
* is authoritative and these bits merely restate the two modes an old reader could have understood.
*
* Approximating here would state a mode the file does not, which is the failure the two names exist to
* keep apart: [legacyBlendFlagOf] is for a DOWNGRADE (the packed section is gone and the nearest
* ancestor is the best available), this is for an ECHO (the packed section is right there).
*
* @param BlendMode mode The runtime blend mode.
* @return Int The constant-flag bits (0 unless the mode is exactly additive- or multiply-premultiplied).
*/
internal fun exactLegacyBlendFlagOf(mode: BlendMode): Int =
when (mode) {
BlendMode.AdditivePremultiplied -> ConstantFlag.BLEND_ADDITIVE
BlendMode.MultiplyPremultiplied -> ConstantFlag.BLEND_MULTIPLICATIVE
else -> 0
}
/**
* Packs [color] and [alpha] into the MOC3 v6 blend int (sections 153 / 157).
*
* The exact inverse of [colorBlendOfPacked] and [alphaBlendOfPacked], written as the same ordinal
* tables read backwards so a mode added to one direction is a compile error in the other rather than a
* silently unpackable value.
*
* @param BlendMode color The runtime color blend mode.
* @param AlphaBlendMode alpha The runtime alpha blend mode.
* @return Int The stored int, `colorMode or (alphaMode shl 8)`.
*/
internal fun packedBlendOf(color: BlendMode, alpha: AlphaBlendMode): Int {
val colorMode =
when (color) {
BlendMode.Normal -> 0
BlendMode.AdditivePremultiplied -> 1
BlendMode.MultiplyPremultiplied -> 2
BlendMode.Additive -> 3
BlendMode.AdditiveGlow -> 4
BlendMode.Darken -> 5
BlendMode.Multiply -> 6
BlendMode.ColorBurn -> 7
BlendMode.LinearBurn -> 8
BlendMode.Lighten -> 9
BlendMode.Screen -> 10
BlendMode.ColorDodge -> 11
BlendMode.Overlay -> 12
BlendMode.SoftLight -> 13
BlendMode.HardLight -> 14
BlendMode.LinearLight -> 15
BlendMode.Hue -> 16
BlendMode.Color -> 17
}
val alphaMode =
when (alpha) {
AlphaBlendMode.Over -> 0
AlphaBlendMode.Atop -> 1
AlphaBlendMode.Out -> 2
AlphaBlendMode.Conjoint -> 3
AlphaBlendMode.Disjoint -> 4
}
return colorMode or (alphaMode shl 8)
}
@@ -0,0 +1,169 @@
package org.umamo.interop
import org.umamo.runtime.model.RuntimeFeature
/**
* One advisory finding from an export, CMO3 or MOC3.
*
* An export ALWAYS writes; notices only tell the user what the written file does not carry or what
* a Cubism-side edit could do to it. Nothing is ever silently dropped: every edit a lowering cannot
* yet (or can never) express in the target format surfaces as an [UnsupportedChange], and every
* feature the chosen target version predates surfaces as a [FeatureStripped].
*/
sealed interface ExportNotice {
/**
* An edit the export lowering did not persist into the written file.
*
* @property ExportEntityCategory category The kind of thing the finding is about.
* @property String? subject The affected entity's id, or null for a document-level
* finding, whose [reason] names the field itself.
* @property ExportNoticeReason reason Why the lowering could not carry the edit.
*/
data class UnsupportedChange(
val category: ExportEntityCategory,
val subject: String?,
val reason: ExportNoticeReason,
) : ExportNotice
/**
* Drawables whose base geometry or UVs diverged from the imported geometry/UV weld. The export
* writes them as authored (the official editor renders the same displaced result Umamo shows),
* but Cubism couples geometry and UVs at the neutral form, so its own mesh-edit / re-atlas
* operations may re-derive and corrupt the mapping.
*
* @property List drawableNames The affected drawables' display names.
*/
data class WeldDivergence(val drawableNames: List<String>) : ExportNotice
/**
* A feature the export target's runtime cannot load, removed from the written file.
*
* Distinct from [UnsupportedChange], which reports what the lowering could not express: this one
* reports what the lowering deliberately took OUT because the chosen version predates it. The
* document itself keeps the feature - the strip runs on a copy - so re-exporting at a higher
* version brings it back.
*
* @property RuntimeFeature feature The stripped feature.
* @property List subjects The affected entities' display names, in document order.
*/
data class FeatureStripped(
val feature: RuntimeFeature,
val subjects: List<String>,
) : ExportNotice
/**
* Not every drawable's art came from a real source layer, so the CMO3 was built around a
* fabricated source document - the whole file, for a MOC3-origin document, which has no source
* artwork at all.
*
* A CMO3 is organised around the layered art it was imported from; a MOC3 carries only packed
* atlas pages, so the export reconstructs a stand-in source document by slicing each drawable's
* patch back out of the atlas. The result opens and renders in the official Cubism Editor, and
* switches between its layered-art and texture-atlas display modes - but every layer in it is a
* slice of a baked page, not the artwork the rig was drawn from. What that costs is editable
* art: the layers cannot be redrawn upstream and refreshed, and their quality is capped by the
* page they were cut from. Reconciling the ORIGINAL layered art (PSD/CLIP/KRA) into the
* document is what replaces them with the real thing.
*
* @property Int pageCount The number of atlas pages the stand-in source was built from.
*/
data class MissingSourceArt(val pageCount: Int) : ExportNotice
/**
* Drawables that share one atlas slot with a twin at another canvas placement and could not be
* given a slot of their own because their patch is too large for a page even on its own. A CMO3
* model image carries a single canvas placement, so the official editor shows such a drawable at
* the first twin's placement in its layered-art display mode; the texture-atlas mode and the
* runtime are unaffected. A transparent twin (a hit area's) is not reported: nothing shows at
* either placement.
*
* @property List drawableNames The affected drawables' display names, in document order.
*/
data class SharedAtlasSlotKept(val drawableNames: List<String>) : ExportNotice
}
/**
* One log line for an export notice: what the editor's log and the command-line tool's report both print,
* the headless-visible mirror of the editor's report alert.
*
* Deliberately English and deliberately structural: the log is a diagnostic surface, read off a bug
* report rather than by a rigger mid-edit, so it wants text that is stable across locales and greps
* straight back to a call site. Printing the reason itself gives that for free and, unlike a second
* hand-written copy of the alert's prose, cannot drift from the case list it describes.
*
* @param ExportNotice notice The notice to describe.
* @return String The log text.
*/
fun describeExportNotice(notice: ExportNotice): String =
when (notice) {
is ExportNotice.UnsupportedChange ->
if (notice.subject == null) {
"[${notice.category}] ${notice.reason}"
} else {
"[${notice.category}] ${notice.subject}: ${notice.reason}"
}
is ExportNotice.WeldDivergence -> "weld divergence on ${notice.drawableNames.joinToString()}"
is ExportNotice.FeatureStripped ->
"${notice.feature} is not in the exported moc version; removed from " +
notice.subjects.take(8).joinToString() +
if (notice.subjects.size > 8) " (+${notice.subjects.size - 8} more)" else ""
is ExportNotice.MissingSourceArt ->
"no source artwork: the CMO3 was built around a stand-in document rebuilt from ${notice.pageCount} atlas page(s), " +
"so its layers are atlas slices rather than the original artwork"
is ExportNotice.SharedAtlasSlotKept ->
"twins sharing one atlas slot could not be given their own: " +
notice.drawableNames.take(8).joinToString() +
(if (notice.drawableNames.size > 8) " (+${notice.drawableNames.size - 8} more)" else "") +
"; the editor's layered view shows them at the first twin's placement"
}
/**
* The kind of thing an [ExportNotice.UnsupportedChange] is about, naming the panel a rigger would
* look in to find it.
*
* An enum rather than the free text it replaces: the vocabulary was previously documented in a
* comment and enforced by nothing, so a typo produced a category no reader recognized, and the label
* could not be localized. [Keyform] is the odd member - a keyform is not an entity in its own right -
* but the notice's subject there is the owning drawable or part, so the rendered line still reads as
* a place to look.
*/
enum class ExportEntityCategory {
Parameter,
ParameterGroup,
Part,
Deformer,
Drawable,
Glue,
Document,
Keyform,
}
/**
* The format one export wrote, naming which file family a report's findings are about.
*
* Deliberately narrower than [org.umamo.format.FileKind], which spans every family Umamo reads
* (art sources, sidecars, raster pages) - only the ones an export path writes belong here, so a
* `when` over an [ExportReport]'s format stays exhaustive without an `else` that would silently
* swallow a new export target.
*/
enum class ExportFormat {
Cmo3,
Moc3,
}
/**
* The advisory outcome of one export: what the written file does not carry.
*
* The notice kinds are format-neutral because the contract is: an export ALWAYS writes, and notices
* only say what the written file does not carry. That holds identically for CMO3 and MOC3, so both
* report through this rather than through parallel types the UI would have to handle twice. The
* [format] is what keeps the report attributable: a reader (the alert's header, a log line) has to
* name the file family the findings are about, and no notice carries that on its own.
*
* @property ExportFormat format The format the export wrote.
* @property List notices The findings, empty for a fully-lowered export.
*/
data class ExportReport(val format: ExportFormat, val notices: List<ExportNotice>) {
/** True when the export lowered everything with nothing to warn about. */
val isEmpty: Boolean get() = notices.isEmpty()
}
@@ -0,0 +1,275 @@
package org.umamo.interop
import org.umamo.runtime.model.FormChannel
/**
* Why one [ExportNotice.UnsupportedChange] fired: the closed vocabulary of things an export lowering
* cannot carry into the written file.
*
* Closed rather than free text so the reason can be LOCALIZED. The prose a rigger reads lives in the
* UI's string catalog, keyed off the case; this module stays presentation-free and carries only the
* structured facts a sentence needs. That is the same split [ExportNotice.FeatureStripped] already
* uses for its [org.umamo.runtime.model.RuntimeFeature], generalized to every finding.
*
* Two rules hold across every case, and both are load-bearing:
*
* - Every case is a `data object` or `data class`, never a bare `object`. The log mirror in the app
* prints the reason with `toString()`, so a bare object would emit an identity hash instead of a
* name. ExportNoticeReasonTest pins this.
* - Ids are plain [String], not the typed `ParameterId`/`DrawableId` wrappers. A report is a display
* carrier rather than a model - [ExportNotice.UnsupportedChange.subject] and
* [ExportNotice.FeatureStripped.subjects] are already plain strings - and a value class would render
* as `ParameterId(raw=ParamAngleX)` in every log line. [FormChannel] is the one typed field, because
* it is a localizable enum rather than user data.
*
* The cases are declared here in commonMain even where only the CMO3 lowering produces them: :interop
* builds an iosArm64 target that never sees jvmAndroidMain, so a member declared there would break the
* exhaustive `when` the UI does over this hierarchy.
*/
sealed interface ExportNoticeReason {
// Shared - fired by both export paths.
/** The drawable carries no mesh, so there is no geometry to write. */
data object DrawableHasNoMesh : ExportNoticeReason
// MOC3 lowering.
/**
* A channel keyed over a narrower span than its object's grid, written as a constant instead.
*
* @property FormChannel channel The demoted channel.
*/
data class ChannelDemotedToStatic(val channel: FormChannel) : ExportNoticeReason
/** A guide-image (sketch) part holds authoring aids, not runtime content. */
data object SketchPartIsNotRuntimeContent : ExportNoticeReason
/** A hidden part's subtree was left out because the export options omit hidden parts. */
data object HiddenPartOmittedByExportOption : ExportNoticeReason
/** A hidden art mesh was left out because the export options omit hidden drawables. */
data object HiddenDrawableOmittedByExportOption : ExportNoticeReason
/** An unkeyed drawable under a deformer has no parent-space geometry the moc could store. */
data object UnkeyedDrawableUnderDeformerHasNoParentGeometry : ExportNoticeReason
/**
* The canvas-to-parent conversion returned a different coordinate count than the mesh has.
*
* @property Int convertedCoordinateCount The count the conversion returned.
* @property Int expectedCoordinateCount The count the mesh carries.
*/
data class RestMeshConversionSizeMismatch(
val convertedCoordinateCount: Int,
val expectedCoordinateCount: Int,
) : ExportNoticeReason
/** No atlas page is bound to the drawable, so its texture index fell back to page 0. */
data object NoAtlasPageBound : ExportNoticeReason
/**
* A clipping mask names drawables this export does not contain.
*
* @property List maskDrawableIds The masking drawables that were left out.
*/
data class ClippingMaskNotInExport(val maskDrawableIds: List<String>) : ExportNoticeReason
/** An offscreen's clipping mask names a drawable that could not be written. */
data object OffscreenMaskNotInExport : ExportNoticeReason
/** A warp deformer carries no control-point grid, so it has no lattice to write. */
data object WarpDeformerHasNoLattice : ExportNoticeReason
/** A rotation deformer carries no pivot grid, so it has no transform to write. */
data object RotationDeformerHasNoPivot : ExportNoticeReason
/** A glue names a drawable that is not in this export. */
data object GlueNamesAnUnknownDrawable : ExportNoticeReason
/**
* An id too long for a moc's fixed-width id record, written shortened.
*
* @property Int recordByteWidth The record's width in bytes.
* @property String writtenId The id that was actually written.
*/
data class IdTruncated(val recordByteWidth: Int, val writtenId: String) : ExportNoticeReason
/**
* An id too long for the record whose truncation ALSO collided with another object's id, so a
* disambiguating suffix was fitted into the same width.
*
* @property Int recordByteWidth The record's width in bytes.
* @property String writtenId The id that was actually written.
*/
data class IdTruncatedAndDisambiguated(
val recordByteWidth: Int,
val writtenId: String,
) : ExportNoticeReason
// CMO3 reconcile - an edit with no counterpart in the retained graph.
/** The edited entity has no matching CMO3 source to reconcile the change onto. */
data object NoMatchingSourceToReconcile : ExportNoticeReason
/** A parameter changed between normal and blend-shape kind, which the lowering cannot express. */
data object ParameterKindChangeNotLowered : ExportNoticeReason
/** A deformer changed kind, which the lowering cannot express. */
data object DeformerKindChangeNotLowered : ExportNoticeReason
/** A warp-only edit (bilinear mode, lattice, keyforms) whose CMO3 source is not a warp deformer. */
data object DeformerEditNeedsWarpSource : ExportNoticeReason
/** A rotation-only edit (base angle, keyforms) whose CMO3 source is not a rotation deformer. */
data object DeformerEditNeedsRotationSource : ExportNoticeReason
/** Which texture a drawable samples is editor-only state that CMO3 does not carry. */
data object TextureSourceRebindingIsEditorOnly : ExportNoticeReason
/** The edited base geometry has a different vertex count than its CMO3 source. */
data object BaseGeometryVertexCountMismatch : ExportNoticeReason
/** The drawable has no UVs to reconcile. */
data object NoUvsToReconcile : ExportNoticeReason
/** The deformer was reparented to a part that has no CMO3 counterpart. */
data object DeformerHasNoPartToMoveTo : ExportNoticeReason
/**
* A static draw order that disagrees with its own keyform track.
*
* CMO3 re-derives the static from the track's head cell on import, so a disagreeing static has
* nowhere to live independently.
*/
data object StaticDrawOrderShadowedByKeyforms : ExportNoticeReason
/** A composite's static values disagree with the part's keyform tracks, which shadow them. */
data object CompositeStaticsShadowedByKeyforms : ExportNoticeReason
/** Part-typed composite masks are an Umamo extension; CMO3 carries only drawable-typed masks. */
data object PartMasksFlattenToDrawables : ExportNoticeReason
// CMO3 structural creation - a new entity with nowhere to be created.
/** The CMO3 model has no set of this kind to create the new entity into. */
data object NoSourceSetToCreateInto : ExportNoticeReason
/** The entity was created this session and has no CMO3 source yet, so panel order skipped it. */
data object CreatedEntityHasNoSourceYet : ExportNoticeReason
/** The created group is not in the edited parameter tree. */
data object CreatedGroupIsNotInTheEditedTree : ExportNoticeReason
/** The created drawable has no texture source to clone a CMO3 image chain from. */
data object CreatedDrawableHasNoTextureSource : ExportNoticeReason
/** A glued drawable has no CMO3 source, so the glue could not be synthesized. */
data object GluedDrawableHasNoSource : ExportNoticeReason
// CMO3 mesh topology and glue re-binding.
/**
* A mesh with more vertices than the editable mesh's short-indexed edge table can address.
*
* @property Int vertexCount The mesh's vertex count.
* @property Int maximumVertexCount The most the edge table can index.
*/
data class VertexCountExceedsEdgeTable(
val vertexCount: Int,
val maximumVertexCount: Int,
) : ExportNoticeReason
/** A glued mesh has no editable-mesh vertex-id table to re-bind the glue against. */
data object GluedMeshHasNoUidTable : ExportNoticeReason
/** A glue pair indexes past its mesh's vertex-id table. */
data object GluePairIndexesPastUidTable : ExportNoticeReason
// CMO3 keyforms.
/**
* A keyform set that will not bundle into the single grid CMO3 stores per object.
*
* @property KeyformBundleRejection rejection Which bundling rule the keyforms broke.
*/
data class KeyformCannotBundle(val rejection: KeyformBundleRejection) : ExportNoticeReason
/**
* A grid axis whose parameter has no CMO3 source.
*
* @property String parameterId The axis parameter's id.
*/
data class AxisParameterHasNoSource(val parameterId: String) : ExportNoticeReason
/**
* A blend shape whose parameter has no CMO3 source.
*
* @property String parameterId The blend-shape parameter's id.
*/
data class BlendShapeParameterHasNoSource(val parameterId: String) : ExportNoticeReason
/** Keyforms with no base mesh to bundle against. */
data object KeyformsWithoutBaseMesh : ExportNoticeReason
/** A fractional draw order, where CMO3 stores a whole number. */
data object FractionalDrawOrderNotStorable : ExportNoticeReason
/** A static glue intensity with no keyforms, which CMO3 has nowhere to put. */
data object StaticGlueIntensityWithoutKeyforms : ExportNoticeReason
// CMO3 document fields. The notice's subject is null for these - the reason names its own field,
// because the field name is chrome and would otherwise be untranslated English in the subject.
/** CMO3 stores no authored world origin; reopening derives it from the canvas center. */
data object NoAuthoredWorldOrigin : ExportNoticeReason
/** The model has no root parameter group to rebuild the parameter tree against. */
data object NoRootParameterGroup : ExportNoticeReason
/** The model has no root part to rebuild the parts panel order against. */
data object NoRootPart : ExportNoticeReason
/** The model has no parameter set to write a parameter order into. */
data object NoParameterSourceSet : ExportNoticeReason
/**
* The parameter order was adjusted to keep a combined pair adjacent, as CMO3 requires.
*
* @property String horizontalParameterId The pair's horizontal parameter id.
* @property String verticalParameterId The pair's vertical parameter id.
*/
data class CombinedPairReordered(
val horizontalParameterId: String,
val verticalParameterId: String,
) : ExportNoticeReason
/** The model has no canvas to reconcile a size against. */
data object NoCanvasToReconcile : ExportNoticeReason
/** The document carries no texture manager, so the source-artwork display mode has nowhere to go. */
data object NoTextureManagerToReconcile : ExportNoticeReason
/** The drawable lacks the texture input the chosen display mode samples, so its pointer was left as-is. */
data object NoTextureInputForDisplayMode : ExportNoticeReason
/** A fractional canvas size, where CMO3 stores whole pixels. */
data object FractionalCanvasSizeNotStorable : ExportNoticeReason
/** The tile has no packed entry on any atlas page, so there is no placement in the file to move. */
data object NoAtlasEntryToReconcile : ExportNoticeReason
/**
* A placement moved, but the page's stored pixels were not rebuilt to match.
*
* Where the art is RECORDED to sit is model state; the page image is the document's, and nothing
* here recomposes it. The written file is a faithful export of what was authored, and its atlas
* page still shows the art at its old spot until a repack redraws it.
*/
data object AtlasPageNotRecomposed : ExportNoticeReason
/** The tile's own art changed - its name, size, or source layer - which a repack cannot express. */
data object AtlasTileMetadataNotReconcilable : ExportNoticeReason
/** The drawable was rebound to different source art, which needs the art re-imported, not repacked. */
data object AtlasTileRebindingNotLowered : ExportNoticeReason
}
@@ -0,0 +1,291 @@
package org.umamo.interop
import org.umamo.runtime.eval.EPS_KEY
import org.umamo.runtime.keyform.ChannelValueInterpolator
import org.umamo.runtime.keyform.FormInterpolator
import org.umamo.runtime.keyform.refinedToUnion
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.ParameterId
/*
* Re-bundles a runtime entity's SPLIT keyform representation - one geometry grid plus independent
* per-channel tracks - back into the single dense grid every source format stores.
*
* The runtime deliberately keeps geometry and each render channel on their own axes so a rigger
* can key opacity without touching the mesh. Both CMO3 and MOC3 store one grid per object
* instead, with every cell carrying every value, so an export has to union the axes and
* re-interpolate each part onto the result. That inversion is exactly `refinedToUnion`'s
* contract, and doing it identically for both formats is the point of this file: two
* independent copies would drift the moment one gained a clamp or a tolerance the other lacked,
* and only a differential oracle would ever notice.
*
* @see <a href="https://docs.umamo.org/format/CMO3.md">CMO3.md §6 Export</a>
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §8 Export</a>
*/
/** What to do with a channel whose keyed span does not cover the bundled union axes. */
enum class OutOfSpanPolicy {
/**
* Reject the whole owner: the export cannot represent it and says so.
*
* CMO3's choice - a partially-representable owner would silently change the rig's shape, and CMO3
* can simply decline to write that object's grid.
*/
RejectOwner,
/**
* Drop the offending channel to its static value and bundle the rest, naming what was demoted.
*
* MOC3's choice, and not a preference: every MOC3 object MUST carry at least one keyform, so
* rejecting the owner would mean emitting nothing for it and producing a file the runtime cannot
* load. Losing one channel's animation is the strictly smaller loss.
*/
DemoteChannel,
}
/** One re-bundled cell: its coordinate, per-parameter key values, geometry, and channel values. */
class KeyformBundleCell(
val coordinate: IntArray,
val values: Map<ParameterId, Float>,
val geometry: Any?,
val channels: Map<FormChannel, ChannelValue>,
)
/**
* A dense bundled grid: the union axes and every cell of their cross product.
*
* @property List axes The union axes, geometry axes first.
* @property List cells Every cell, in first-axis-fastest order.
* @property List demotedChannels Channels dropped to their static under [OutOfSpanPolicy.DemoteChannel].
*/
class KeyformBundle(
val axes: List<KeyformAxis>,
val cells: List<KeyformBundleCell>,
val demotedChannels: List<FormChannel> = emptyList(),
)
/** The outcome of a bundling attempt. */
sealed interface KeyformBundleResult {
/** The entity bundled; [bundle] may still name demoted channels. */
class Bundled(val bundle: KeyformBundle) : KeyformBundleResult
/**
* The split state cannot be expressed as one grid, and the caller must report it.
*
* @property KeyformBundleRejection rejection Which bundling rule the keyforms broke.
*/
data class Unrepresentable(val rejection: KeyformBundleRejection) : KeyformBundleResult
}
/**
* Why a bundling attempt failed, for the caller to lower into an export notice.
*
* The bundler owns this vocabulary rather than [ExportNoticeReason] because the rule that was broken
* is a fact about bundling, not about any one format - the CMO3 lowering wraps it in
* [ExportNoticeReason.KeyformCannotBundle], and a future format would wrap the same cases its own way.
* Format-neutral for the same reason: the "one grid per object" clause a reader sees is supplied by
* the wrapping notice, not baked in here.
*/
sealed interface KeyformBundleRejection {
/** Geometry keys fall outside the union span, and geometry is never demotable. */
data object KeysOutsideGeometrySpan : KeyformBundleRejection
/** Channels key but there is no geometry to hang them on, where the caller requires geometry. */
data object ChannelKeysWithoutGeometry : KeyformBundleRejection
/**
* A channel keys outside its track span, under a policy that rejects the owner rather than
* demoting the channel.
*
* @property FormChannel channel The offending channel.
*/
data class KeysOutsideChannelSpan(val channel: FormChannel) : KeyformBundleRejection
}
/**
* Re-bundles a split representation onto union axes.
*
* The axis ORDER follows the geometry grid first, which is the order the import's fan-out preserved -
* so a round trip through split-then-bundled keeps the source's own axis order rather than inventing
* one. Cells are emitted first-axis-fastest, matching the mixed radix both formats index with.
*
* @param KeyformGrid? geometryGrid The geometry grid, or null for a channel-only owner.
* @param FormInterpolator geometryBlend The geometry interpolator (unused when there is no geometry).
* @param ChannelGrids channels The owner's channel tracks.
* @param Map statics Fallback value per relevant channel.
* @param Boolean requireGeometry Whether a geometry-less bundle is an error (warp/rotation).
* @param OutOfSpanPolicy outOfSpanPolicy What to do with a channel whose span misses the union.
* @return KeyformBundleResult The bundle - possibly with empty axes when fully unkeyed - or a rejection.
*/
fun <TGeometry> buildKeyformBundle(
geometryGrid: KeyformGrid<TGeometry>?,
geometryBlend: FormInterpolator<TGeometry>,
channels: ChannelGrids,
statics: Map<FormChannel, ChannelValue>,
requireGeometry: Boolean,
outOfSpanPolicy: OutOfSpanPolicy,
): KeyformBundleResult {
// Union keys per parameter, geometry axes first so the bundled axis order follows the
// geometry grid (the order the import's fan-out preserved).
val unionKeys = LinkedHashMap<ParameterId, FloatArray>()
fun mergeAxis(axis: KeyformAxis) {
val existing = unionKeys[axis.parameterId]
unionKeys[axis.parameterId] =
if (existing == null) axis.keys.copyOf() else mergedKeys(existing, axis.keys)
}
geometryGrid?.axes?.forEach(::mergeAxis)
for (grid in channels.gridsByChannel.values) {
grid.axes.forEach(::mergeAxis)
}
if (unionKeys.isEmpty()) {
// No parameter keys anywhere. An axis-less grid (one static cell) is a real shape in both
// formats and keeps its single cell; a grid-less, channel-less owner is fully unkeyed (empty).
//
// AXIS-LESS IS NOT VALUE-LESS. A channel track can be a single cell with no axes - an authored
// constant that was never lifted into the owner's static - and that value must win over the
// static, which in that state still holds its untouched constructor default. Falling straight
// back to the statics here would silently replace every such value.
val channelValues =
buildMap {
for ((channel, staticValue) in statics) {
put(channel, channels.gridsByChannel[channel]?.cells?.firstOrNull()?.form ?: staticValue)
}
}
val staticCell = geometryGrid?.cells?.firstOrNull()
if (staticCell != null) {
return KeyformBundleResult.Bundled(
KeyformBundle(
emptyList(),
listOf(KeyformBundleCell(IntArray(0), emptyMap(), staticCell.form, channelValues)),
),
)
}
// A geometry-less owner whose channels are all axis-less still has one cell's worth of values;
// emitting nothing would make the caller fall back to the same statics this just corrected.
if (channels.gridsByChannel.isNotEmpty()) {
return KeyformBundleResult.Bundled(
KeyformBundle(emptyList(), listOf(KeyformBundleCell(IntArray(0), emptyMap(), null, channelValues))),
)
}
return KeyformBundleResult.Bundled(KeyformBundle(emptyList(), emptyList()))
}
// Refine geometry over its own axes only (an empty ranges map suppresses the append path); every
// axis must then carry exactly the union keys - a span that does not cover them means an
// out-of-span key the bundle cannot represent without inventing values.
var axes: List<KeyformAxis>
var geometryByCoordinate: Map<List<Int>, TGeometry>
if (geometryGrid != null) {
val refined = geometryGrid.refinedToUnion(unionKeys, emptyMap(), geometryBlend)
for (axis in refined.axes) {
if (!axis.keys.contentEquals(unionKeys.getValue(axis.parameterId))) {
// Geometry is never demotable - it is the thing being exported.
return KeyformBundleResult.Unrepresentable(KeyformBundleRejection.KeysOutsideGeometrySpan)
}
}
axes = refined.axes
geometryByCoordinate = refined.cells.associate { cell -> cell.coordinate.toList() to cell.form }
// Replicate across parameters only channels key (the value is constant along them).
for ((parameterId, keys) in unionKeys) {
if (axes.none { it.parameterId == parameterId }) {
axes = axes + KeyformAxis(parameterId, keys)
geometryByCoordinate =
buildMap {
for (keyIndex in keys.indices) {
for ((coordinate, form) in geometryByCoordinate) {
put(coordinate + keyIndex, form)
}
}
}
}
}
} else {
if (requireGeometry) {
return KeyformBundleResult.Unrepresentable(KeyformBundleRejection.ChannelKeysWithoutGeometry)
}
axes = unionKeys.map { (parameterId, keys) -> KeyformAxis(parameterId, keys) }
geometryByCoordinate = emptyMap()
}
// Refine each channel over its own axes; a final-coordinate lookup then projects onto the
// channel's axis subset (the channel is constant along axes it does not key).
val channelLookups = HashMap<FormChannel, (IntArray) -> ChannelValue?>()
val demotedChannels = ArrayList<FormChannel>()
val finalAxisPosition = axes.mapIndexed { position, axis -> axis.parameterId to position }.toMap()
for ((channel, track) in channels.gridsByChannel) {
val refined = track.refinedToUnion(unionKeys, emptyMap(), ChannelValueInterpolator)
val outOfSpan =
refined.axes.any { axis -> !axis.keys.contentEquals(unionKeys.getValue(axis.parameterId)) }
if (outOfSpan) {
if (outOfSpanPolicy == OutOfSpanPolicy.RejectOwner) {
return KeyformBundleResult.Unrepresentable(
KeyformBundleRejection.KeysOutsideChannelSpan(channel),
)
}
// Demoted: no lookup is registered, so every cell falls back to the channel's static below.
demotedChannels.add(channel)
continue
}
val subPositions =
refined.axes.map { axis -> finalAxisPosition.getValue(axis.parameterId) }.toIntArray()
channelLookups[channel] =
{ coordinate ->
val subCoordinate = IntArray(subPositions.size) { axisIndex -> coordinate[subPositions[axisIndex]] }
refined.cellsByLinearIndex[refined.linearIndexOf(subCoordinate)]?.form
}
}
// Assemble every cell of the dense final grid.
val keyCounts = axes.map { it.keys.size }
val totalCells = keyCounts.fold(1) { product, count -> product * count }
val cells = ArrayList<KeyformBundleCell>(totalCells)
val coordinate = IntArray(axes.size)
for (cellOrdinal in 0 until totalCells) {
var remainder = cellOrdinal
for (axisIndex in axes.indices) {
coordinate[axisIndex] = remainder % keyCounts[axisIndex]
remainder /= keyCounts[axisIndex]
}
val cellCoordinate = coordinate.copyOf()
val values =
buildMap {
for (axisIndex in axes.indices) {
put(axes[axisIndex].parameterId, axes[axisIndex].keys[cellCoordinate[axisIndex]])
}
}
val channelValues =
buildMap {
for ((channel, staticValue) in statics) {
put(channel, channelLookups[channel]?.invoke(cellCoordinate) ?: staticValue)
}
}
cells.add(
KeyformBundleCell(cellCoordinate, values, geometryByCoordinate[cellCoordinate.toList()], channelValues),
)
}
return KeyformBundleResult.Bundled(KeyformBundle(axes, cells, demotedChannels))
}
/**
* The two key arrays merged ascending with evaluator-tolerance duplicates dropped.
*
* @param FloatArray first One axis's keys.
* @param FloatArray second The other's.
* @return FloatArray The merged ascending keys.
*/
private fun mergedKeys(first: FloatArray, second: FloatArray): FloatArray {
val sorted = (first + second).sortedArray()
val kept = ArrayList<Float>(sorted.size)
for (candidate in sorted) {
// The evaluator's own key-snap tolerance: two keys it cannot tell apart stay one key.
if (kept.isEmpty() || candidate - kept.last() >= EPS_KEY) {
kept.add(candidate)
}
}
return kept.toFloatArray()
}
@@ -0,0 +1,855 @@
package org.umamo.interop
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.Deformer
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.Glue
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterNode
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpForm
import org.umamo.runtime.model.WarpLatticeForm
import org.umamo.runtime.model.lineageRoot
/*
* The semantic diff between two PuppetModels - the input the CMO3 export reconcile dispatches on.
*
* The exporter never consumes the editor's Change log: it compares the session's FINAL model against
* a baseline re-imported from the retained CMO3 graph, so deletion is "baseline entity absent from
* the edited model", creation is the reverse, and an empty diff proves the graph needs no touch at
* all (which is what makes the no-change byte-identity gate structural rather than accidental).
*
* Completeness is the load-bearing property: any semantic difference between the two models MUST
* surface in some field below, because an edit the diff misses is an edit the export silently drops.
* Comparisons are bit-exact (FloatArray.contentEquals semantics; raw bits for loose scalars) - the
* diff's job is to detect that anything changed, not to judge whether the change is significant.
*/
/** The changed aspects of a [Parameter]. */
enum class ParameterField { NAME, RANGE, KIND }
/** The changed aspects of a [ParameterNode.Group]. */
enum class ParameterGroupField { NAME, INITIALLY_OPEN, CHILDREN }
/** The changed aspects of a [Part]. */
enum class PartField { NAME, VISIBLE, SKETCH, SELECTABLE, GROUP_MODE, DRAW_ORDER, CHILDREN, CHANNELS, COMPOSITE }
/** The changed aspects of a [Deformer]. */
enum class DeformerField {
KIND,
NAME,
PARENT,
PART,
SELECTABLE,
LATTICE,
QUAD_TRANSFORM,
BASE_ANGLE,
GEOMETRY,
CHANNELS,
STATICS,
BLEND_SHAPES,
}
/** The changed aspects of a [Drawable]. */
enum class DrawableField {
NAME,
PARENT_DEFORMER,
BLEND_MODE,
ALPHA_BLEND_MODE,
MASKED_BY,
INVERT_MASK,
CULLING,
VISIBLE,
SELECTABLE,
TEXTURE_SOURCE,
ATLAS_TILE,
MESH_TOPOLOGY,
MESH_POSITIONS,
MESH_UVS,
GEOMETRY,
CHANNELS,
STATICS,
BLEND_SHAPES,
}
/** The changed aspects of a [Glue]. */
enum class GlueField { PAIRS, CHANNELS, INTENSITY }
/** The changed aspects of an [AtlasTile]. */
enum class AtlasTileField {
/** Where the tile's art sits on its page - the authored half, and the only one an edit produces. */
PLACEMENT,
/** Its name, pixel size, or source binding: what the art itself is, not where it was packed. */
METADATA,
}
/** The changed document-level aspects of a [PuppetModel]. */
enum class DocumentField {
CANVAS_SIZE,
WORLD_ORIGIN,
RUNTIME_TARGET,
SOURCE_LAYER_DISPLAY,
PARAMETER_ORDER,
PARAMETER_LINKS,
PARAMETER_TREE,
ROOT_CHILDREN,
ATLAS_PAGES,
SOURCE_FILES,
}
/**
* One entity's difference between the baseline and the edited model: present only in the edited
* model (Created), only in the baseline (Deleted), or in both with changed fields (Changed).
*/
sealed interface EntityDiff<out TId, out TField> {
/** The entity's id in whichever model carries it. */
val id: TId
/** An entity the edited model has and the baseline does not - it needs CMO3-side synthesis. */
data class Created<out TId>(override val id: TId) : EntityDiff<TId, Nothing>
/** An entity the baseline has and the edited model does not - its CMO3 node must be removed. */
data class Deleted<out TId>(override val id: TId) : EntityDiff<TId, Nothing>
/** An entity present in both models whose [fields] differ. */
data class Changed<out TId, TField>(override val id: TId, val fields: Set<TField>) : EntityDiff<TId, TField>
}
/**
* One glue's difference. A glue has no id (CGlueSource carries none), so it is keyed by its
* ordered mesh pair plus an ordinal among glues sharing that pair.
*/
sealed interface GlueDiff {
val meshA: DrawableId
val meshB: DrawableId
val ordinal: Int
/** A glue only the edited model has. */
data class Created(
override val meshA: DrawableId,
override val meshB: DrawableId,
override val ordinal: Int,
) : GlueDiff
/** A glue only the baseline has. */
data class Deleted(
override val meshA: DrawableId,
override val meshB: DrawableId,
override val ordinal: Int,
) : GlueDiff
/** A glue present in both models whose [fields] differ. */
data class Changed(
override val meshA: DrawableId,
override val meshB: DrawableId,
override val ordinal: Int,
val fields: Set<GlueField>,
) : GlueDiff
}
/**
* The complete semantic difference between a baseline and an edited [PuppetModel].
*
* @property List parameters Per-parameter diffs.
* @property List parameterGroups Per-parameter-panel-group diffs (groups flattened out of the tree).
* @property List parts Per-part diffs.
* @property List deformers Per-deformer diffs.
* @property List drawables Per-drawable diffs.
* @property List glues Per-glue diffs.
* @property List atlasTiles Per-atlas-tile diffs.
* @property Set document Document-level field diffs.
*/
data class PuppetDiff(
val parameters: List<EntityDiff<ParameterId, ParameterField>>,
val parameterGroups: List<EntityDiff<ParameterGroupId, ParameterGroupField>>,
val parts: List<EntityDiff<PartId, PartField>>,
val deformers: List<EntityDiff<DeformerId, DeformerField>>,
val drawables: List<EntityDiff<DrawableId, DrawableField>>,
val glues: List<GlueDiff>,
val atlasTiles: List<EntityDiff<AtlasTileId, AtlasTileField>>,
val document: Set<DocumentField>,
) {
/** True when the models are semantically identical and the export graph needs no touch. */
val isEmpty: Boolean
get() =
parameters.isEmpty() &&
parameterGroups.isEmpty() &&
parts.isEmpty() &&
deformers.isEmpty() &&
drawables.isEmpty() &&
glues.isEmpty() &&
atlasTiles.isEmpty() &&
document.isEmpty()
}
/**
* Diffs [edited] against [baseline] (the model re-imported from the retained CMO3 graph).
*
* @param PuppetModel baseline The graph-derived baseline.
* @param PuppetModel edited The session's current model.
* @return PuppetDiff The complete semantic difference.
*/
fun diffPuppetModels(baseline: PuppetModel, edited: PuppetModel): PuppetDiff =
PuppetDiff(
parameters = diffEntities(baseline.parameters, edited.parameters, Parameter::id, ::parameterFields),
parameterGroups =
diffEntities(
flattenGroups(baseline.parameterTree),
flattenGroups(edited.parameterTree),
ParameterNode.Group::id,
::parameterGroupFields,
),
parts = diffEntities(baseline.parts, edited.parts, Part::id, ::partFields),
deformers = diffEntities(baseline.deformers, edited.deformers, Deformer::id, ::deformerFields),
drawables = diffEntities(baseline.drawables, edited.drawables, Drawable::id, ::drawableFields),
glues = diffGlues(baseline.glues, edited.glues),
atlasTiles = diffAtlasTiles(baseline.atlas.tiles, edited.atlas.tiles),
document = documentFields(baseline, edited),
)
/**
* Generic per-category entity diff: keys both lists by id, emits Created/Deleted for one-sided ids
* and Changed for shared ids whose [changedFields] set is non-empty. Baseline-order for stability.
*
* @param List baselineEntities The baseline's entities.
* @param List editedEntities The edited model's entities.
* @param Function idOf The entity's id accessor.
* @param Function changedFields The field comparator for a shared id.
* @return List The category's diffs, empty when nothing differs.
*/
private inline fun <TEntity, TId, TField> diffEntities(
baselineEntities: List<TEntity>,
editedEntities: List<TEntity>,
idOf: (TEntity) -> TId,
changedFields: (TEntity, TEntity) -> Set<TField>,
): List<EntityDiff<TId, TField>> {
val baselineById = baselineEntities.associateBy(idOf)
val editedById = editedEntities.associateBy(idOf)
val diffs = ArrayList<EntityDiff<TId, TField>>()
for (baselineEntity in baselineEntities) {
val entityId = idOf(baselineEntity)
val editedEntity = editedById[entityId]
if (editedEntity == null) {
diffs.add(EntityDiff.Deleted(entityId))
continue
}
if (baselineEntity === editedEntity) {
continue
}
val fields = changedFields(baselineEntity, editedEntity)
if (fields.isNotEmpty()) {
diffs.add(EntityDiff.Changed(entityId, fields))
}
}
for (editedEntity in editedEntities) {
val entityId = idOf(editedEntity)
if (entityId !in baselineById) {
diffs.add(EntityDiff.Created(entityId))
}
}
return diffs
}
private fun parameterFields(baseline: Parameter, edited: Parameter): Set<ParameterField> =
buildSet {
if (baseline.name != edited.name) {
add(ParameterField.NAME)
}
if (!floatEq(baseline.min, edited.min) || !floatEq(baseline.max, edited.max) || !floatEq(baseline.default, edited.default)) {
add(ParameterField.RANGE)
}
if (baseline.kind != edited.kind) {
add(ParameterField.KIND)
}
}
private fun parameterGroupFields(baseline: ParameterNode.Group, edited: ParameterNode.Group): Set<ParameterGroupField> =
buildSet {
if (baseline.name != edited.name) {
add(ParameterGroupField.NAME)
}
if (baseline.initiallyOpen != edited.initiallyOpen) {
add(ParameterGroupField.INITIALLY_OPEN)
}
if (nodeIdentities(baseline.children) != nodeIdentities(edited.children)) {
add(ParameterGroupField.CHILDREN)
}
}
private fun partFields(baseline: Part, edited: Part): Set<PartField> =
buildSet {
if (baseline.name != edited.name) {
add(PartField.NAME)
}
if (baseline.isVisible != edited.isVisible) {
add(PartField.VISIBLE)
}
if (baseline.isSketch != edited.isSketch) {
add(PartField.SKETCH)
}
if (baseline.isSelectable != edited.isSelectable) {
add(PartField.SELECTABLE)
}
if (baseline.groupMode != edited.groupMode) {
add(PartField.GROUP_MODE)
}
if (baseline.drawOrder != edited.drawOrder) {
add(PartField.DRAW_ORDER)
}
if (baseline.children != edited.children) {
add(PartField.CHILDREN)
}
if (!channelGridsEqual(baseline.channelGrids, edited.channelGrids)) {
add(PartField.CHANNELS)
}
if (baseline.composite != edited.composite) {
add(PartField.COMPOSITE)
}
}
private fun deformerFields(baseline: Deformer, edited: Deformer): Set<DeformerField> =
buildSet {
if (baseline::class != edited::class) {
// A kind swap under one id has no edit op; surfacing it beats mis-reading field diffs.
add(DeformerField.KIND)
return@buildSet
}
if (baseline.name != edited.name) {
add(DeformerField.NAME)
}
if (baseline.parent != edited.parent) {
add(DeformerField.PARENT)
}
if (baseline.partId != edited.partId) {
add(DeformerField.PART)
}
if (baseline.isSelectable != edited.isSelectable) {
add(DeformerField.SELECTABLE)
}
when (baseline) {
is Deformer.Warp -> {
val editedWarp = edited as Deformer.Warp
if (baseline.rows != editedWarp.rows || baseline.columns != editedWarp.columns) {
add(DeformerField.LATTICE)
}
if (baseline.isQuadTransform != editedWarp.isQuadTransform) {
add(DeformerField.QUAD_TRANSFORM)
}
if (!gridEquals(baseline.geometryGrid, editedWarp.geometryGrid, ::warpLatticeFormEqual)) {
add(DeformerField.GEOMETRY)
}
if (
!floatEq(baseline.opacity, editedWarp.opacity) ||
baseline.multiplyColor != editedWarp.multiplyColor ||
baseline.screenColor != editedWarp.screenColor
) {
add(DeformerField.STATICS)
}
if (!blendShapesEqual(baseline.blendShapes, editedWarp.blendShapes, ::warpFormEqual)) {
add(DeformerField.BLEND_SHAPES)
}
}
is Deformer.Rotation -> {
val editedRotation = edited as Deformer.Rotation
if (!floatEq(baseline.baseAngle, editedRotation.baseAngle)) {
add(DeformerField.BASE_ANGLE)
}
if (!gridEquals(baseline.geometryGrid, editedRotation.geometryGrid, ::rotationPivotFormEqual)) {
add(DeformerField.GEOMETRY)
}
if (
!floatEq(baseline.opacity, editedRotation.opacity) ||
baseline.multiplyColor != editedRotation.multiplyColor ||
baseline.screenColor != editedRotation.screenColor ||
baseline.flipX != editedRotation.flipX ||
baseline.flipY != editedRotation.flipY
) {
add(DeformerField.STATICS)
}
if (!blendShapesEqual(baseline.blendShapes, editedRotation.blendShapes, ::rotationFormEqual)) {
add(DeformerField.BLEND_SHAPES)
}
}
}
if (!channelGridsEqual(baseline.channelGrids, edited.channelGrids)) {
add(DeformerField.CHANNELS)
}
}
/**
* Diffs the atlas inventory, comparing only the tiles BOTH models carry.
*
* Set membership is deliberately not a difference here. A tile is the art the document holds, which
* arrives and leaves with an import rather than with an edit - and the two models being compared do not
* always track it the same way: a MOC3-origin conversion synthesizes model images into the graph that
* its puppet, which never had layered art, does not know about. Reporting those as deletions would
* describe an edit nobody made, on a path with nothing to reconcile.
*
* That is safe precisely because no edit can add or remove art today. When re-import can (it is the
* whole point of that phase), this grows the created/deleted arms together with the lowering that
* serves them, rather than reporting a difference nothing acts on.
*
* @param List baseline The graph-derived tiles.
* @param List edited The session's tiles.
* @return List One Changed entry per shared tile that differs.
*/
private fun diffAtlasTiles(baseline: List<AtlasTile>, edited: List<AtlasTile>): List<EntityDiff<AtlasTileId, AtlasTileField>> {
val editedById = edited.associateBy { tile -> tile.id }
// A reloaded tile is a new tile whose lineage root is the baseline's id; it is the same art to the
// graph, compared under the root so the reload reads as that tile changing.
val editedByRoot = edited.filter { tile -> tile.replaces != null }.associateBy { tile -> tile.id.lineageRoot }
return baseline.mapNotNull { baselineTile ->
val editedTile = editedById[baselineTile.id] ?: editedByRoot[baselineTile.id] ?: return@mapNotNull null
val fields = atlasTileFields(baselineTile, editedTile)
if (fields.isEmpty()) null else EntityDiff.Changed(baselineTile.id, fields)
}
}
/**
* The changed aspects of one atlas tile.
*
* @param AtlasTile baseline The graph-derived tile.
* @param AtlasTile edited The session's tile.
* @return Set<AtlasTileField> The fields that differ.
*/
private fun atlasTileFields(baseline: AtlasTile, edited: AtlasTile): Set<AtlasTileField> =
buildSet {
if (baseline.placement != edited.placement) {
add(AtlasTileField.PLACEMENT)
}
if (
baseline.name != edited.name ||
baseline.width != edited.width ||
baseline.height != edited.height ||
baseline.source != edited.source
) {
add(AtlasTileField.METADATA)
}
}
private fun drawableFields(baseline: Drawable, edited: Drawable): Set<DrawableField> =
buildSet {
if (baseline.name != edited.name) {
add(DrawableField.NAME)
}
if (baseline.parentDeformerId != edited.parentDeformerId) {
add(DrawableField.PARENT_DEFORMER)
}
if (baseline.blendMode != edited.blendMode) {
add(DrawableField.BLEND_MODE)
}
if (baseline.alphaBlendMode != edited.alphaBlendMode) {
add(DrawableField.ALPHA_BLEND_MODE)
}
if (baseline.maskedBy != edited.maskedBy) {
add(DrawableField.MASKED_BY)
}
if (baseline.invertMask != edited.invertMask) {
add(DrawableField.INVERT_MASK)
}
if (baseline.culling != edited.culling) {
add(DrawableField.CULLING)
}
if (baseline.isVisible != edited.isVisible) {
add(DrawableField.VISIBLE)
}
if (baseline.isSelectable != edited.isSelectable) {
add(DrawableField.SELECTABLE)
}
if (baseline.textureSourceId != edited.textureSourceId) {
add(DrawableField.TEXTURE_SOURCE)
}
// Absence is "not tracked", not "unbound", for the same reason the page list is only compared
// when there is an atlas: a drawable the model carries no art for says nothing about the art the
// graph carries for it.
// Compared under the lineage root: a drawable carried onto its tile's reload replacement still
// samples the same art as far as the graph knows.
val editedTileId = edited.atlasTileId
if (editedTileId != null && baseline.atlasTileId?.lineageRoot != editedTileId.lineageRoot) {
add(DrawableField.ATLAS_TILE)
}
addAll(meshFields(baseline.mesh, edited.mesh))
if (!gridEquals(restOnlyAsUnkeyed(baseline.geometryGrid), restOnlyAsUnkeyed(edited.geometryGrid), ::meshDeltaFormEqual)) {
add(DrawableField.GEOMETRY)
}
if (!channelGridsEqual(baseline.channelGrids, edited.channelGrids)) {
add(DrawableField.CHANNELS)
}
if (
!floatEq(baseline.drawOrder, edited.drawOrder) ||
!floatEq(baseline.opacity, edited.opacity) ||
baseline.multiplyColor != edited.multiplyColor ||
baseline.screenColor != edited.screenColor
) {
add(DrawableField.STATICS)
}
if (!blendShapesEqual(baseline.blendShapes, edited.blendShapes, ::meshFormEqual)) {
add(DrawableField.BLEND_SHAPES)
}
}
/**
* The mesh aspect of a drawable diff. A vertex-count or triangulation change (or a mesh appearing/
* disappearing) is MESH_TOPOLOGY; with topology intact, moved vertices are MESH_POSITIONS and
* remapped texels MESH_UVS - the split the lowering dispatches on, since topology forces a full
* GEditableMesh2 rebuild while the others patch arrays in place.
*
* @param DrawableMesh? baseline The baseline's mesh.
* @param DrawableMesh? edited The edited model's mesh.
* @return Set The changed mesh fields.
*/
private fun meshFields(baseline: DrawableMesh?, edited: DrawableMesh?): Set<DrawableField> {
if (baseline === edited) {
return emptySet()
}
if (baseline == null || edited == null) {
return setOf(DrawableField.MESH_TOPOLOGY)
}
if (baseline.vertexCount != edited.vertexCount || !baseline.indices.contentEquals(edited.indices)) {
return setOf(DrawableField.MESH_TOPOLOGY)
}
return buildSet {
if (!baseline.positions.contentEquals(edited.positions)) {
add(DrawableField.MESH_POSITIONS)
}
if (!baseline.uvs.contentEquals(edited.uvs)) {
add(DrawableField.MESH_UVS)
}
}
}
private fun diffGlues(baselineGlues: List<Glue>, editedGlues: List<Glue>): List<GlueDiff> {
if (baselineGlues === editedGlues) {
return emptyList()
}
// A glue has no id: key by the ordered mesh pair, with an ordinal among same-pair glues.
val baselineByPair = baselineGlues.groupBy { glue -> glue.meshA to glue.meshB }
val editedByPair = editedGlues.groupBy { glue -> glue.meshA to glue.meshB }
val diffs = ArrayList<GlueDiff>()
for ((pair, baselineList) in baselineByPair) {
val editedList = editedByPair[pair].orEmpty()
for (ordinal in baselineList.indices) {
val editedGlue = editedList.getOrNull(ordinal)
if (editedGlue == null) {
diffs.add(GlueDiff.Deleted(pair.first, pair.second, ordinal))
continue
}
val fields = glueFields(baselineList[ordinal], editedGlue)
if (fields.isNotEmpty()) {
diffs.add(GlueDiff.Changed(pair.first, pair.second, ordinal, fields))
}
}
}
for ((pair, editedList) in editedByPair) {
val baselineCount = baselineByPair[pair].orEmpty().size
for (ordinal in baselineCount until editedList.size) {
diffs.add(GlueDiff.Created(pair.first, pair.second, ordinal))
}
}
return diffs
}
private fun glueFields(baseline: Glue, edited: Glue): Set<GlueField> {
if (baseline === edited) {
return emptySet()
}
return buildSet {
val pairsEqual =
baseline.pairs.size == edited.pairs.size &&
baseline.pairs.indices.all { pairIndex ->
val baselinePair = baseline.pairs[pairIndex]
val editedPair = edited.pairs[pairIndex]
baselinePair.indexA == editedPair.indexA &&
baselinePair.indexB == editedPair.indexB &&
floatEq(baselinePair.weightA, editedPair.weightA) &&
floatEq(baselinePair.weightB, editedPair.weightB)
}
if (!pairsEqual) {
add(GlueField.PAIRS)
}
if (!channelGridsEqual(baseline.channelGrids, edited.channelGrids)) {
add(GlueField.CHANNELS)
}
if (!floatEq(baseline.intensity, edited.intensity)) {
add(GlueField.INTENSITY)
}
}
}
private fun documentFields(baseline: PuppetModel, edited: PuppetModel): Set<DocumentField> =
buildSet {
if (!floatEq(baseline.canvasWidth, edited.canvasWidth) || !floatEq(baseline.canvasHeight, edited.canvasHeight)) {
add(DocumentField.CANVAS_SIZE)
}
if (!floatEq(baseline.worldOriginX, edited.worldOriginX) || !floatEq(baseline.worldOriginZ, edited.worldOriginZ)) {
add(DocumentField.WORLD_ORIGIN)
}
if (baseline.runtimeTarget != edited.runtimeTarget) {
add(DocumentField.RUNTIME_TARGET)
}
if (baseline.rendersFromSourceLayers != edited.rendersFromSourceLayers) {
add(DocumentField.SOURCE_LAYER_DISPLAY)
}
// The page LIST, not the tiles on it: a page appearing, disappearing, or resizing changes what
// every placement on it means, and no per-tile diff would say so.
//
// Only when the edited model actually tracks an atlas. Carrying none is "this model has no
// source art" - a MOC3 origin never had any - and is not the same as an atlas that was emptied;
// comparing against a graph that does carry one would report a deletion nobody performed.
if (edited.atlas.tiles.isNotEmpty() && baseline.atlas.pages != edited.atlas.pages) {
add(DocumentField.ATLAS_PAGES)
}
// Document order of the flat parameter list is semantic in CMO3: combined (2D) pairs are
// encoded positionally (the Y axis is the next source after its combined X).
if (baseline.parameters.map(Parameter::id) != edited.parameters.map(Parameter::id)) {
add(DocumentField.PARAMETER_ORDER)
}
if (baseline.parameterLinks != edited.parameterLinks) {
add(DocumentField.PARAMETER_LINKS)
}
if (nodeIdentities(baseline.parameterTree) != nodeIdentities(edited.parameterTree)) {
add(DocumentField.PARAMETER_TREE)
}
if (baseline.rootChildren != edited.rootChildren) {
add(DocumentField.ROOT_CHILDREN)
}
// The file each source record points at - its name, path, and modification time - and nothing
// else about the record: the inventory and the hashes change on every reload and have no CMO3
// home, so they must not turn a reload into a document change the export cannot lower. Only
// the records BOTH models list: a record one side lacks is art added this session, or a page
// slice a fresh synthesis minted under its own id, and has no layered image to repoint.
if (sourceFilesChanged(baseline, edited)) {
add(DocumentField.SOURCE_FILES)
}
}
/**
* Whether any source record both models list points at a different file in [edited]: another name,
* path, or modification time.
*
* @param PuppetModel baseline The graph-derived baseline.
* @param PuppetModel edited The session's current model.
* @return Boolean True when a shared record was repointed.
*/
private fun sourceFilesChanged(baseline: PuppetModel, edited: PuppetModel): Boolean {
val baselineById = baseline.sources.associateBy { source -> source.id }
return edited.sources.any { source ->
val before = baselineById[source.id] ?: return@any false
before.name != source.name || before.path != source.path || before.lastModified != source.lastModified
}
}
/**
* The identity sequence of one tree level - a Param's id or a Group's id, in order. Group content
* changes are reported per group (CHILDREN), so tree-level comparisons only look at this level's
* ordered identities.
*
* @param List nodes The level's nodes.
* @return List One identity token per node.
*/
private fun nodeIdentities(nodes: List<ParameterNode>): List<String> =
nodes.map { node ->
when (node) {
is ParameterNode.Param -> "p:${node.id.raw}"
is ParameterNode.Group -> "g:${node.id.raw}"
}
}
private fun flattenGroups(tree: List<ParameterNode>): List<ParameterNode.Group> {
val groups = ArrayList<ParameterNode.Group>()
fun walk(nodes: List<ParameterNode>) {
for (node in nodes) {
if (node is ParameterNode.Group) {
groups.add(node)
walk(node.children)
}
}
}
walk(tree)
return groups
}
/*
* Bit-exact equality helpers. Two independent imports of the same graph produce bit-identical
* floats, so raw-bits comparison never yields a false diff there - while an edit that flips only a
* sign bit (0.0 vs -0.0) still surfaces. Every helper takes the `===` fast path first: the common
* call compares a model against itself or against structurally shared sub-objects.
*/
private fun floatEq(baseline: Float, edited: Float): Boolean = baseline.toRawBits() == edited.toRawBits()
/**
* A drawable's geometry grid with the rest-only shape read as unkeyed: an axis-less grid holding one
* cell of zero deltas IS the unkeyed drawable, since both mean "the base mesh, nothing keyed". The
* two spellings arise from the formats - every CMO3 source carries a default form, so an unkeyed
* drawable exports as that one cell and re-imports as this grid - and neither is an edit of the
* other, so the diff must not call it one.
*
* @param KeyformGrid? grid The drawable's geometry grid.
* @return KeyformGrid? The grid, or null when it is the rest-only shape.
*/
private fun restOnlyAsUnkeyed(grid: KeyformGrid<MeshDeltaForm>?): KeyformGrid<MeshDeltaForm>? {
if (grid == null || grid.axes.isNotEmpty() || grid.cells.size != 1) {
return grid
}
val deltas = grid.cells.single().form.positionDeltas
return if (deltas.all { delta -> delta == 0f }) null else grid
}
private fun <TForm> gridEquals(
baseline: KeyformGrid<TForm>?,
edited: KeyformGrid<TForm>?,
formEqual: (TForm, TForm) -> Boolean,
): Boolean {
if (baseline === edited) {
return true
}
if (baseline == null || edited == null) {
return false
}
if (baseline.axes.size != edited.axes.size || baseline.cells.size != edited.cells.size) {
return false
}
for (axisIndex in baseline.axes.indices) {
val baselineAxis = baseline.axes[axisIndex]
val editedAxis = edited.axes[axisIndex]
if (baselineAxis.parameterId != editedAxis.parameterId || !baselineAxis.keys.contentEquals(editedAxis.keys)) {
return false
}
}
// Cells compare by coordinate, not list position: the import and the edit ops are both free to
// order cells differently without that being a semantic change.
val baselineByCoordinate = HashMap<List<Int>, TForm>(baseline.cells.size)
for (cell in baseline.cells) {
baselineByCoordinate[cell.coordinate.toList()] = cell.form
}
for (cell in edited.cells) {
val baselineForm = baselineByCoordinate[cell.coordinate.toList()] ?: return false
if (!formEqual(baselineForm, cell.form)) {
return false
}
}
return true
}
private fun channelGridsEqual(baseline: ChannelGrids, edited: ChannelGrids): Boolean {
if (baseline === edited) {
return true
}
if (baseline.gridsByChannel.keys != edited.gridsByChannel.keys) {
return false
}
for ((channel, baselineGrid) in baseline.gridsByChannel) {
val editedGrid = edited.gridsByChannel.getValue(channel)
if (!gridEquals(baselineGrid, editedGrid) { baselineValue, editedValue -> baselineValue == editedValue }) {
return false
}
}
return true
}
private fun <TForm : Any> blendShapesEqual(
baseline: List<BlendShapeBinding<TForm>>,
edited: List<BlendShapeBinding<TForm>>,
formEqual: (TForm, TForm) -> Boolean,
): Boolean {
if (baseline === edited) {
return true
}
if (baseline.size != edited.size) {
return false
}
for (bindingIndex in baseline.indices) {
val baselineBinding = baseline[bindingIndex]
val editedBinding = edited[bindingIndex]
if (
baselineBinding.parameterId != editedBinding.parameterId ||
!baselineBinding.keys.contentEquals(editedBinding.keys) ||
baselineBinding.neutralIndex != editedBinding.neutralIndex ||
baselineBinding.limits != editedBinding.limits ||
baselineBinding.forms.size != editedBinding.forms.size
) {
return false
}
for (formIndex in baselineBinding.forms.indices) {
val baselineForm = baselineBinding.forms[formIndex]
val editedForm = editedBinding.forms[formIndex]
if (baselineForm == null || editedForm == null) {
if (baselineForm !== editedForm) {
return false
}
continue
}
if (!formEqual(baselineForm, editedForm)) {
return false
}
}
}
return true
}
private fun meshDeltaFormEqual(baseline: MeshDeltaForm, edited: MeshDeltaForm): Boolean =
baseline === edited || baseline.positionDeltas.contentEquals(edited.positionDeltas)
private fun warpLatticeFormEqual(baseline: WarpLatticeForm, edited: WarpLatticeForm): Boolean =
baseline === edited || baseline.controlPoints.contentEquals(edited.controlPoints)
private fun rotationPivotFormEqual(baseline: RotationPivotForm, edited: RotationPivotForm): Boolean =
baseline === edited ||
(
floatEq(baseline.originX, edited.originX) &&
floatEq(baseline.originY, edited.originY) &&
floatEq(baseline.angle, edited.angle) &&
floatEq(baseline.scale, edited.scale)
)
private fun meshFormEqual(baseline: MeshForm, edited: MeshForm): Boolean =
baseline === edited ||
(
baseline.positionDeltas.contentEquals(edited.positionDeltas) &&
floatEq(baseline.drawOrder, edited.drawOrder) &&
floatEq(baseline.opacity, edited.opacity) &&
baseline.multiplyColor == edited.multiplyColor &&
baseline.screenColor == edited.screenColor
)
private fun warpFormEqual(baseline: WarpForm, edited: WarpForm): Boolean =
baseline === edited ||
(
baseline.controlPoints.contentEquals(edited.controlPoints) &&
floatEq(baseline.opacity, edited.opacity) &&
baseline.multiplyColor == edited.multiplyColor &&
baseline.screenColor == edited.screenColor
)
private fun rotationFormEqual(baseline: RotationForm, edited: RotationForm): Boolean =
baseline === edited ||
(
floatEq(baseline.originX, edited.originX) &&
floatEq(baseline.originY, edited.originY) &&
floatEq(baseline.angle, edited.angle) &&
floatEq(baseline.scale, edited.scale) &&
baseline.flipX == edited.flipX &&
baseline.flipY == edited.flipY &&
floatEq(baseline.opacity, edited.opacity) &&
baseline.multiplyColor == edited.multiplyColor &&
baseline.screenColor == edited.screenColor
)
@@ -0,0 +1,97 @@
package org.umamo.interop
import org.umamo.format.cmo3.Cmo3TargetVersion
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.runtime.model.RuntimeTarget
/*
* The RuntimeTarget ↔ format-version mapping: which Cmo3TargetVersion / MocVersion each runtime
* target reads from and persists as. It lives here rather than on the enum so :runtime stays free
* of :format - the target's capability matrix (supports / restrictedFeatures) is runtime policy,
* while the version encodings are a format concern owned by the conversion layer.
*/
/**
* The moc version a MOC3 export of this target bakes: the matching version for a Cubism target,
* the latest for NoTarget (nothing restricted), and V50 for Ayagami (its effective level).
*
* @return MocVersion The bake target.
*/
fun RuntimeTarget.mocVersion(): MocVersion =
when (this) {
RuntimeTarget.NoTarget -> MocVersion.V53
RuntimeTarget.Ayagami -> MocVersion.V50
RuntimeTarget.Cubism30 -> MocVersion.V30
RuntimeTarget.Cubism33 -> MocVersion.V33
RuntimeTarget.Cubism40 -> MocVersion.V40
RuntimeTarget.Cubism42 -> MocVersion.V42
RuntimeTarget.Cubism50 -> MocVersion.V50
RuntimeTarget.Cubism53 -> MocVersion.V53
}
/**
* The CMO3 target version this target persists as, or null for NoTarget - a target-less document
* has no target VERSION and persists through the latest sentinel instead (see
* [cmo3TargetVersionNo]). Ayagami has no CMO3 encoding of its own, so it persists at its
* effective Cubism level: the gating level survives a CMO3 round-trip even though the Ayagami
* identity cannot (a reopen shows Cubism 5.0; UMA will carry the identity).
*
* @return Cmo3TargetVersion? The CMO3-side version, or null for NoTarget.
*/
fun RuntimeTarget.cmo3TargetVersion(): Cmo3TargetVersion? =
when (this) {
RuntimeTarget.NoTarget -> null
// Ayagami writes its effective Cubism level, in lockstep with cubismLevel and mocVersion.
RuntimeTarget.Ayagami -> Cmo3TargetVersion.V50
RuntimeTarget.Cubism30 -> Cmo3TargetVersion.V30
RuntimeTarget.Cubism33 -> Cmo3TargetVersion.V33
RuntimeTarget.Cubism40 -> Cmo3TargetVersion.V40
RuntimeTarget.Cubism42 -> Cmo3TargetVersion.V42
RuntimeTarget.Cubism50 -> Cmo3TargetVersion.V50
RuntimeTarget.Cubism53 -> Cmo3TargetVersion.V53
}
/**
* The raw `targetVersionNo` a CMO3 save persists for this target: the version's literal, or the
* "SDK(N/A)/Latest Cubism" sentinel for NoTarget. Every target persists something.
*
* @return Int The value to write.
*/
fun RuntimeTarget.cmo3TargetVersionNo(): Int =
// CMO3: CModelSource field targetVersionNo.
cmo3TargetVersion()?.versionNo ?: Cmo3TargetVersion.LATEST_VERSION_NO
/**
* Maps a CMO3 document's decoded target version to the runtime target it selects, with unknown or
* absent values falling back to no restriction.
*
* @param Cmo3TargetVersion? version The decoded CMO3 target version, or null for unknown/absent.
* @return RuntimeTarget The matching target, or [RuntimeTarget.NoTarget] for null.
*/
fun runtimeTargetOfCmo3Target(version: Cmo3TargetVersion?): RuntimeTarget =
when (version) {
null -> RuntimeTarget.NoTarget
Cmo3TargetVersion.V30 -> RuntimeTarget.Cubism30
Cmo3TargetVersion.V33 -> RuntimeTarget.Cubism33
Cmo3TargetVersion.V40 -> RuntimeTarget.Cubism40
Cmo3TargetVersion.V42 -> RuntimeTarget.Cubism42
Cmo3TargetVersion.V50 -> RuntimeTarget.Cubism50
Cmo3TargetVersion.V53 -> RuntimeTarget.Cubism53
}
/**
* Maps a baked moc's version byte to the runtime target it implies - the moc version is a hard
* fact of the file, so an imported .moc3 starts at the matching Cubism target.
*
* @param MocVersion version The moc version.
* @return RuntimeTarget The matching Cubism target.
*/
fun runtimeTargetOfMocVersion(version: MocVersion): RuntimeTarget =
when (version) {
MocVersion.V30 -> RuntimeTarget.Cubism30
MocVersion.V33 -> RuntimeTarget.Cubism33
MocVersion.V40 -> RuntimeTarget.Cubism40
MocVersion.V42 -> RuntimeTarget.Cubism42
MocVersion.V50 -> RuntimeTarget.Cubism50
MocVersion.V53 -> RuntimeTarget.Cubism53
}
@@ -0,0 +1,37 @@
package org.umamo.interop.art
/**
* Where a later artwork file's canvas is anchored on the document canvas when it is added: the nine
* anchors the art programs' own Canvas Size dialogs offer, so a file whose canvas the artist resized
* around some anchor lands back where the art was drawn. A file the same size as the document canvas
* lands identically under every anchor.
*
* @property String key The stable setting and strip value.
* @property Float horizontal How far along the document's width the file's width is anchored (0 left, 0.5 center, 1 right).
* @property Float vertical How far along the document's height the file's height is anchored (0 top, 0.5 middle, 1 bottom).
*/
enum class ArtworkAnchor(val key: String, val horizontal: Float, val vertical: Float) {
TopLeft("topLeft", 0f, 0f),
Top("top", 0.5f, 0f),
TopRight("topRight", 1f, 0f),
Left("left", 0f, 0.5f),
Center("center", 0.5f, 0.5f),
Right("right", 1f, 0.5f),
BottomLeft("bottomLeft", 0f, 1f),
Bottom("bottom", 0.5f, 1f),
BottomRight("bottomRight", 1f, 1f),
;
companion object {
/** The anchor a fresh install adds with: the art programs' own default when a canvas is resized. */
val Default: ArtworkAnchor = Center
/**
* The anchor a setting or strip value names, or [Default] for a value no anchor carries.
*
* @param String? key The value.
* @return ArtworkAnchor The anchor.
*/
fun fromKey(key: String?): ArtworkAnchor = entries.firstOrNull { anchor -> anchor.key == key } ?: Default
}
}
@@ -0,0 +1,72 @@
package org.umamo.interop.art
import org.umamo.format.art.LayerBlend
import org.umamo.runtime.model.BlendMode
/**
* How one source-art blend lands on the model's blend modes.
*
* Three outcomes, kept distinct because the rigger's remedy differs: an exact mapping needs no word,
* an approximation is worth a notice so an artist who leaned on the exact formula knows, and an
* unsupported blend falls back to Normal with a notice so the change is never silent.
*/
sealed interface LayerBlendMapping {
/** The blend mode the model gets, Normal for an unsupported one. */
val blendMode: BlendMode
/** The model has this blend under the same formula. */
data class Exact(override val blendMode: BlendMode) : LayerBlendMapping
/** The model's nearest blend, not the same formula. */
data class Approximate(override val blendMode: BlendMode) : LayerBlendMapping
/** No model blend comes close; the drawable renders Normal. */
data object Unsupported : LayerBlendMapping {
override val blendMode: BlendMode get() = BlendMode.Normal
}
}
/**
* Maps a source-art blend onto the model's blend modes.
*
* The model's set is Cubism 5.3's (see [BlendMode]), which covers most of the PSD / Clip Studio /
* Krita vocabulary one to one. Glow Dodge is Clip Studio's clamped Color Dodge and lands there as an
* approximation; the HSL modes the model lacks (Saturation, Luminosity), the two comparison modes
* (Darker / Lighter Color), and the arithmetic ones (Subtract, Divide, Vivid / Pin Light, Hard Mix,
* Difference, Exclusion) have no model equivalent at all.
*
* @param LayerBlend blend The source layer's blend.
* @return LayerBlendMapping Where it lands.
*/
fun mapLayerBlend(blend: LayerBlend): LayerBlendMapping =
when (blend) {
LayerBlend.Normal -> LayerBlendMapping.Exact(BlendMode.Normal)
LayerBlend.Darken -> LayerBlendMapping.Exact(BlendMode.Darken)
LayerBlend.Multiply -> LayerBlendMapping.Exact(BlendMode.Multiply)
LayerBlend.ColorBurn -> LayerBlendMapping.Exact(BlendMode.ColorBurn)
LayerBlend.LinearBurn -> LayerBlendMapping.Exact(BlendMode.LinearBurn)
LayerBlend.Lighten -> LayerBlendMapping.Exact(BlendMode.Lighten)
LayerBlend.Screen -> LayerBlendMapping.Exact(BlendMode.Screen)
LayerBlend.ColorDodge -> LayerBlendMapping.Exact(BlendMode.ColorDodge)
LayerBlend.GlowDodge -> LayerBlendMapping.Approximate(BlendMode.ColorDodge)
LayerBlend.Add -> LayerBlendMapping.Exact(BlendMode.Additive)
LayerBlend.AddGlow -> LayerBlendMapping.Exact(BlendMode.AdditiveGlow)
LayerBlend.Overlay -> LayerBlendMapping.Exact(BlendMode.Overlay)
LayerBlend.SoftLight -> LayerBlendMapping.Exact(BlendMode.SoftLight)
LayerBlend.HardLight -> LayerBlendMapping.Exact(BlendMode.HardLight)
LayerBlend.LinearLight -> LayerBlendMapping.Exact(BlendMode.LinearLight)
LayerBlend.Hue -> LayerBlendMapping.Exact(BlendMode.Hue)
LayerBlend.Color -> LayerBlendMapping.Exact(BlendMode.Color)
LayerBlend.Subtract,
LayerBlend.DarkerColor,
LayerBlend.LighterColor,
LayerBlend.VividLight,
LayerBlend.PinLight,
LayerBlend.HardMix,
LayerBlend.Difference,
LayerBlend.Exclusion,
LayerBlend.Saturation,
LayerBlend.Luminosity,
LayerBlend.Divide,
-> LayerBlendMapping.Unsupported
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,43 @@
package org.umamo.interop.art
import org.umamo.format.art.LayerBlend
import org.umamo.format.art.SourceLayerKind
import org.umamo.runtime.model.BlendMode
/**
* One thing an artwork import could not carry onto the model as drawn, named so the rigger can act
* on it. Anything unrepresentable surfaces as a notice, never as a silent drop - the same rule the
* export notices follow. Presentation-free: the shell logs each one and raises a single status
* notice.
*/
sealed interface SourceArtImportNotice {
/** A text, vector, adjustment, or fill layer: no stored pixels, so no drawable. */
data class NonRasterLayer(val layerName: String, val kind: SourceLayerKind) : SourceArtImportNotice
/** A raster layer with no pixel over the alpha threshold: nothing to mesh, so no drawable. */
data class EmptyLayer(val layerName: String) : SourceArtImportNotice
/** A layer blend the model has no equivalent for; the drawable falls back to Normal. */
data class BlendUnsupported(val layerName: String, val blend: LayerBlend) : SourceArtImportNotice
/** A layer blend carried onto its nearest model equivalent, which is not the same formula. */
data class BlendApproximated(val layerName: String, val blend: LayerBlend, val mappedTo: BlendMode) : SourceArtImportNotice
/** A clipping layer with no non-clipped layer below it in its folder to clip to; imported unclipped. */
data class ClipBaseMissing(val layerName: String) : SourceArtImportNotice
/** A layer that writes only some of its channels; the model has no per-channel masking, so all four write. */
data class ChannelMaskDropped(val layerName: String) : SourceArtImportNotice
/** A folder blend the model has no equivalent for; the part composites with Normal. */
data class FolderBlendUnsupported(val groupPath: String, val blend: LayerBlend) : SourceArtImportNotice
/** A folder that is itself a clipping layer; the part imports unclipped. */
data class FolderClipDropped(val groupPath: String) : SourceArtImportNotice
/** Art whose trimmed footprint does not fit the largest page the import packs against; left unpacked. */
data class LayerLargerThanPage(val layerName: String) : SourceArtImportNotice
/** Art the packer could not place for any other reason; left unpacked, with the packer's reason. */
data class LayerNotPacked(val layerName: String, val reason: String) : SourceArtImportNotice
}
@@ -0,0 +1,87 @@
package org.umamo.interop.art
import org.umamo.format.art.LayerBounds
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceGroup
import org.umamo.format.art.SourceLayer
import org.umamo.runtime.model.ArtSource
/*
* Placing a file's art on the document canvas. Every SourceArt the model sees - the bridge's, the
* reload planner's, the matcher's - is in the DOCUMENT canvas frame, and the placement happens ONCE,
* where the file is read: the add path places a new file by its Align and Offset rows, and every
* later read of a listed file is placed by the offset its record keeps. That keeps the inventory
* rows, the birth meshes, and the reload's frame comparisons in one frame with the drawables'
* positions, so nothing downstream knows a file's own canvas ever differed from the document's.
*/
/**
* A translation from a file's own canvas to the document canvas, in pixels along the viewport's world
* axes: x to the right and z UP. A file whose top-left corner sits below the document's carries a
* negative z, and a layer's canvas top (y down) moves by -z.
*
* @property Int x How far right of the document canvas's top-left corner the file's top-left corner sits.
* @property Int z How far up from the document canvas's top-left corner the file's top-left corner sits.
*/
data class CanvasOffset(val x: Int, val z: Int) {
/** Whether this offset moves nothing. */
val isZero: Boolean get() = x == 0 && z == 0
companion object {
/** The offset of a file that shares the document's frame. */
val Zero: CanvasOffset = CanvasOffset(0, 0)
}
}
/**
* This art with every layer's bounds shifted by [offset], the file's canvas placed on the document's.
*
* The layers delegate everything but their bounds to the originals, so each layer's raster is the
* SAME instance: the add path's decode memo and the renderer's texture cache both key on that
* identity. The file's own canvas size and its folders pass through unchanged. A zero offset
* returns this art itself.
*
* @param CanvasOffset offset The translation.
* @return SourceArt The placed art.
*/
fun SourceArt.placedBy(offset: CanvasOffset): SourceArt {
if (offset.isZero) {
return this
}
return PlacedSourceArt(this, offset)
}
/**
* This art placed by [source]'s recorded offset - what every read of a listed file goes through
* before the model sees it.
*
* @param ArtSource source The file's record.
* @return SourceArt The placed art.
*/
fun SourceArt.placedFor(source: ArtSource): SourceArt = placedBy(CanvasOffset(source.offsetX, source.offsetZ))
/** A file's art shifted onto the document canvas; see [placedBy]. */
private class PlacedSourceArt(
private val original: SourceArt,
offset: CanvasOffset,
) : SourceArt {
override val layers: List<SourceLayer> = original.layers.map { layer -> PlacedSourceLayer(layer, offset) }
override val groups: List<SourceGroup> get() = original.groups
override val widthPx: Int get() = original.widthPx
override val heightPx: Int get() = original.heightPx
}
/** One layer shifted onto the document canvas: the original in every respect but where it sits. */
private class PlacedSourceLayer(
private val original: SourceLayer,
offset: CanvasOffset,
) : SourceLayer by original {
override val bounds: LayerBounds =
LayerBounds(
left = original.bounds.left + offset.x,
// Canvas y runs down and z runs up, so a file placed higher has a smaller top.
top = original.bounds.top - offset.z,
width = original.bounds.width,
height = original.bounds.height,
)
}
@@ -0,0 +1,47 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.type.CAffine
/*
* The CMO3 2x3 affine as the runtime's six-float array (m00, m01, m02, m10, m11, m12), in both
* directions. Every atlas lowering reads and writes a CAffine through these, so a transposed index
* cannot be written in one site and not another - a wrong transform in the file is exactly the
* corruption the reconcile exists to prevent.
*/
/**
* This affine's six components in the runtime's row-major order.
*
* @return FloatArray The components (m00, m01, m02, m10, m11, m12).
*/
internal fun CAffine.toAffineArray(): FloatArray = floatArrayOf(m00, m01, m02, m10, m11, m12)
/**
* Overwrites this affine's six components from the runtime's row-major order.
*
* @param FloatArray values The components (m00, m01, m02, m10, m11, m12).
*/
internal fun CAffine.setFromAffineArray(values: FloatArray) {
m00 = values[0]
m01 = values[1]
m02 = values[2]
m10 = values[3]
m11 = values[4]
m12 = values[5]
}
/**
* A fresh affine holding [values].
*
* @param FloatArray values The components (m00, m01, m02, m10, m11, m12).
* @return CAffine The new affine.
*/
internal fun affineOf(values: FloatArray): CAffine = CAffine().apply { setFromAffineArray(values) }
/**
* An independent copy of this affine. The writer must not hoist one shared instance across the
* entry, the region input, and the model image - the editor writes separate elements.
*
* @return CAffine The copy.
*/
internal fun CAffine.copyAffine(): CAffine = affineOf(toAffineArray())
@@ -0,0 +1,438 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CLayer
import org.umamo.format.cmo3.model.custom.CModelImage
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.ACLayerEntry
import org.umamo.format.cmo3.model.gen.ACLayerGroup
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.CLayerIdentifier
import org.umamo.format.cmo3.model.gen.CLayerInputData
import org.umamo.format.cmo3.model.gen.CLayerSelectorMap
import org.umamo.format.cmo3.model.gen.CLayeredImage
import org.umamo.format.cmo3.model.gen.CModelImageGroup
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureInputExtension
import org.umamo.format.cmo3.model.gen.CTextureInput_ModelImage
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.EnvValueSet
import org.umamo.format.cmo3.model.gen.FilterEnv
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.gen.GTransform2
import org.umamo.format.cmo3.model.gen.LayeredImageWrapper
import org.umamo.format.cmo3.model.gen.ModelImageEntry
import org.umamo.format.cmo3.model.identity.Id
import org.umamo.format.cmo3.model.type.CRect
import org.umamo.format.cmo3.model.type.FileRef
import org.umamo.format.cmo3.model.type.GVector2
import org.umamo.runtime.model.ArtSource
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.PuppetAtlas
import org.umamo.runtime.model.SourceLayerRef
/**
* A CMO3's layered-art web read as model state: the atlas itself, which tile each drawable samples,
* where each tile's pixels live in the graph, and the artwork files the editor decomposed to build it.
*
* @property PuppetAtlas atlas The document's pages and tiles, with each tile's placement.
* @property Map tileIdByDrawableId Raw drawable id to the tile it samples; absent when it has none.
* @property Map imageResourceByTile The graph resource holding each tile's pixels, for the
* document's pixel supplier - metadata ingest reads no bytes, so decoding stays the caller's.
* @property List sources The layered images the editor imported, as the model's
* source list: identity, name, the advisory PSD path, and the layer inventory walked from the
* editor's decomposed layer tree ([walkLayeredImage]) - the same walk that mints each tile's binding.
*/
public class Cmo3AtlasIngest(
public val atlas: PuppetAtlas,
public val tileIdByDrawableId: Map<String, AtlasTileId>,
public val imageResourceByTile: Map<AtlasTileId, CImageResource>,
public val sources: List<ArtSource> = emptyList(),
) {
public companion object {
/** What a document with no texture manager, or no model images, ingests to. */
public val EMPTY: Cmo3AtlasIngest = Cmo3AtlasIngest(PuppetAtlas.Empty, emptyMap(), emptyMap())
}
}
/**
* Reads a CMO3's layered-art web into the model's atlas.
*
* The web is three joined structures and this walks all three: the texture manager's atlas pages carry
* a `ModelImageEntry` per packed image (where the packer put it), the model-image groups carry the
* images themselves (the art, and its size), and each art mesh's texture-input extension names the
* image it samples. The join key throughout is the model image's guid, which becomes the tile id.
*
* Nothing is decoded here: an image's dimensions come off its resource record, so a model with hundreds
* of layers ingests without touching a pixel. [Cmo3AtlasIngest.imageResourceByTile] is what lets the
* caller decode later, on demand.
*
* A drawable's placement is deliberately NOT resolved here. Whether a drawable reads a packed page or
* its art directly follows from the document's display mode and whether its tile was packed at all -
* both of which are model state - so the model derives it (`PuppetModel.atlasBindingFor`) rather than
* this ingest freezing an answer that an edit would then have to keep in step.
*
* @param CModelSource modelSource The CMO3's root model source.
* @return Cmo3AtlasIngest The atlas, the per-drawable tile binding, and the pixel resources.
*/
public fun cmo3AtlasIngest(modelSource: CModelSource): Cmo3AtlasIngest {
// CMO3: CModelSource field textureManager - the root of the whole layered-art web.
val textureManager = modelSource.textureManager as? CTextureManager ?: return Cmo3AtlasIngest.EMPTY
// CMO3: CTextureManager field _textureAtlases -> CTextureAtlas fields modelImages / width / height.
// This page order is the document's, and becomes AtlasPlacement.pageIndex; it is independent of the
// renderer's own page numbering, which is derived from drawable encounter order.
val atlases = Cmo3Import.elementsOf(textureManager._textureAtlases).filterIsInstance<CTextureAtlas>()
val pages = atlases.map { atlas -> AtlasPage(atlas.width, atlas.height) }
// CMO3: CTextureAtlas field cachedAtlasImage - the page's own pixels. A drawable whose texture points AT
// one stores page-space coordinates. Identity membership is the test, CImageResource being a plain class.
val atlasPageResources = atlases.mapNotNull { atlas -> atlas.cachedAtlasImage as? CImageResource }.toHashSet()
val placementByModelImageGuid = HashMap<String, AtlasPlacement>()
for ((pageIndex, atlas) in atlases.withIndex()) {
for (entry in Cmo3Import.elementsOf(atlas.modelImages).filterIsInstance<ModelImageEntry>()) {
// CMO3: ModelImageEntry field modelImageGuid - the join back to the pooled model image.
val modelImageGuid = Cmo3Import.uuidOf(entry.modelImageGuid) ?: continue
// CMO3: ModelImageEntry field materialLocalToAtlasTransform - the packer's work, as a
// GTransform2 (position, scale, eulerAngle in DEGREES). Absent scale defaults to 1: a
// GTransform2 with no scale child is the unscaled case, not a collapse to zero.
val transform = entry.materialLocalToAtlasTransform as? GTransform2 ?: continue
val position = transform.position as? GVector2
val scale = transform.scale as? GVector2
placementByModelImageGuid[modelImageGuid] =
AtlasPlacement(
pageIndex = pageIndex,
positionX = position?.x ?: 0f,
positionY = position?.y ?: 0f,
scaleX = scale?.x ?: 1f,
scaleY = scale?.y ?: 1f,
rotationDegrees = transform.eulerAngle,
)
}
}
// CMO3: CTextureManager field _rawImages -> LayeredImageWrapper field image -> CLayeredImage fields
// guid / name / psdFile - the artwork files the editor decomposed at import, each keyed by the guid
// the selector maps below reference. psdFile is the external-reference <file> shape: its text is
// the absolute path on the importing machine (docs/format/CMO3.md section 4), advisory here. The
// field's legacy name notwithstanding, a flat raster import lands in the same structure, so the
// format is read off the name's extension rather than assumed.
val layeredImages =
Cmo3Import.elementsOf(textureManager._rawImages).mapNotNull { wrapper -> (wrapper as? LayeredImageWrapper)?.image as? CLayeredImage }
val sources = ArrayList<ArtSource>(layeredImages.size)
val refByLayerGuidBySource = HashMap<String, Map<String, SourceLayerRef>>()
for (image in layeredImages) {
val guid = Cmo3Import.uuidOf(image.guid) ?: continue
if (guid in refByLayerGuidBySource) {
continue
}
val name = image.name?.takeIf { candidate -> candidate.isNotEmpty() } ?: guid
val inventory = layeredImageInventory(image, ArtSourceId(guid))
refByLayerGuidBySource[guid] = inventory.refByLayerGuid
sources.add(
ArtSource(
id = ArtSourceId(guid),
name = name,
path = (image.psdFile as? FileRef)?.textPath?.takeIf { path -> path.isNotEmpty() },
format = name.substringAfterLast('.', missingDelimiterValue = "psd").lowercase(),
layers = inventory.rows,
// CMO3: CLayeredImage field psdFileLastModified - the source's modification time when the
// editor imported it (epoch milliseconds), zero when it never recorded one.
lastModified = image.psdFileLastModified.takeIf { millis -> millis > 0L },
),
)
}
// CMO3: CTextureManager field _modelImageGroups -> CModelImageGroup field _modelImages.
val modelImages =
Cmo3Import.elementsOf(textureManager._modelImageGroups)
.filterIsInstance<CModelImageGroup>()
.flatMap { group -> Cmo3Import.elementsOf(group._modelImages).filterIsInstance<CModelImage>() }
val tiles = ArrayList<AtlasTile>(modelImages.size)
val imageResourceByTile = HashMap<AtlasTileId, CImageResource>()
val knownTileIds = HashSet<String>()
for (modelImage in modelImages) {
// CMO3: CModelImage field guid - the key every binding and placement references.
val key = Cmo3Import.uuidOf(modelImage.guid) ?: continue
// CMO3: CModelImage field _filteredImage - the baked composite raster, carrying its own
// dimensions, so the inventory needs no decode. An image with no resource has no art to show
// and no size to place, so it is not a tile at all.
val resource = modelImage._filteredImage as? CImageResource ?: continue
val tileId = AtlasTileId(key)
knownTileIds.add(key)
imageResourceByTile[tileId] = resource
tiles.add(
AtlasTile(
id = tileId,
// CMO3: CModelImage field name - the editor writes the drawable's own name here.
name = displayNameOf(modelImage.name) ?: key,
width = resource.width,
height = resource.height,
placement = placementByModelImageGuid[key],
source = soleSourceLayerRefOf(modelImage, refByLayerGuidBySource),
),
)
}
// CMO3: CDrawableSourceSet field _sources -> CArtMeshSource field _extensions.
val artMeshes =
Cmo3Import.elementsOf((modelSource.drawableSourceSet as? CDrawableSourceSet)?._sources)
.filterIsInstance<CArtMeshSource>()
val tileIdByDrawableId = HashMap<String, AtlasTileId>()
// Whether the model's coordinates address pages: a drawable samples a page, or - the same thing once
// the import has read it (Cmo3TextureFrames) - its tile is placed, since a placed tile's drawable takes
// its coordinates on the page whatever its texture names. A model saved in source-layer display points
// every drawable at a model image, yet its placed tiles still sit on the page the file carries.
var anyDrawableAddressesAPage = false
for (mesh in artMeshes) {
val drawableId = Cmo3Import.idStrOf(mesh.id) ?: continue
// CMO3: CTextureInputExtension field _textureInputs -> CTextureInput_ModelImage field
// _modelImageGuid. A drawable carrying only an atlas-region input (no model image) has no
// source art and is simply absent from the map.
val extension =
Cmo3Import.elementsOf(mesh._extensions).filterIsInstance<CTextureInputExtension>().firstOrNull() ?: continue
val modelImageInput =
Cmo3Import.elementsOf(extension._textureInputs).filterIsInstance<CTextureInput_ModelImage>().firstOrNull()
?: continue
val key = Cmo3Import.uuidOf(modelImageInput._modelImageGuid) ?: continue
if (key !in knownTileIds) {
continue
}
// CMO3: CArtMeshSource field texture -> GTexture2D field srcImageResource.
val sampledResource = (mesh.texture as? GTexture2D)?.srcImageResource as? CImageResource
if ((sampledResource != null && sampledResource in atlasPageResources) || key in placementByModelImageGuid) {
anyDrawableAddressesAPage = true
}
tileIdByDrawableId[drawableId] = AtlasTileId(key)
}
return Cmo3AtlasIngest(
PuppetAtlas(pages, tiles, storedUvsAddressPages = anyDrawableAddressesAPage),
tileIdByDrawableId,
imageResourceByTile,
sources,
)
}
/**
* One decomposed artwork file's layer table: the inventory rows in the editor's stored order, and the
* binding each layer's guid resolves to, so a tile's binding and the inventory row it names are minted
* by the same pass and cannot disagree.
*
* @property List rows The inventory rows.
* @property Map refByLayerGuid Each image layer's binding, keyed by the layer entry's guid.
*/
private class LayeredImageInventory(val rows: List<ArtSourceLayer>, val refByLayerGuid: Map<String, SourceLayerRef>)
/**
* One image layer of a decomposed artwork file as the walk found it: the entry, the key the walk
* minted for it, whether that key is stable, its folder path, and its place in the stored order.
*
* @property CLayer layer The layer entry.
* @property String key The binding key ("lyid:<id>", or "name:<name>" with an order suffix on a duplicate).
* @property Boolean stable Whether the key survives a rename (an unsuffixed Photoshop layer id).
* @property String groupPath The slash-joined enclosing-folder path ("" at the root).
* @property Int order The layer's index in the stored order, top-most first.
*/
internal class WalkedCmo3Layer(
val layer: CLayer,
val key: String,
val stable: Boolean,
val groupPath: String,
val order: Int,
)
/**
* Walks one decomposed artwork file's layer tree: every image layer under its root group, in the
* editor's stored order, with its key.
*
* Keys are minted the way the PSD reader mints them, so a CMO3-origin document and a fresh read of
* the same file agree on a layer's identity: "lyid:<id>" when the editor recorded Photoshop's layer
* id (a stable key, the reader's own), else "name:<name>", which is unique within the image only by
* construction - a repeated name takes an order suffix ("name:1#2") on every duplicate after the
* first, and any suffixed key is unstable by definition, because the suffix depends on the tree order.
*
* @param CLayeredImage image The layered image to walk.
* @return List<WalkedCmo3Layer> The image layers, empty when the image has no layer tree.
*/
internal fun walkLayeredImage(image: CLayeredImage): List<WalkedCmo3Layer> {
// CMO3: CLayeredImage field _rootLayer -> CLayerGroup, whose ACLayerGroup field _children holds the
// image layers (CLayer) and nested folders (CLayerGroup) of the decomposed file.
val root = image._rootLayer as? ACLayerGroup ?: return emptyList()
val walked = ArrayList<WalkedCmo3Layer>()
val duplicateCountByKey = HashMap<String, Int>()
fun walk(group: ACLayerGroup, path: String) {
for (entry in Cmo3Import.elementsOf(group._children)) {
when (entry) {
is ACLayerGroup -> {
// CMO3: ACLayerEntry field name - the folder's own name, one segment of the path.
val name = entry.name.orEmpty()
walk(entry, if (path.isEmpty()) name else "$path/$name")
}
is CLayer -> {
// CMO3: ACLayerEntry field name.
val name = entry.name.orEmpty()
val photoshopLayerId = photoshopLayerIdOf(entry.layerIdentifier)
val baseKey = if (photoshopLayerId != null) "lyid:$photoshopLayerId" else "name:$name"
val duplicateOrdinal = (duplicateCountByKey[baseKey] ?: 0) + 1
duplicateCountByKey[baseKey] = duplicateOrdinal
val key = if (duplicateOrdinal == 1) baseKey else "$baseKey#$duplicateOrdinal"
walked.add(WalkedCmo3Layer(entry, key, stable = photoshopLayerId != null && duplicateOrdinal == 1, groupPath = path, order = walked.size))
}
}
}
}
walk(root, "")
return walked
}
/**
* The layer inventory of one decomposed artwork file, over [walkLayeredImage].
*
* @param CLayeredImage image The layered image to walk.
* @param ArtSourceId sourceId The source id the bindings carry.
* @return LayeredImageInventory The rows and the per-layer bindings, both empty when the image has no
* layer tree.
*/
private fun layeredImageInventory(image: CLayeredImage, sourceId: ArtSourceId): LayeredImageInventory {
val rows = ArrayList<ArtSourceLayer>()
val refByLayerGuid = HashMap<String, SourceLayerRef>()
for (walked in walkLayeredImage(image)) {
val entry = walked.layer
// CMO3: ACLayerEntry fields isVisible / guid; CLayer field boundsOnImageDoc, a CRect (x / y /
// width / height) placing the layer on the source document.
val bounds = entry.boundsOnImageDoc as? CRect
Cmo3Import.uuidOf(entry.guid)?.let { layerGuid ->
refByLayerGuid[layerGuid] = SourceLayerRef(sourceId, layerKey = walked.key, stableKey = walked.stable)
}
rows.add(
ArtSourceLayer(
key = walked.key,
name = entry.name.orEmpty(),
groupPath = walked.groupPath,
left = bounds?.x ?: 0,
top = bounds?.y ?: 0,
width = bounds?.width ?: 0,
height = bounds?.height ?: 0,
visible = entry.isVisible,
),
)
}
return LayeredImageInventory(rows, refByLayerGuid)
}
/**
* The Photoshop layer id the editor recorded for a decomposed layer, or null when it recorded none.
*
* @param Any? identifier The layer's CLayerIdentifier slot.
* @return Int? The id, as the PSD reader's lyid integer.
*/
private fun photoshopLayerIdOf(identifier: Any?): Int? {
// CMO3: CLayerIdentifier field layerId - Photoshop's lyid (the additional-layer-info block the PSD
// reader keys on, docs/format/PSD.md) written as up to four dash-separated hex bytes, big-endian
// ("00-00-06-28" is 1576); null when the import was not a PSD. layerIdValue_testImpl mirrors it in
// decimal (-1 when absent) and is not read: the byte string is the field the editor names as the id.
val text = (identifier as? CLayerIdentifier)?.layerId?.takeIf { candidate -> candidate.isNotEmpty() } ?: return null
val byteTexts = text.split('-')
if (byteTexts.size > 4) {
return null
}
var value = 0L
for (byteText in byteTexts) {
val byteValue = byteText.toIntOrNull(16) ?: return null
if (byteValue !in 0..255) {
return null
}
value = (value shl 8) or byteValue.toLong()
}
return value.toInt()
}
/**
* The one layer input a model image composites, with the layered image it comes from.
*
* @property String imageGuid The layered image's guid (uuid text).
* @property CLayerInputData input The layer input, whose `layer` is the composited entry.
*/
internal class SoleLayerInput(val imageGuid: String, val input: CLayerInputData)
/**
* The one layer input of a model image's selector map, when exactly one artwork layer composites
* into it - which is every model image across the corpus - else null. Shared by the ingest's binding
* walk and the export's retained-layer rewrite, so both agree on which layer a tile IS.
*
* @param CModelImage modelImage The model image to resolve.
* @return SoleLayerInput? The input, or null.
*/
internal fun soleLayerInputOf(modelImage: CModelImage): SoleLayerInput? {
// CMO3: CModelImage field inputFilterEnv -> ModelImageFilterEnv (a FilterEnv) field envValues, a map
// from filter-value ids to EnvValueSet; the set under mi_input_layerInputData holds the
// CLayerSelectorMap whose _imageToLayerInput maps each layered image's guid to the list of layer
// inputs composited from it. Found by the value's type rather than the id: the id is an Id node
// whose equality the deserializer does not promise, and only one set holds a selector map.
val filterEnv = modelImage.inputFilterEnv as? FilterEnv ?: return null
val selectorMap =
Cmo3Import.elementsOf(filterEnv.envValues).filterIsInstance<EnvValueSet>()
.firstNotNullOfOrNull { valueSet -> valueSet.value as? CLayerSelectorMap } ?: return null
val imageToInputs = selectorMap._imageToLayerInput as? Map<*, *> ?: return null
var soleImageGuid: String? = null
var soleInput: CLayerInputData? = null
var inputCount = 0
for ((imageGuid, inputs) in imageToInputs) {
for (input in Cmo3Import.elementsOf(inputs).filterIsInstance<CLayerInputData>()) {
inputCount++
soleImageGuid = Cmo3Import.uuidOf(imageGuid)
soleInput = input
}
}
if (inputCount != 1) {
return null
}
val imageGuid = soleImageGuid ?: return null
val input = soleInput ?: return null
return SoleLayerInput(imageGuid, input)
}
/**
* The source-layer binding of a model image, when exactly one artwork layer composites into it -
* which is every model image across the corpus - else null.
*
* The binding is the one the inventory walk minted for that layer (looked up by the layer entry's
* guid), so it names an inventory row by construction. A layer the walk never listed - one outside
* its image's root tree - falls back to an unstable name key rather than losing the binding.
*
* @param CModelImage modelImage The model image to resolve.
* @param Map refByLayerGuidBySource Each listed layered image's per-layer bindings, keyed by
* the image guid; a map keyed by an unlisted image binds to nothing rather than to a source the
* document does not have.
* @return SourceLayerRef? The binding, or null.
*/
private fun soleSourceLayerRefOf(modelImage: CModelImage, refByLayerGuidBySource: Map<String, Map<String, SourceLayerRef>>): SourceLayerRef? {
val sole = soleLayerInputOf(modelImage) ?: return null
val refByLayerGuid = refByLayerGuidBySource[sole.imageGuid] ?: return null
// CMO3: CLayerInputData field layer -> ACLayerEntry fields guid / name.
val layer = sole.input.layer as? ACLayerEntry ?: return null
Cmo3Import.uuidOf(layer.guid)?.let { layerGuid -> refByLayerGuid[layerGuid] }?.let { ref -> return ref }
val layerName = layer.name?.takeIf { name -> name.isNotEmpty() } ?: return null
return SourceLayerRef(ArtSourceId(sole.imageGuid), layerKey = "name:$layerName", stableKey = false)
}
/**
* Resolves a CMO3 name slot, which the serializer holds as `Any?` and fills with either a plain string
* or an id-bearing node.
*
* @param Any? name The raw name field.
* @return String? The display name, or null when the slot holds neither shape.
*/
private fun displayNameOf(name: Any?): String? =
when (name) {
is String -> name.takeIf { candidate -> candidate.isNotEmpty() }
is Id -> name.idstr.takeIf { candidate -> candidate.isNotEmpty() }
else -> null
}
@@ -0,0 +1,104 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.interop.AtlasPageSet
/**
* Extracts the image(s) a CMO3 model's art meshes are shown from, the images their imported coordinates
* address: a drawable over a placed tile is shown from that tile's atlas page (`CTextureAtlas.cachedAtlasImage`)
* whatever its texture names - a model saved in source-layer display still carries the page - and any other
* drawable from the image its texture names, its model image's raster standing in for a reduced cache copy
* ([Cmo3TextureFrames.renderedImageOf]). Each distinct image's embedded PNG is collected once and keyed by
* the drawable id (matching `DrawableId` from [Cmo3Import]).
*
* The pixel lookup is injected rather than taken from a `Cmo3Model`, which is what keeps this in
* commonMain: the CMO3 graph node types are all commonMain, and only the JDOM-built container wrapper
* that owns the CAFF archive is JVM-bound. The caller passes `Cmo3Model::extractLayerPng` (see the
* document loader); a test passes a map lookup.
*
* A resource carrying no bytes at all is dropped here, leaving its drawables unmapped; one carrying
* bytes that will not decode is the decoder's call, and for a CMO3 that means dropping the page rather
* than refusing the document - its pixels are embedded in the model file, so one corrupt resource
* inside an otherwise editable rig must not cost the rigger everything else.
*
* @param CModelSource modelSource The CMO3's root model source.
* @param Function readPng Yields an image resource's embedded PNG bytes, or null when it has none.
* @return AtlasPageSet The encoded pages + per-drawable index.
*/
public fun cmo3AtlasPages(modelSource: CModelSource, readPng: (CImageResource) -> ByteArray?): AtlasPageSet =
cmo3AtlasPages(modelSource, cmo3AtlasIngest(modelSource), readPng)
/**
* [cmo3AtlasPages] over an atlas ingest the caller already holds, so the document loader walks the web once.
*
* @param CModelSource modelSource The CMO3's root model source.
* @param Cmo3AtlasIngest atlasIngest The model's atlas ingest, for each drawable's tile and placement.
* @param Function readPng Yields an image resource's embedded PNG bytes, or null when it has none.
* @return AtlasPageSet The encoded pages + per-drawable index.
*/
public fun cmo3AtlasPages(
modelSource: CModelSource,
atlasIngest: Cmo3AtlasIngest,
readPng: (CImageResource) -> ByteArray?,
): AtlasPageSet {
val sources = (modelSource.drawableSourceSet as? CDrawableSourceSet)?._sources
val artMeshes = Cmo3Import.elementsOf(sources).filterIsInstance<CArtMeshSource>()
val textureFrames = Cmo3TextureFrames(modelSource)
// CMO3: CModelSource field textureManager -> CTextureManager field _textureAtlases -> CTextureAtlas field
// cachedAtlasImage, in the order a placement's pageIndex counts.
val pageImages =
Cmo3Import.elementsOf((modelSource.textureManager as? CTextureManager)?._textureAtlases)
.filterIsInstance<CTextureAtlas>()
.map { atlas -> atlas.cachedAtlasImage as? CImageResource }
// Resolved once per DISTINCT resource, not per drawable: art meshes overwhelmingly share one atlas
// page, so a per-drawable lookup would repeat the archive fetch hundreds of times on a real model.
// A null value is a remembered failure (no bytes), which is why this is not a getOrPut - getOrPut
// treats a stored null as absent and would recompute it every time.
val resolvedPageIndexByResource = HashMap<CImageResource, Int?>()
val pageBytes = ArrayList<ByteArray>()
val atlasIndexByDrawableId = HashMap<String, Int>()
var premultiplied = false
for (mesh in artMeshes) {
val drawableId = Cmo3Import.idStrOf(mesh.id) ?: continue
val texture = mesh.texture as? GTexture2D ?: continue
// CMO3: GTexture2D.isPremultiplied is an editor texture-upload-convention flag (serialized true on
// nearly every model), NOT a claim the embedded PNG is premultiplied - PngCodec decodes straight
// alpha and the shader premultiplies. Aggregated here but deliberately unconsumed downstream; do
// not drive rendering off it (that would over-darken the corpus). The version-dependent
// premultiplied-vs-straight COMPOSITING axis rides BlendMode.isLegacy, not this flag. See
// PuppetTextures.premultipliedAlpha and docs/format/CMO3.md, "Premultiplied vs straight alpha".
premultiplied = premultiplied || texture.isPremultiplied
val placement = atlasIngest.tileIdByDrawableId[drawableId]?.let { tileId -> atlasIngest.atlas.tileById[tileId]?.placement }
val resource =
if (placement != null) {
// Its coordinates are on the page; without the page's image it has nothing to show from.
pageImages.getOrNull(placement.pageIndex) ?: continue
} else {
textureFrames.renderedImageOf(mesh) ?: continue
}
val pageIndex =
if (resolvedPageIndexByResource.containsKey(resource)) {
resolvedPageIndexByResource[resource]
} else {
val resolved =
readPng(resource)?.let { png ->
pageBytes.add(png)
pageBytes.size - 1
}
resolvedPageIndexByResource[resource] = resolved
resolved
}
if (pageIndex != null) {
atlasIndexByDrawableId[drawableId] = pageIndex
}
}
return AtlasPageSet(pageBytes, atlasIndexByDrawableId, premultiplied)
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,120 @@
package org.umamo.interop.cmo3
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.SourceLayer
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CLayeredImage
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.LayeredImageWrapper
import org.umamo.format.cmo3.model.type.CRect
import org.umamo.format.png.PngCodec
import org.umamo.runtime.model.ArtSourceId
/*
* A CMO3's decomposed artwork as source art: the official editor stores every layer of an imported
* file as its own PNG at its canvas bounds (the CLayeredImage tree), so a CMO3-origin document can
* hand the reload planner a layer's pixels without the original file - what a relink reads when the
* file the document recorded is not on this machine. It is the art as the editor imported it, not
* as the artist last saved it, so a reload (which asks "what changed") reads the file, never this.
*/
/**
* One decomposed layer as a source layer. The raster decodes on first use - a relink needs one
* layer's pixels, not the whole file's.
*
* @property WalkedCmo3Layer walked The layer as the walk found it (its key, folder, and order).
* @property Function extractPng The CMO3's PNG lookup for a resource.
*/
private class Cmo3SourceLayer(
private val walked: WalkedCmo3Layer,
private val extractPng: (CImageResource) -> ByteArray?,
) : SourceLayer {
// CMO3: CLayer field imageResource - the layer's own PNG, at the size of boundsOnImageDoc.
private val resource: CImageResource? = walked.layer.imageResource as? CImageResource
override val id: LayerId = LayerId(walked.key)
override val name: String = walked.layer.name.orEmpty()
override val groupPath: String = walked.groupPath
override val kind: SourceLayerKind = if (resource?.imageFileBuf != null) SourceLayerKind.Raster else SourceLayerKind.Unknown
override val visible: Boolean = walked.layer.isVisible
override val idIsStable: Boolean = walked.stable
override val order: Int = walked.order
override val bounds: LayerBounds =
(walked.layer.boundsOnImageDoc as? CRect).let { rect ->
// CMO3: CLayer field boundsOnImageDoc (x / y / width / height on the source document).
LayerBounds(rect?.x ?: 0, rect?.y ?: 0, rect?.width ?: (resource?.width ?: 0), rect?.height ?: (resource?.height ?: 0))
}
// CMO3: ACLayerEntry fields opacity255 / isClipping / blend.
override val opacity: Float = walked.layer.opacity255 / 255f
override val clipped: Boolean = walked.layer.isClipping
override val blend: LayerBlend = layerBlendOf(walked.layer.blend)
override val raster: LayerRaster by lazy {
val decoded = resource?.let(extractPng)?.let { png -> runCatching { PngCodec.read(png) }.getOrNull() }
if (decoded != null) {
LayerRaster(decoded.width, decoded.height, decoded.rgba)
} else {
// A layer whose PNG is missing or undecodable reads as fully transparent at its bounds, which
// the planner treats as a layer with no art to give.
LayerRaster(bounds.width, bounds.height, ByteArray(bounds.width * bounds.height * 4))
}
}
}
/**
* The decomposed file as a source document.
*
* @property List layers The image layers, in the stored order.
* @property Int widthPx The source document's width.
* @property Int heightPx The source document's height.
*/
private class Cmo3LayeredArt(
override val layers: List<SourceLayer>,
override val widthPx: Int,
override val heightPx: Int,
) : SourceArt
/**
* The blend a decomposed layer composites with, as the readers name it.
*
* @param Any? blend The layer's ACBlend node.
* @return LayerBlend The blend; Normal for a node the CMO3 marks unsupported or one this does not name.
*/
private fun layerBlendOf(blend: Any?): LayerBlend =
// CMO3: ACLayerEntry field blend - one of the CBlend_* classes; the editor keeps only the modes it
// composites itself and marks the rest CBlend_NotSupported.
when (blend?.let { node -> node::class.simpleName }) {
"CBlend_Multiply" -> LayerBlend.Multiply
"CBlend_LinearDodge" -> LayerBlend.Add
"CBlend_Color" -> LayerBlend.Color
else -> LayerBlend.Normal
}
/**
* The artwork file [sourceId] names, as the CMO3 decomposed it at import: one source layer per image
* layer of the matching layered image, keyed exactly as the atlas ingest keys the document's
* bindings, with pixels read from the layer's own PNG. Null when the document lists no such image.
*
* @param CModelSource modelSource The parsed CMO3 root.
* @param ArtSourceId sourceId The source to read - the layered image's guid.
* @param Function extractPng The CMO3's PNG lookup for a resource (the codec's extractLayerPng).
* @return SourceArt? The decomposed file, or null.
*/
fun cmo3SourceArtOf(modelSource: CModelSource, sourceId: ArtSourceId, extractPng: (CImageResource) -> ByteArray?): SourceArt? {
// CMO3: CModelSource field textureManager -> CTextureManager field _rawImages -> LayeredImageWrapper
// field image -> CLayeredImage fields guid / width / height.
val textureManager = modelSource.textureManager as? CTextureManager ?: return null
val image =
Cmo3Import.elementsOf(textureManager._rawImages)
.mapNotNull { wrapper -> (wrapper as? LayeredImageWrapper)?.image as? CLayeredImage }
.firstOrNull { candidate -> Cmo3Import.uuidOf(candidate.guid) == sourceId.raw }
?: return null
val layers = walkLayeredImage(image).map { walked -> Cmo3SourceLayer(walked, extractPng) }
return Cmo3LayeredArt(layers, image.width, image.height)
}
@@ -0,0 +1,349 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CModelImage
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CCachedImage
import org.umamo.format.cmo3.model.gen.CCachedImageManager
import org.umamo.format.cmo3.model.gen.CModelImageGroup
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.type.CAffine
import org.umamo.runtime.model.applyUvAffine
import org.umamo.runtime.model.invertUvAffine
/**
* The frame a drawable's stored texture coordinates are in, read off the image its texture names.
*/
internal enum class Cmo3StoredFrame {
/** An atlas page's own [0,1]: the drawable samples the page. */
Page,
/** Its model image's raster's own [0,1]: a packed drawable sampling the raster. */
Raster,
/** The editor's cache frame, the raster padded to a multiple of 64: unpacked, or over a reduced copy. */
Cache,
}
/**
* Which image each CMO3 drawable is shown from, and how its stored texture coordinates reach that image -
* the one place the CMO3 boundary decides a drawable's texture frame, on import and on export alike.
*
* The editor can point a drawable at three kinds of image: an atlas page, its model image's own raster
* (`_filteredImage`), or a reduced cache copy of that raster (a `CCachedImage` other than the raster itself,
* the raster padded to a multiple of 64 and scaled down). Stored coordinates live in one of two frames:
* the sampled image's own, or the cache frame - the padded raster, which is also the reduced copy's frame.
* A packed drawable over a page or the raster stores its sampled image's frame; an unpacked drawable, and
* any drawable over a reduced copy, stores the cache frame. `GTexture2D.transformImageResource01toLogical01`
* carries the raster-to-cache scale (raster size over its 64-aligned padding, per axis), so the cache frame
* reaches the raster through that affine's inverse.
*
* Umamo keeps no cache frame and no reduced copy, and reads every placed tile off its page. A drawable
* whose tile the editor packed (it has an atlas entry, so the tile has a placement) takes model coordinates
* in that PAGE's frame whatever its texture names: a model saved in source-layer display points its
* drawables at model images or their copies, yet its atlas page is in the file and is what the editor shows
* with the source artwork off. Any other drawable takes its model image's raster frame, and a drawable
* over a reduced copy is shown from the raster - the copy is the editor's display cache and has no meaning
* outside it. The export runs the same chain backward, so the file keeps the frame the editor reads.
*
* The tile's placement arrives as its stored-to-art affine ([org.umamo.runtime.model.storedToArtAffineForTile]):
* the import's atlas on the way in, the EDITED model's on the way out, so a repack's new placement converts
* correctly while the art frame - which a repack never moves - is what reaches the file.
*
* The set of reduced copies is taken once, from the graph as it was read. An export that rewrites a model
* image rebuilds its cache and would otherwise make its copy vanish in the middle of the pass; each query
* reads the drawable's CURRENT texture against that set, so only a deliberate retarget of the texture moves
* a drawable out of the cache frame. The atlas pages, by contrast, are read live: a pack-in points its
* drawable at a page the same export may have just minted, and that drawable stores the page's frame.
*
* @param CModelSource modelSource The CMO3's root model source, as read.
*/
internal class Cmo3TextureFrames(private val modelSource: CModelSource) {
/** Each reduced copy in the graph as read, to the model image it is a copy of; compared by identity. */
private val ownerByReducedCopy: Map<CImageResource, CModelImage> = reducedCopiesOf(modelSource)
/**
* Whether a drawable's texture is a reduced cache copy of its model image.
*
* @param CArtMeshSource source The drawable's graph source.
* @return Boolean True when it samples a copy rather than a page or a raster.
*/
fun samplesReducedCopy(source: CArtMeshSource): Boolean = sampledResourceOf(source)?.let { resource -> resource in ownerByReducedCopy } == true
/**
* The frame a drawable's stored coordinates are in.
*
* @param CArtMeshSource source The drawable's graph source.
* @return Cmo3StoredFrame Page over an atlas page; Cache when unpacked or over a reduced copy; else Raster.
*/
fun storedFrameOf(source: CArtMeshSource): Cmo3StoredFrame {
val sampled = sampledResourceOf(source)
return when {
sampled != null && isAtlasPage(sampled) -> Cmo3StoredFrame.Page
!Cmo3Import.hasAtlasRegion(source) || samplesReducedCopy(source) -> Cmo3StoredFrame.Cache
else -> Cmo3StoredFrame.Raster
}
}
/**
* The image Umamo shows a drawable from: its model image's raster in place of a reduced copy, else the
* image its texture names.
*
* @param CArtMeshSource source The drawable's graph source.
* @return CImageResource? The image, or null when the drawable has no texture image.
*/
fun renderedImageOf(source: CArtMeshSource): CImageResource? {
val sampled = sampledResourceOf(source) ?: return null
// CMO3: CModelImage field _filteredImage - the raster the copy was reduced from.
return ownerByReducedCopy[sampled]?.let { owner -> owner._filteredImage as? CImageResource } ?: sampled
}
/**
* The model coordinates of a drawable's stored ones. Page coordinates are taken verbatim. Otherwise
* the stored coordinates reach the raster frame - verbatim from Raster, through the inverse of the
* raster-to-cache affine from Cache - and a placed tile's then go on through its placement onto its page.
*
* @param CArtMeshSource source The drawable's graph source.
* @param FloatArray storedUvs The stored coordinates, interleaved (u, v).
* @param FloatArray? storedToArt The drawable's tile's model-to-art affine, or null (or the identity)
* when the tile is not placed.
* @return FloatArray The model coordinates; the same array when no remap applies.
*/
fun modelUvsOf(source: CArtMeshSource, storedUvs: FloatArray, storedToArt: FloatArray? = null): FloatArray {
val frame = storedFrameOf(source)
if (frame == Cmo3StoredFrame.Page) {
return storedUvs
}
val artUvs = if (frame == Cmo3StoredFrame.Cache) rasterUvsOfCache(source, storedUvs) else storedUvs
val artToModel = storedToArt?.takeUnless(::isIdentityAffine)?.let(::invertUvAffine) ?: return artUvs
return applyUvAffine(artUvs, artToModel)
}
/**
* Cache-frame coordinates brought into the raster frame through the inverse of the raster-to-cache affine.
*
* @param CArtMeshSource source The drawable's graph source.
* @param FloatArray cacheUvs The coordinates in the cache frame.
* @return FloatArray The raster-frame coordinates; the same array when the affine is absent or degenerate.
*/
private fun rasterUvsOfCache(source: CArtMeshSource, cacheUvs: FloatArray): FloatArray {
val affine = cacheAffineOf(source) ?: return cacheUvs
val determinant = affine.m00 * affine.m11 - affine.m01 * affine.m10
// A degenerate affine would invert to NaN or infinity; the coordinates stay as stored.
if (determinant == 0f) {
return cacheUvs
}
val rasterUvs = FloatArray(cacheUvs.size)
var componentIndex = 0
while (componentIndex + 1 < cacheUvs.size) {
rasterUvs[componentIndex] = inverseU(affine, determinant, cacheUvs[componentIndex], cacheUvs[componentIndex + 1])
rasterUvs[componentIndex + 1] = inverseV(affine, determinant, cacheUvs[componentIndex], cacheUvs[componentIndex + 1])
componentIndex += 2
}
return rasterUvs
}
/**
* The stored coordinates of a drawable's model ones - [modelUvsOf] run backward. Page coordinates are
* stored verbatim. Otherwise a placed tile's model coordinates come off its page through the placement
* into the raster frame, which Raster stores verbatim and Cache through the raster-to-cache affine.
*
* A coordinate pair the edit left alone keeps its stored value, so the float round trip cannot drift a
* file the rigger did not touch there. That needs both the stored and the baseline model coordinates,
* and is only sound when the tile's placement is the one those were read under - the caller passes them
* only then. Without them every pair is converted, and a converted pair re-imports within a few ULPs of
* the model's value: through a scale, not every float has a float that maps onto it exactly.
*
* @param CArtMeshSource source The drawable's graph source.
* @param FloatArray modelUvs The model coordinates to store, interleaved (u, v).
* @param FloatArray? storedToArt The drawable's tile's model-to-art affine in the model being stored,
* or null (or the identity) when the tile is not placed.
* @param FloatArray? storedUvs The coordinates the graph stores now, or null.
* @param FloatArray? baselineUvs The model coordinates [storedUvs] import to, or null.
* @return FloatArray The coordinates to store, a fresh array.
*/
fun storedUvsOf(
source: CArtMeshSource,
modelUvs: FloatArray,
storedToArt: FloatArray? = null,
storedUvs: FloatArray? = null,
baselineUvs: FloatArray? = null,
): FloatArray {
val frame = storedFrameOf(source)
if (frame == Cmo3StoredFrame.Page) {
return modelUvs.copyOf()
}
val artUvs = storedToArt?.takeUnless(::isIdentityAffine)?.let { affine -> applyUvAffine(modelUvs, affine) } ?: modelUvs
val cacheAffine = if (frame == Cmo3StoredFrame.Cache) cacheAffineOf(source) else null
val keptStored = storedUvs?.takeIf { stored -> stored.size == modelUvs.size && baselineUvs?.size == modelUvs.size }
val result = FloatArray(modelUvs.size)
var componentIndex = 0
while (componentIndex + 1 < modelUvs.size) {
val unchangedPair =
baselineUvs != null &&
modelUvs[componentIndex].toRawBits() == baselineUvs[componentIndex].toRawBits() &&
modelUvs[componentIndex + 1].toRawBits() == baselineUvs[componentIndex + 1].toRawBits()
if (keptStored != null && unchangedPair) {
result[componentIndex] = keptStored[componentIndex]
result[componentIndex + 1] = keptStored[componentIndex + 1]
} else if (cacheAffine != null) {
val u = artUvs[componentIndex]
val v = artUvs[componentIndex + 1]
result[componentIndex] = cacheAffine.m00 * u + cacheAffine.m01 * v + cacheAffine.m02
result[componentIndex + 1] = cacheAffine.m10 * u + cacheAffine.m11 * v + cacheAffine.m12
} else {
result[componentIndex] = artUvs[componentIndex]
result[componentIndex + 1] = artUvs[componentIndex + 1]
}
componentIndex += 2
}
return result
}
/**
* Whether a resource is one of the graph's atlas pages right now.
*
* The page's own instance, or a twin naming the same archive entry: a graph built rather than read can
* hand a texture a second resource record for the page's pixels, and it samples the page all the same.
*
* @param CImageResource resource The resource.
* @return Boolean True when some texture atlas holds it, or its archive entry, as its page image.
*/
fun isAtlasPage(resource: CImageResource): Boolean {
// CMO3: CImageResource field imageFileBuf - the archive entry holding the pixels.
val archivePath = resource.imageFileBuf?.archivePath
// CMO3: CModelSource field textureManager -> CTextureManager field _textureAtlases -> CTextureAtlas
// field cachedAtlasImage.
return Cmo3Import.elementsOf((modelSource.textureManager as? CTextureManager)?._textureAtlases).any { atlas ->
val page = (atlas as? CTextureAtlas)?.cachedAtlasImage as? CImageResource
page != null && (page === resource || (archivePath != null && page.imageFileBuf?.archivePath == archivePath))
}
}
/**
* Whether a drawable is shown from a model image: it samples the image's raster, or a reduced copy of it
* as the graph was read.
*
* @param CArtMeshSource source The drawable's graph source.
* @param CModelImage modelImage The model image.
* @return Boolean True when the drawable's texture is the image's raster or one of its copies.
*/
fun isShownFrom(source: CArtMeshSource, modelImage: CModelImage): Boolean {
val sampled = sampledResourceOf(source) ?: return false
// CMO3: CModelImage field _filteredImage.
return sampled === modelImage._filteredImage || ownerByReducedCopy[sampled] === modelImage
}
/**
* Whether a resource was a reduced copy when the graph was read.
*
* @param CImageResource resource The resource.
* @return Boolean True for a copy.
*/
fun isReducedCopy(resource: CImageResource): Boolean = resource in ownerByReducedCopy
private companion object {
/**
* Whether a 2x3 uv affine changes nothing.
*
* @param FloatArray affine The affine (m00, m01, m02, m10, m11, m12).
* @return Boolean True for the identity.
*/
fun isIdentityAffine(affine: FloatArray): Boolean =
affine[0] == 1f && affine[1] == 0f && affine[2] == 0f && affine[3] == 0f && affine[4] == 1f && affine[5] == 0f
/**
* The model u a stored pair imports to: the cache frame's inverse, the one expression import uses.
*
* @param CAffine affine The raster-to-cache affine.
* @param Float determinant Its linear part's determinant, nonzero.
* @param Float storedU The stored u.
* @param Float storedV The stored v.
* @return Float The model u.
*/
fun inverseU(affine: CAffine, determinant: Float, storedU: Float, storedV: Float): Float =
(affine.m11 * (storedU - affine.m02) - affine.m01 * (storedV - affine.m12)) / determinant
/**
* The model v a stored pair imports to: the cache frame's inverse, the one expression import uses.
*
* @param CAffine affine The raster-to-cache affine.
* @param Float determinant Its linear part's determinant, nonzero.
* @param Float storedU The stored u.
* @param Float storedV The stored v.
* @return Float The model v.
*/
fun inverseV(affine: CAffine, determinant: Float, storedU: Float, storedV: Float): Float =
(-affine.m10 * (storedU - affine.m02) + affine.m00 * (storedV - affine.m12)) / determinant
/**
* The image a drawable's texture names.
*
* @param CArtMeshSource source The drawable's graph source.
* @return CImageResource? The image, or null without one.
*/
fun sampledResourceOf(source: CArtMeshSource): CImageResource? =
// CMO3: CArtMeshSource field texture -> GTexture2D field srcImageResource.
(source.texture as? GTexture2D)?.srcImageResource as? CImageResource
/**
* A drawable's raster-to-cache affine, or null when it has none or it is the identity.
*
* @param CArtMeshSource source The drawable's graph source.
* @return CAffine? The affine.
*/
fun cacheAffineOf(source: CArtMeshSource): CAffine? {
// CMO3: GTexture2D field transformImageResource01toLogical01 - a CAffine taking the raster's [0,1]
// into the cache frame's [0,1].
val affine = (source.texture as? GTexture2D)?.transformImageResource01toLogical01 as? CAffine ?: return null
val isIdentity =
affine.m00 == 1f &&
affine.m01 == 0f &&
affine.m02 == 0f &&
affine.m10 == 0f &&
affine.m11 == 1f &&
affine.m12 == 0f
return affine.takeUnless { isIdentity }
}
/**
* Every reduced copy in the graph, to the model image it is a copy of.
*
* A copy is any cached image of a model image other than the raster itself; an atlas page is never
* one, even should a cache ever name it.
*
* @param CModelSource modelSource The CMO3's root model source.
* @return Map<CImageResource, CModelImage> The copies and their owners.
*/
fun reducedCopiesOf(modelSource: CModelSource): Map<CImageResource, CModelImage> {
// CMO3: CModelSource field textureManager.
val textureManager = modelSource.textureManager as? CTextureManager ?: return emptyMap()
// CMO3: CTextureManager field _textureAtlases -> CTextureAtlas field cachedAtlasImage.
val pages =
Cmo3Import.elementsOf(textureManager._textureAtlases).filterIsInstance<CTextureAtlas>()
.mapNotNull { atlas -> atlas.cachedAtlasImage as? CImageResource }
.toHashSet()
val ownerByCopy = HashMap<CImageResource, CModelImage>()
// CMO3: CTextureManager field _modelImageGroups -> CModelImageGroup field _modelImages.
for (group in Cmo3Import.elementsOf(textureManager._modelImageGroups).filterIsInstance<CModelImageGroup>()) {
for (modelImage in Cmo3Import.elementsOf(group._modelImages).filterIsInstance<CModelImage>()) {
val raster = modelImage._filteredImage as? CImageResource
// CMO3: CModelImage field cachedImageManager -> CCachedImageManager field cachedImages ->
// CCachedImage field _cachedImageResource - the raster itself at SCALE_1, and a reduced
// copy beside it when the editor made one.
val manager = modelImage.cachedImageManager as? CCachedImageManager ?: continue
for (cached in Cmo3Import.elementsOf(manager.cachedImages).filterIsInstance<CCachedImage>()) {
val resource = cached._cachedImageResource as? CImageResource ?: continue
if (resource !== raster && resource !in pages) {
ownerByCopy[resource] = modelImage
}
}
}
}
return ownerByCopy
}
}
}
@@ -0,0 +1,42 @@
package org.umamo.interop.moc3
/**
* What a MOC3 export includes, chosen at export time rather than stored on the document.
*
* The defaults here are the API's compatibility contract, not the export dialog's: an options-less
* call behaves exactly as the lowering always has - hidden objects carried with their flag clear,
* guide subtrees dropped, every sidecar emitted, and the canvas scale resolved by
* [org.umamo.interop.moc3.export.Moc3Export.mocPixelsPerUnitFor]. The dialog seeds its own
* first-launch defaults in the UI layer, and those match the official editor's bake instead
* (hidden objects dropped), so the two default sets are deliberately not the same thing.
*
* One class carries both the lowering's flags and the bundle's sidecar toggles, so an export
* handler threads a single value end to end. A future texture-resolution scale is one more
* defaulted property here.
*
* @property Boolean exportHiddenParts Write hidden part subtrees, flag clear, instead of
* dropping them the way the official bake does.
* @property Boolean exportHiddenDrawables Write drawables whose own flag is hidden, flag clear,
* instead of dropping them.
* @property Boolean exportGuideImageParts Write guide-image (sketch) subtrees instead of dropping
* them.
* @property Boolean includePhysics Carry a retained physics3.json through the bundle.
* @property Boolean includeUserData Carry a retained userdata3.json through the bundle.
* @property Boolean includeDisplayInfo Synthesize the cdi3.json display-info sidecar.
* @property Float? pixelsPerUnitOverride The bake scale to write, or null to resolve it from the
* model (the recorded scale, else the canvas width).
*/
data class Moc3ExportOptions(
val exportHiddenParts: Boolean = true,
val exportHiddenDrawables: Boolean = true,
val exportGuideImageParts: Boolean = false,
val includePhysics: Boolean = true,
val includeUserData: Boolean = true,
val includeDisplayInfo: Boolean = true,
val pixelsPerUnitOverride: Float? = null,
) {
companion object {
/** The options-less behavior: exactly what the lowering did before options existed. */
val Default: Moc3ExportOptions = Moc3ExportOptions()
}
}
@@ -0,0 +1,267 @@
package org.umamo.interop.moc3
import org.umamo.format.FileKind
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.json.Cdi3Json
import org.umamo.format.moc3.json.DisplayDrawable
import org.umamo.format.moc3.json.DisplayParameter
import org.umamo.format.moc3.json.DisplayParameterGroup
import org.umamo.format.moc3.json.DisplayPart
import org.umamo.format.moc3.json.FileReferences
import org.umamo.format.moc3.json.Model3Json
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.interop.ExportReport
import org.umamo.interop.moc3.export.CanvasToParentSpace
import org.umamo.interop.moc3.export.Moc3Export
import org.umamo.interop.moc3.export.Moc3WrittenIds
import org.umamo.interop.mocVersion
import org.umamo.runtime.model.ParameterNode
import org.umamo.runtime.model.PuppetModel
/**
* Builds the whole `.moc3` FILE FAMILY - the moc, its `model3.json` manifest, a `cdi3.json` of
* display names, the atlas pages, and whatever sidecars the document was imported with.
*
* A baked model is a family, not a file: the runtime loads the manifest, and the manifest is what
* names the atlas pages a moc's texture indices point into. Writing the moc alone produces something
* no runtime can open, so the export's unit is this bundle.
*
* Everything here is pure - the caller supplies the atlas bytes and the retained sidecar texts, and
* receives named byte arrays to write wherever it likes. That keeps the family layout testable
* without a filesystem, and keeps the IO (and its per-platform limits) in the app layer.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md § Export</a>
*/
object Moc3Sidecars {
/** The moc extension the family's base name is derived against, dotted for the name strip. */
private val MOC3_EXTENSION: String = ".${FileKind.Moc3.extension}"
/**
* The family base name for a moc file called [fileName] - every sibling is named off this.
*
* The strip ignores CASE. A file spelled `X.MOC3` would otherwise keep its extension in the base
* name, and every generated sibling - the manifest included - would be named after an `X.MOC3.moc3`
* that no write ever produces. Import and export both derive the name this way, so a re-export
* lands the family in the shape the model already used.
*
* @param String fileName The moc's own file name.
* @return String The base name the rest of the family hangs off.
*/
fun basenameFor(fileName: String): String =
if (fileName.endsWith(MOC3_EXTENSION, ignoreCase = true)) {
fileName.dropLast(MOC3_EXTENSION.length)
} else {
fileName
}
/** The cdi3 schema version the editor writes. */
private const val CDI3_VERSION: Int = 3
/** The model3 schema version the editor writes. */
private const val MODEL3_VERSION: Int = 3
/**
* One file of the exported family.
*
* @property String name The file name, relative to the moc's own directory.
* @property ByteArray bytes The contents.
*/
class BundleFile(val name: String, val bytes: ByteArray)
/**
* A retained sidecar carried through untouched.
*
* Pass-through, not synthesis: physics, poses, expressions, and user data are authored elsewhere
* and reference parameters and parts by id, which the export preserves - so re-emitting the
* original text is both lossless and the only honest option, since Umamo does not model them.
*
* @property SidecarKind kind Which sidecar this is, for the manifest wiring below.
* @property String fileName The name to write it under.
* @property String text The original file's text.
*/
class PassThroughSidecar(val kind: SidecarKind, val fileName: String, val text: String)
/** The sidecar families a MOC3 export carries through from the imported document. */
enum class SidecarKind {
Physics,
Pose,
UserData,
Expression,
Motion,
}
/**
* One atlas page's bytes and the name to write them under.
*
* @property String fileName The page's file name, manifest-relative.
* @property ByteArray bytes The PNG bytes, verbatim from the source when there is one.
*/
class AtlasPage(val fileName: String, val bytes: ByteArray)
/**
* The complete export: every file to write, plus the lowering's advisory report.
*
* @property List files The family, moc first.
* @property ExportReport report The notices from the moc lowering.
*/
class Bundle(val files: List<BundleFile>, val mocFileName: String, val report: ExportReport)
/**
* Builds the family for [puppet].
*
* @param PuppetModel puppet The rig to export.
* @param String basename The family's base name (no extension).
* @param MocVersion version The moc version to bake; the document's runtime target by default.
* @param List pages The atlas pages, in the drawables' texture-page index order.
* @param List sidecars The retained sidecars to carry through.
* @param Model3Json? source The imported manifest, whose non-file sections carry through.
* @param CanvasToParentSpace? canvasToParentSpace The unkeyed-drawable space inverse, or null.
* @param Moc3ExportOptions options What the rigger chose to include; the default is the
* options-less behavior.
* @return Bundle The files to write, which of them is the moc, and the report.
*/
fun bundle(
puppet: PuppetModel,
basename: String,
version: MocVersion = puppet.runtimeTarget.mocVersion(),
pages: List<AtlasPage>,
sidecars: List<PassThroughSidecar> = emptyList(),
source: Model3Json? = null,
canvasToParentSpace: CanvasToParentSpace? = null,
options: Moc3ExportOptions = Moc3ExportOptions.Default,
): Bundle {
// Lowered rather than written outright, because the cdi3 below has to name the objects by the ids
// the MOC actually got: an id the record width forced short is not the id the model carries.
val lowered = Moc3Export.toMocDocument(puppet, version, canvasToParentSpace, options)
val mocBytes = Moc3.write(lowered.document)
val report = lowered.report
val mocFileName = "$basename$MOC3_EXTENSION"
// Null when the rigger opted the cdi3 out: the file and the manifest's reference to it must
// move together, or the manifest names a file the bundle does not contain.
val displayInfoName = "$basename.cdi3.json".takeIf { options.includeDisplayInfo }
val files = ArrayList<BundleFile>(pages.size + sidecars.size + 3)
files.add(BundleFile(mocFileName, mocBytes))
if (displayInfoName != null) {
files.add(
BundleFile(displayInfoName, Moc3.writeCdi3(displayInfo(puppet, lowered.writtenIds)).encodeToByteArray()),
)
}
for (page in pages) {
files.add(BundleFile(page.fileName, page.bytes))
}
for (sidecar in sidecars) {
files.add(BundleFile(sidecar.fileName, sidecar.text.encodeToByteArray()))
}
val manifest =
Model3Json(
version = MODEL3_VERSION,
fileReferences =
FileReferences(
moc = mocFileName,
textures = pages.map { page -> page.fileName },
pose = sidecars.firstOrNull { it.kind == SidecarKind.Pose }?.fileName,
physics = sidecars.firstOrNull { it.kind == SidecarKind.Physics }?.fileName,
userData = sidecars.firstOrNull { it.kind == SidecarKind.UserData }?.fileName,
displayInfo = displayInfoName,
// Expression and motion entries carry their own fade times and group names, so the
// source's own entries are re-emitted rather than rebuilt from the file list - the
// files themselves ride along in `sidecars` under those same relative names.
expressions = source?.fileReferences?.expressions,
motions = source?.fileReferences?.motions,
),
// Auto-wiring groups (EyeBlink / LipSync) and hit areas are USER DATA that lives only in
// the manifest. Nothing in PuppetModel holds them, so dropping them here would quietly
// delete a rigger's eye-blink wiring on the first MOC3 round trip.
groups = source?.groups,
hitAreas = source?.hitAreas,
)
files.add(BundleFile("$basename.model3.json", Moc3.writeModel3(manifest).encodeToByteArray()))
return Bundle(files, mocFileName, report)
}
/**
* The `cdi3.json` for [puppet]: parameter, group, part, and art-mesh display names.
*
* Written whenever [Moc3ExportOptions.includeDisplayInfo] allows it, even when every name equals
* its id. A cdi3 is what carries the ONE thing the MOC3 cannot - what the rigger called each
* object - and deciding it is "not worth writing" because this model happens to use default names
* would make the family's shape depend on the data in it. The rigger's explicit opt-out in the
* export options is the one sanctioned exception: a CHOICE may shape the family, the data may not.
*
* Every id here is the id the MOC was written with, taken from [writtenIds] rather than from the
* model: the runtime joins the two files on that string, so an id the record width forced short
* would leave its cdi3 entry naming an object the MOC3 does not contain - the display name, the
* parameter's group placement, and its combined-parameter pairing all quietly stranded. Parameter
* GROUP ids are the exception, and stay verbatim: they exist only in this file, so no MOC3 record
* bounds them.
*
* Parts and art meshes are also filtered to the ones the lowering actually WROTE - the export drops
* sketch subtrees, mesh-less drawables, and unkeyed drawables it cannot invert into parent space.
* Naming a dropped object is dead weight on its own, and worse than that alongside the shortening
* above: a dropped object claims no id, so an over-long id can shorten onto exactly its string and
* leave the file with two entries under one id for a reader's join to choose between.
*
* @param PuppetModel puppet The rig.
* @param Moc3WrittenIds writtenIds What the lowering wrote each object's id as.
* @return Cdi3Json The display info.
*/
fun displayInfo(
puppet: PuppetModel,
writtenIds: Moc3WrittenIds,
): Cdi3Json {
val groupIdByParameter = HashMap<String, String>()
val groups = ArrayList<DisplayParameterGroup>()
/**
* Walks the parameter tree, recording each group and the group every parameter belongs to.
*
* @param List nodes The nodes at this level.
* @param String parentGroupId The enclosing group's id, empty at the root.
*/
fun walk(nodes: List<ParameterNode>, parentGroupId: String) {
for (node in nodes) {
when (node) {
is ParameterNode.Param -> groupIdByParameter[node.id.raw] = parentGroupId
is ParameterNode.Group -> {
groups.add(DisplayParameterGroup(id = node.id.raw, groupId = parentGroupId, name = node.name))
walk(node.children, node.id.raw)
}
}
}
}
walk(puppet.parameterTree, "")
return Cdi3Json(
version = CDI3_VERSION,
parameters =
puppet.parameters.map { parameter ->
DisplayParameter(
id = writtenIds.parameterId(parameter.id),
// Keyed by the MODEL id: the group walk above indexed the parameter tree, which
// holds model ids like everything else in the rig.
groupId = groupIdByParameter[parameter.id.raw] ?: "",
name = parameter.name,
)
},
parameterGroups = groups,
parts =
puppet.parts
.filter { part -> writtenIds.wrotePart(part.id) }
.map { part -> DisplayPart(id = writtenIds.partId(part.id), name = part.name) },
// The pair order is the same one the import reads back: horizontal first, then vertical.
combinedParameters =
puppet.parameterLinks
.map { link ->
listOf(writtenIds.parameterId(link.horizontal), writtenIds.parameterId(link.vertical))
}
.takeIf { links -> links.isNotEmpty() },
drawables =
puppet.drawables
.filter { drawable -> writtenIds.wroteDrawable(drawable.id) }
.map { drawable ->
DisplayDrawable(id = writtenIds.drawableId(drawable.id), name = drawable.name)
}
.takeIf { meshes -> meshes.isNotEmpty() },
)
}
}
@@ -0,0 +1,231 @@
package org.umamo.interop.moc3
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
/*
* The coordinate seam between a `.moc3`'s stored values and the runtime's convention, in BOTH
* directions.
*
* MOC3 stores geometry in three different spaces depending on what an object hangs from, and only
* one of them differs from the runtime's - so an import converts a minority of values and an
* export has to invert exactly that same minority. There is also a unit seam on rotation scale
* that is easy to miss and impossible to see in a single object: the FIRST rotation on each root
* path carries the pixels-per-unit factor and every rotation below it does not.
*
* Import and export live in one file because the failure mode of two copies is invisible until it
* is catastrophic. Get the rotation-ancestor predicate subtly wrong in one of them and a whole
* subtree exports at the wrong scale, with nothing but a differential oracle to say so.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.3</a>
*/
/** The coordinate space an object's stored positions live in, selected by its parent deformer. */
enum class PointSpace {
/** MOC3 model space (a root object): canvas = CanvasInfo origin + ppu·model, Y-down like the canvas. */
ModelRoot,
/** A warp parent's normalized lattice (u, v) - identical in both conventions. */
WarpLattice,
/** A rotation parent's pixel-scale local frame - identical in both conventions. */
RotationLocal,
}
/**
* The canvas mapping a `.moc3` stores, as the two numbers every conversion here needs.
*
* @property Float pixelsPerUnit Canvas pixels per model unit; 1 when the source carried no canvas.
* @property Float originX The canvas-space origin's x.
* @property Float originY The canvas-space origin's y, in CANVAS orientation (not negated).
*/
class MocCanvasMapping(
val pixelsPerUnit: Float,
val originX: Float,
val originY: Float,
)
/**
* The scale every conversion in this file actually applies.
*
* A degenerate canvas (ppu 0) has no invertible scale: dividing by it is a division by zero, and
* multiplying by it collapses the whole rig onto the canvas origin. Both directions therefore
* substitute the identity, which is also how the import treats a canvas-less document.
*
* Shared rather than written out per direction because a guard applied on only one side is exactly
* how the two stop being inverses - the moc direction would map a degenerate canvas as the identity
* while the runtime direction flattened every point onto one spot, and nothing here would say so.
*
* @param MocCanvasMapping canvas The document's canvas mapping.
* @return Float The scale factor to apply.
*/
private fun effectiveScale(canvas: MocCanvasMapping): Float =
if (canvas.pixelsPerUnit != 0f) canvas.pixelsPerUnit else 1f
/**
* Converts interleaved x,y [points] from the moc's stored [space] to the runtime's convention.
*
* Warp-lattice and rotation-local values are already in the runtime's convention (corpus-verified) and
* pass through untouched; only root-space values map through the canvas affine.
*
* @param PointSpace space The stored space.
* @param FloatArray points Interleaved x,y positions as stored in the moc.
* @param MocCanvasMapping canvas The document's canvas mapping.
* @return FloatArray The converted positions (always a fresh array).
*/
fun convertPointsToRuntime(space: PointSpace, points: FloatArray, canvas: MocCanvasMapping): FloatArray {
val converted = FloatArray(points.size)
val scale = effectiveScale(canvas)
var coordIndex = 0
while (coordIndex + 1 < points.size) {
when (space) {
// MOC3 §5.3 CanvasInfo: canvas px = origin + ppu·model, same Y-down orientation.
PointSpace.ModelRoot -> {
converted[coordIndex] = canvas.originX + scale * points[coordIndex]
converted[coordIndex + 1] = canvas.originY + scale * points[coordIndex + 1]
}
// Warp-lattice (u, v) and pixel-scale rotation-local frames match the runtime verbatim.
PointSpace.WarpLattice, PointSpace.RotationLocal -> {
converted[coordIndex] = points[coordIndex]
converted[coordIndex + 1] = points[coordIndex + 1]
}
}
coordIndex += 2
}
return converted
}
/**
* The exact inverse of [convertPointsToRuntime]: runtime positions back to the moc's stored [space].
*
* @param PointSpace space The space to store in.
* @param FloatArray points Interleaved x,y positions in the runtime's convention.
* @param MocCanvasMapping canvas The document's canvas mapping.
* @return FloatArray The values to store (always a fresh array).
*/
fun convertPointsToMoc(space: PointSpace, points: FloatArray, canvas: MocCanvasMapping): FloatArray {
val converted = FloatArray(points.size)
val scale = effectiveScale(canvas)
var coordIndex = 0
while (coordIndex + 1 < points.size) {
when (space) {
PointSpace.ModelRoot -> {
converted[coordIndex] = (points[coordIndex] - canvas.originX) / scale
converted[coordIndex + 1] = (points[coordIndex + 1] - canvas.originY) / scale
}
PointSpace.WarpLattice, PointSpace.RotationLocal -> {
converted[coordIndex] = points[coordIndex]
converted[coordIndex + 1] = points[coordIndex + 1]
}
}
coordIndex += 2
}
return converted
}
/**
* Converts interleaved delta components from the moc's stored [space] to the runtime's convention.
*
* Unlike [convertPointsToRuntime] the canvas ORIGIN does not apply - it cancels out of a difference -
* so a root-space delta scales by ppu only; the other spaces pass through.
*
* @param PointSpace space The stored space.
* @param FloatArray deltas Interleaved x,y deltas as stored in the moc.
* @param MocCanvasMapping canvas The document's canvas mapping.
* @return FloatArray The converted deltas (always a fresh array).
*/
fun convertDeltasToRuntime(space: PointSpace, deltas: FloatArray, canvas: MocCanvasMapping): FloatArray =
when (space) {
PointSpace.ModelRoot -> {
val scale = effectiveScale(canvas)
FloatArray(deltas.size) { index -> scale * deltas[index] }
}
PointSpace.WarpLattice, PointSpace.RotationLocal -> deltas.copyOf()
}
/**
* The exact inverse of [convertDeltasToRuntime].
*
* @param PointSpace space The space to store in.
* @param FloatArray deltas Interleaved x,y deltas in the runtime's convention.
* @param MocCanvasMapping canvas The document's canvas mapping.
* @return FloatArray The values to store (always a fresh array).
*/
fun convertDeltasToMoc(space: PointSpace, deltas: FloatArray, canvas: MocCanvasMapping): FloatArray {
val scale = effectiveScale(canvas)
return when (space) {
PointSpace.ModelRoot -> FloatArray(deltas.size) { index -> deltas[index] / scale }
PointSpace.WarpLattice, PointSpace.RotationLocal -> deltas.copyOf()
}
}
/**
* The px→model unit factor a rotation deformer's stored scale carries.
*
* Along every root path the FIRST rotation is where the accumulated scale chain converts pixel-scale
* local space into model units, so only that rotation's stored scale carries the factor. Every
* rotation below it - whatever its direct parent's kind - inherits it through the accumulator and
* stores its scale verbatim.
*
* @param Boolean hasRotationAncestor Whether a rotation sits anywhere above this deformer.
* @param MocCanvasMapping canvas The document's canvas mapping.
* @return Float The multiplier taking a stored scale to the runtime's, 1 when a rotation is above.
*/
fun rotationScaleFactor(hasRotationAncestor: Boolean, canvas: MocCanvasMapping): Float =
if (hasRotationAncestor) 1f else effectiveScale(canvas)
/**
* Whether a rotation deformer sits anywhere on each deformer's ancestor chain, by FILE index.
*
* @param Int deformerCount How many deformers there are.
* @param Function parentIndexOf Each deformer's parent index (-1 at the root).
* @param Function isRotationAt Whether the deformer at an index is a rotation.
* @return BooleanArray Indexed like the deformer list.
*/
fun rotationAncestorFlags(
deformerCount: Int,
parentIndexOf: (Int) -> Int,
isRotationAt: (Int) -> Boolean,
): BooleanArray =
BooleanArray(deformerCount) { deformerIndex ->
var currentIndex = parentIndexOf(deformerIndex)
var found = false
// The step cap breaks a malformed cyclic parent chain rather than hanging on it.
var chainSteps = 0
while (currentIndex in 0 until deformerCount && chainSteps <= deformerCount) {
if (isRotationAt(currentIndex)) {
found = true
break
}
currentIndex = parentIndexOf(currentIndex)
chainSteps++
}
found
}
/**
* [rotationAncestorFlags] over a RUNTIME deformer list, keyed by deformer id.
*
* The export walks ids rather than file indices, but the predicate must stay the one the import used -
* hence one implementation with two adapters rather than two walks.
*
* @param List deformers The runtime deformers.
* @return Map Whether a rotation sits above each deformer.
*/
fun rotationAncestorsById(deformers: List<Deformer>): Map<DeformerId, Boolean> {
val byId = deformers.associateBy { deformer -> deformer.id }
return deformers.associate { deformer ->
var current = deformer.parent?.let { byId[it] }
var found = false
var chainSteps = 0
while (current != null && chainSteps <= deformers.size) {
if (current is Deformer.Rotation) {
found = true
break
}
current = current.parent?.let { byId[it] }
chainSteps++
}
deformer.id to found
}
}
@@ -0,0 +1,174 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.moc.ConstantFlag
import org.umamo.format.moc3.model.ArtMesh
import org.umamo.format.moc3.model.ArtMeshKeyform
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportNoticeReason
import org.umamo.interop.legacyBlendFlagOf
import org.umamo.interop.moc3.convertPointsToMoc
import org.umamo.interop.packedBlendOf
import org.umamo.runtime.keyform.MeshDeltaInterpolator
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.MeshDeltaForm
/**
* Lowers every exportable drawable into its MOC3 art-mesh record.
*
* @param Moc3ExportContext context The export's derived state.
* @param Moc3KeyformPool pool Interned into: every art mesh claims a binding index here.
* @param Moc3ExportIds ids Claimed from: each drawable's written id.
* @param Moc3ExportNotices noticeSink Appended to: demotions and unresolvable masks.
* @return List<ArtMesh> The records, in plan order.
*/
internal fun lowerArtMeshes(
context: Moc3ExportContext,
pool: Moc3KeyformPool,
ids: Moc3ExportIds,
noticeSink: Moc3ExportNotices,
): List<ArtMesh> {
val plan = context.plan
val canvasToParentSpace = context.canvasToParentSpace
return plan.drawables.map { drawable ->
val mesh = drawable.mesh!!
val space = context.spaceOfParent(drawable.parentDeformerId)
// An unkeyed drawable under a deformer has no deltas to recover parent-local from, so the
// injected seam must supply it. That seam inverts canvas-space rests (MOC3 import after
// restMeshesToCanvasSpace) and leaves already-parent-local rests alone (UMA / CMO3 / warp-
// create UV) - applying the inverse blindly would double-transform the latter. A keyed
// drawable already reconstructs parent-local as base + delta, so the seam is asked only
// where it is needed.
val basePositions =
if (drawable.geometryGrid == null && drawable.parentDeformerId != null) {
canvasToParentSpace?.invoke(drawable.id, mesh.positions)?.also { converted ->
if (converted.size != mesh.positions.size) {
noticeSink.unsupported(
ExportEntityCategory.Drawable,
drawable.id.raw,
ExportNoticeReason.RestMeshConversionSizeMismatch(
converted.size,
mesh.positions.size,
),
)
}
}?.takeIf { converted -> converted.size == mesh.positions.size } ?: mesh.positions
} else {
mesh.positions
}
val keyforms =
lowerObjectKeyforms(
pool,
drawable.geometryGrid,
MeshDeltaInterpolator,
drawable.channelGrids.onlyChannels(
*(renderChannels(context.colorsEnabled) + arrayOf(FormChannel.DRAW_ORDER)),
),
renderStatics(drawable.opacity, drawable.multiplyColor, drawable.screenColor, context.colorsEnabled) +
mapOf(FormChannel.DRAW_ORDER to ChannelValue.Scalar(drawable.drawOrder)),
requireGeometry = false,
)
noticeSink.reportDemotions(ExportEntityCategory.Drawable, drawable.id.raw, keyforms)
val bundle = keyforms?.bundle
val cellCount = maxOf(bundle?.cells?.size ?: 0, 1)
val triangleIndices =
ShortArray(mesh.indices.size) { index -> mesh.indices[index].toShort() }
// -1 is the "no atlas page bound" sentinel and a moc has no way to spell it, so the write
// clamps to page 0. On a multi-page rig that is the WRONG texture rather than a near miss,
// which is worth a notice even though the file it produces is structurally valid.
if (drawable.texturePage < 0) {
noticeSink.unsupported(
ExportEntityCategory.Drawable,
drawable.id.raw,
ExportNoticeReason.NoAtlasPageBound,
)
}
// A mask naming a drawable this export dropped has no file index to reference. Filtering it
// is the only option, but doing so silently would leave the mesh rendering unclipped with
// nothing in the report to explain why.
val maskIndices = ArrayList<Int>(drawable.maskedBy.size)
val unresolvedMasks = ArrayList<String>()
for (maskId in drawable.maskedBy) {
val maskIndex = plan.drawableIndex(maskId)
if (maskIndex >= 0) {
maskIndices.add(maskIndex)
} else {
unresolvedMasks.add(maskId.raw)
}
}
if (unresolvedMasks.isNotEmpty()) {
noticeSink.unsupported(
ExportEntityCategory.Drawable,
drawable.id.raw,
ExportNoticeReason.ClippingMaskNotInExport(unresolvedMasks.toList()),
)
}
ArtMesh(
id = ids.drawableId(drawable.id),
textureIndex = maxOf(drawable.texturePage, 0),
constantFlags = constantFlagsOf(drawable, context.extendedBlendEnabled),
// The 5.3 blend surface; below v6 the mode falls back to the legacy constant-flag bits.
extendedBlend =
if (context.extendedBlendEnabled) packedBlendOf(drawable.blendMode, drawable.alphaBlendMode) else 0,
isVisible = drawable.isVisible,
isEnabled = true,
parentPartIndex = plan.partIndex(context.partByDrawable[drawable.id]),
parentDeformerIndex = plan.deformerIndex(drawable.parentDeformerId),
vertexUvs = mesh.uvs.copyOf(),
triangleIndices = triangleIndices,
maskDrawableIndices = maskIndices.toIntArray(),
keyformBindingIndex = keyforms?.bindingIndex ?: 0,
keyforms =
(0 until cellCount).map { cellIndex ->
// THE load-bearing invariant: base + delta is the absolute parent-space position.
val deltas =
(bundle?.cells?.getOrNull(cellIndex)?.geometry as? MeshDeltaForm)
?.positionDeltas
val absolute =
FloatArray(basePositions.size) { coordinate ->
basePositions[coordinate] + (deltas?.getOrNull(coordinate) ?: 0f)
}
ArtMeshKeyform(
vertexPositions = convertPointsToMoc(space, absolute, context.canvas),
opacity =
bundle?.let { scalarOf(it, cellIndex, FormChannel.OPACITY, drawable.opacity) }
?: drawable.opacity,
drawOrder =
bundle?.let { scalarOf(it, cellIndex, FormChannel.DRAW_ORDER, drawable.drawOrder) }
?: drawable.drawOrder,
multiplyColor =
colorOf(bundle, cellIndex, FormChannel.MULTIPLY_COLOR, drawable.multiplyColor, context.colorsEnabled),
screenColor =
colorOf(bundle, cellIndex, FormChannel.SCREEN_COLOR, drawable.screenColor, context.colorsEnabled),
)
},
)
}
}
/**
* The drawable's constant-flag byte.
*
* Note bit 2 is the INVERSE of culling: the flag means "double sided", so a culled drawable clears
* it. Getting that backwards silently double-draws every back face.
*
* @param Drawable drawable The drawable.
* @param Boolean extendedBlendEnabled Whether the target version carries the 5.3 extended-blend
* section, which then states the blend mode instead of the
* legacy bits.
* @return Int The flag bits.
*/
private fun constantFlagsOf(drawable: Drawable, extendedBlendEnabled: Boolean): Int {
// On moc 6 the extended-blend section is authoritative and the editor leaves the legacy 2-bit pair
// CLEAR even for an additive or multiply mesh - writing both would state the mode twice, and the
// legacy pair cannot express the other sixteen modes anyway.
var flags = if (extendedBlendEnabled) 0 else legacyBlendFlagOf(drawable.blendMode)
if (!drawable.culling) {
flags = flags or ConstantFlag.IS_DOUBLE_SIDED
}
if (drawable.invertMask) {
flags = flags or ConstantFlag.IS_INVERTED_MASK
}
return flags
}
@@ -0,0 +1,322 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.model.ArtMeshKeyform
import org.umamo.format.moc3.model.BlendShape
import org.umamo.format.moc3.model.BlendShapeKeyform
import org.umamo.format.moc3.model.BlendShapeLimit
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.format.moc3.model.Rgb
import org.umamo.format.moc3.model.RotationKeyform
import org.umamo.format.moc3.model.WarpKeyform
import org.umamo.interop.moc3.MocCanvasMapping
import org.umamo.interop.moc3.PointSpace
import org.umamo.interop.moc3.convertDeltasToMoc
import org.umamo.runtime.eval.colorAt
import org.umamo.runtime.eval.meshGridDefaultDeltas
import org.umamo.runtime.eval.rotationFormAt
import org.umamo.runtime.eval.scalarAt
import org.umamo.runtime.eval.warpControlPointsAt
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartForm
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpForm
/*
* Lowers the runtime's blend-shape bindings back into MOC3 records.
*
* A stored MOC3 blend row is a pure DELTA; the runtime form is that delta plus the object's grid form
* interpolated at the DEFAULT pose, which the import added so the evaluator can subtract the same
* reference back out. Exporting therefore means subtracting that reference again - and it has to be
* the SAME reference, computed by the same `org.umamo.runtime.eval` samplers the evaluator calls, or
* the loop does not close.
*
* The reference comes from the SESSION grid, not from a refined copy. That is the fixed point: the
* evaluator subtracts whatever grid the model currently holds, a re-import of this export rebuilds
* exactly that grid, so sampling the session grid makes export → import → eval cancel. (Compaction's
* refinement is bit-exact, so the two sample identically anyway - but only one of them is the
* definition.)
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
/**
* Builds every blend-shape record for the document.
*
* `recordBase` is left at 0 deliberately: `MocLowering.blendShapeSections` recomputes it as a running
* per-kind cursor over the value tables, so a value carried here would be ignored at best and stale at
* worst.
*
* @param List drawables The drawables in file order.
* @param List deformers The deformers in file order.
* @param List parts The parts in file order.
* @param List parameters The parameters in file order.
* @param Moc3IndexPlan plan The index plan.
* @param MocCanvasMapping canvas The canvas mapping, for un-converting positional deltas.
* @param Function spaceOfParent The space a child of the given parent deformer stores its positions in.
* @param Function scaleFactorOf The px→model factor for a rotation deformer.
* @param Boolean colorsEnabled Whether the target version carries color tables.
* @return List<BlendShape> The records, in no particular order (the lowering orders them).
*/
internal fun lowerBlendShapes(
drawables: List<Drawable>,
deformers: List<Deformer>,
parts: List<Part>,
parameters: List<Parameter>,
plan: Moc3IndexPlan,
canvas: MocCanvasMapping,
spaceOfParent: (DeformerId?) -> PointSpace,
scaleFactorOf: (Deformer.Rotation) -> Float,
colorsEnabled: Boolean,
): List<BlendShape> {
val defaultByParameter = parameters.associate { parameter -> parameter.id to parameter.default }
val defaultValue: (ParameterId) -> Float = { id -> defaultByParameter[id] ?: 0f }
val records = ArrayList<BlendShape>()
/**
* The delta of a color channel against its reference, or null when colors are not written.
*
* @param ColorRgb form The form's color (reference + delta).
* @param ColorRgb reference The channel's value at the default pose.
* @return Rgb? The stored delta row.
*/
fun colorDelta(form: ColorRgb, reference: ColorRgb): Rgb? =
if (colorsEnabled) {
Rgb(form.red - reference.red, form.green - reference.green, form.blue - reference.blue)
} else {
null
}
/**
* Assembles one record from a binding, given a per-key payload builder.
*
* The NEUTRAL key's form is null in the runtime binding and its stored row is all zeros, which the
* builder produces naturally by receiving null.
*
* @param BlendShapeTarget target The owner kind.
* @param Int localIndex The owner's kind-local index.
* @param BlendShapeBinding binding The runtime binding.
* @param Function payloadOf Builds one key's delta payload (null form = the neutral row).
*/
fun <TForm : Any> addRecord(
target: BlendShapeTarget,
localIndex: Int,
binding: BlendShapeBinding<TForm>,
payloadOf: (TForm?) -> BlendShapeKeyform,
) {
val parameterIndex = plan.parameterIndex(binding.parameterId)
if (parameterIndex < 0) {
return
}
records.add(
BlendShape(
target = target,
targetIndex = localIndex,
parameterIndex = parameterIndex,
keyPositions = binding.keys.copyOf(),
neutralKeyIndex = binding.neutralIndex,
// Recomputed by the lowering; see this function's docblock.
recordBase = 0,
limits =
binding.limits.mapNotNull { limit ->
val limitParameter = plan.parameterIndex(limit.parameterId)
if (limitParameter < 0) {
return@mapNotNull null
}
BlendShapeLimit(
parameterIndex = limitParameter,
keyPositions = limit.points.map { point -> point.value }.toFloatArray(),
weights = limit.points.map { point -> point.weight }.toFloatArray(),
)
},
keyforms = binding.forms.map(payloadOf),
),
)
}
// ---- drawables ----
for (drawable in drawables) {
if (drawable.blendShapes.isEmpty()) {
continue
}
val localIndex = plan.drawableIndex(drawable.id)
val space = spaceOfParent(drawable.parentDeformerId)
val referenceDeltas = meshGridDefaultDeltas(drawable, defaultValue) ?: FloatArray(0)
val referenceDrawOrder =
drawable.channelGrids.scalarAt(FormChannel.DRAW_ORDER, drawable.drawOrder, defaultValue)
val referenceOpacity = drawable.channelGrids.scalarAt(FormChannel.OPACITY, drawable.opacity, defaultValue)
val referenceMultiply =
drawable.channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, drawable.multiplyColor, defaultValue)
val referenceScreen =
drawable.channelGrids.colorAt(FormChannel.SCREEN_COLOR, drawable.screenColor, defaultValue)
val vertexCount = drawable.mesh?.positions?.size ?: 0
for (binding in drawable.blendShapes) {
addRecord(BlendShapeTarget.ART_MESH, localIndex, binding) { form: MeshForm? ->
BlendShapeKeyform.Mesh(
ArtMeshKeyform(
vertexPositions =
if (form == null) {
FloatArray(vertexCount)
} else {
convertDeltasToMoc(
space,
FloatArray(vertexCount) { component ->
form.positionDeltas.getOrElse(component) { 0f } -
referenceDeltas.getOrElse(component) { 0f }
},
canvas,
)
},
opacity = if (form == null) 0f else form.opacity - referenceOpacity,
drawOrder = if (form == null) 0f else form.drawOrder - referenceDrawOrder,
multiplyColor =
if (form == null) {
colorDelta(referenceMultiply, referenceMultiply)
} else {
colorDelta(form.multiplyColor, referenceMultiply)
},
screenColor =
if (form == null) {
colorDelta(referenceScreen, referenceScreen)
} else {
colorDelta(form.screenColor, referenceScreen)
},
),
)
}
}
}
// ---- deformers ----
for (deformer in deformers) {
when (deformer) {
is Deformer.Warp -> {
if (deformer.blendShapes.isEmpty()) {
continue
}
// Resolved only once the deformer is known to carry blend shapes: `spaceOfParent` is a
// lookup the caller supplies, and asking it for every deformer in the rig would pay for a
// result that is discarded on all of them in a model with no blend shapes.
val space = spaceOfParent(deformer.parent)
// The UNIFIED deformer index, not the kind-local one: `MocLowering` maps it through
// `warpLocalByDeformer` itself, so handing it a kind-local index would re-map an already
// -mapped value and name a different deformer. The decoder produces the same convention.
val localIndex = plan.deformerIndex(deformer.id)
val reference = warpControlPointsAt(deformer.geometryGrid, defaultValue) ?: FloatArray(0)
val referenceOpacity =
deformer.channelGrids.scalarAt(FormChannel.OPACITY, deformer.opacity, defaultValue)
val referenceMultiply =
deformer.channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, deformer.multiplyColor, defaultValue)
val referenceScreen =
deformer.channelGrids.colorAt(FormChannel.SCREEN_COLOR, deformer.screenColor, defaultValue)
val pointCount = (deformer.rows + 1) * (deformer.columns + 1) * 2
for (binding in deformer.blendShapes) {
addRecord(BlendShapeTarget.WARP, localIndex, binding) { form: WarpForm? ->
BlendShapeKeyform.Warp(
WarpKeyform(
controlPoints =
if (form == null) {
FloatArray(pointCount)
} else {
convertDeltasToMoc(
space,
FloatArray(pointCount) { component ->
form.controlPoints.getOrElse(component) { 0f } -
reference.getOrElse(component) { 0f }
},
canvas,
)
},
opacity = if (form == null) 0f else form.opacity - referenceOpacity,
multiplyColor =
colorDelta(form?.multiplyColor ?: referenceMultiply, referenceMultiply),
screenColor = colorDelta(form?.screenColor ?: referenceScreen, referenceScreen),
),
)
}
}
}
is Deformer.Rotation -> {
if (deformer.blendShapes.isEmpty()) {
continue
}
// Resolved after the guard; see the warp branch.
val space = spaceOfParent(deformer.parent)
// Unified, not kind-local; see the warp branch.
val localIndex = plan.deformerIndex(deformer.id)
val reference =
rotationFormAt(deformer.geometryGrid, defaultValue) ?: RotationPivotForm(0f, 0f, 0f, 1f)
val referenceOpacity =
deformer.channelGrids.scalarAt(FormChannel.OPACITY, deformer.opacity, defaultValue)
val referenceMultiply =
deformer.channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, deformer.multiplyColor, defaultValue)
val referenceScreen =
deformer.channelGrids.colorAt(FormChannel.SCREEN_COLOR, deformer.screenColor, defaultValue)
val scaleFactor = scaleFactorOf(deformer)
for (binding in deformer.blendShapes) {
addRecord(BlendShapeTarget.ROTATION, localIndex, binding) { form: RotationForm? ->
val originDelta =
if (form == null) {
floatArrayOf(0f, 0f)
} else {
convertDeltasToMoc(
space,
floatArrayOf(
form.originX - reference.originX,
form.originY - reference.originY,
),
canvas,
)
}
BlendShapeKeyform.Rotation(
RotationKeyform(
originX = originDelta[0],
originY = originDelta[1],
angle = if (form == null) 0f else form.angle - reference.angle,
scale =
if (form == null) {
0f
} else {
(form.scale - reference.scale) / (if (scaleFactor != 0f) scaleFactor else 1f)
},
// Reflections are not blendable: MOC3 stores no flip delta row, so the stored
// value is the record's own neutral rather than a difference.
reflectX = false,
reflectY = false,
opacity = if (form == null) 0f else form.opacity - referenceOpacity,
multiplyColor =
colorDelta(form?.multiplyColor ?: referenceMultiply, referenceMultiply),
screenColor = colorDelta(form?.screenColor ?: referenceScreen, referenceScreen),
),
)
}
}
}
}
}
// ---- parts ----
for (part in parts) {
if (part.blendShapes.isEmpty()) {
continue
}
val localIndex = plan.partIndex(part.id)
val referenceDrawOrder =
part.channelGrids.scalarAt(FormChannel.DRAW_ORDER, part.drawOrder.toFloat(), defaultValue)
for (binding in part.blendShapes) {
addRecord(BlendShapeTarget.PART, localIndex, binding) { form: PartForm? ->
BlendShapeKeyform.Part(if (form == null) 0f else form.drawOrder - referenceDrawOrder)
}
}
}
return records
}
@@ -0,0 +1,182 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.RotationKeyform
import org.umamo.format.moc3.model.WarpDeformer
import org.umamo.format.moc3.model.WarpKeyform
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportNoticeReason
import org.umamo.interop.moc3.convertPointsToMoc
import org.umamo.runtime.keyform.RotationPivotInterpolator
import org.umamo.runtime.keyform.WarpLatticeInterpolator
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpLatticeForm
import org.umamo.format.moc3.model.Deformer as MocDeformer
/**
* Lowers every deformer in the plan into its MOC3 record, warps and rotations alike.
*
* Kept as one pass over `plan.deformers` rather than two per-kind passes: the file stores deformers in
* one unified list whose order is the addressing scheme, and the per-type columns are addressed through
* it - so splitting the walk would mean rebuilding that correspondence twice.
*
* @param Moc3ExportContext context The export's derived state.
* @param Moc3KeyformPool pool Interned into: every deformer claims a binding index here.
* @param Moc3ExportIds ids Claimed from: each deformer's written id.
* @param Moc3ExportNotices noticeSink Appended to: demotions and unrepresentable grids.
* @return List<MocDeformer> The records, in plan order.
*/
internal fun lowerDeformers(
context: Moc3ExportContext,
pool: Moc3KeyformPool,
ids: Moc3ExportIds,
noticeSink: Moc3ExportNotices,
): List<MocDeformer> {
val plan = context.plan
return plan.deformers.map { deformer ->
val parentPartIndex = plan.partIndex(deformer.partId)
val parentDeformerIndex = plan.deformerIndex(deformer.parent)
val space = context.spaceOfParent(deformer.parent)
when (deformer) {
is Deformer.Warp -> {
val keyforms =
lowerObjectKeyforms(
pool,
deformer.geometryGrid,
WarpLatticeInterpolator,
deformer.channelGrids.onlyChannels(*renderChannels(context.colorsEnabled)),
renderStatics(
deformer.opacity,
deformer.multiplyColor,
deformer.screenColor,
context.colorsEnabled,
),
requireGeometry = true,
)
noticeSink.reportDemotions(ExportEntityCategory.Deformer, deformer.id.raw, keyforms)
if (keyforms == null) {
noticeSink.unsupported(
ExportEntityCategory.Deformer,
deformer.id.raw,
ExportNoticeReason.WarpDeformerHasNoLattice,
)
}
val bundle = keyforms?.bundle
// A MOC3 addresses an object's forms as `gridSize` rows from its own keyform base, and
// the static binding 0 still declares ONE row - so an object that writes zero rows puts
// its base on top of the next object's, and the last one sends the reader off the end of
// the table. Every object kind writes at least one form for that reason.
val cellCount = maxOf(bundle?.cells?.size ?: 0, 1)
// Unlike a drawable, which falls back to its rest mesh, a grid-less warp has no lattice
// anywhere in the model - so the form it is obliged to write is a correctly SIZED empty
// one. The reader slices (rows + 1) x (columns + 1) control points back out by that
// arithmetic, and a short array would desynchronize every warp block after it.
val controlPointFloats = (deformer.rows + 1) * (deformer.columns + 1) * 2
WarpDeformer(
id = ids.deformerId(deformer.id),
keyformBindingIndex = keyforms?.bindingIndex ?: 0,
isVisible = deformer.isVisible,
isEnabled = deformer.isEnabled,
parentPartIndex = parentPartIndex,
parentDeformerIndex = parentDeformerIndex,
rows = deformer.rows,
columns = deformer.columns,
mode = if (deformer.isQuadTransform) 1 else 0,
keyforms =
(0 until cellCount).map { cellIndex ->
val lattice =
bundle?.cells?.getOrNull(cellIndex)?.geometry
as? WarpLatticeForm
WarpKeyform(
convertPointsToMoc(
space,
lattice?.controlPoints ?: FloatArray(controlPointFloats),
context.canvas,
),
bundle?.let { scalarOf(it, cellIndex, FormChannel.OPACITY, deformer.opacity) }
?: deformer.opacity,
colorOf(bundle, cellIndex, FormChannel.MULTIPLY_COLOR, deformer.multiplyColor, context.colorsEnabled),
colorOf(bundle, cellIndex, FormChannel.SCREEN_COLOR, deformer.screenColor, context.colorsEnabled),
)
},
)
}
is Deformer.Rotation -> {
val keyforms =
lowerObjectKeyforms(
pool,
deformer.geometryGrid,
RotationPivotInterpolator,
deformer.channelGrids.onlyChannels(
*(renderChannels(context.colorsEnabled) + arrayOf(FormChannel.FLIP_X, FormChannel.FLIP_Y)),
),
renderStatics(deformer.opacity, deformer.multiplyColor, deformer.screenColor, context.colorsEnabled) +
mapOf(
FormChannel.FLIP_X to ChannelValue.Flag(deformer.flipX),
FormChannel.FLIP_Y to ChannelValue.Flag(deformer.flipY),
),
requireGeometry = true,
)
noticeSink.reportDemotions(ExportEntityCategory.Deformer, deformer.id.raw, keyforms)
if (keyforms == null) {
noticeSink.unsupported(
ExportEntityCategory.Deformer,
deformer.id.raw,
ExportNoticeReason.RotationDeformerHasNoPivot,
)
}
val bundle = keyforms?.bundle
// One form minimum, for the same base-collision reason as the warp branch above. A
// pivot-less rotation has a well-defined fallback the warp does not: the identity
// transform, which is what `pivot == null` already resolves to below.
val cellCount = maxOf(bundle?.cells?.size ?: 0, 1)
// Only the FIRST rotation on each root path carries the px->model factor.
val scaleFactor =
context.rotationScaleFactorFor(deformer)
RotationDeformer(
id = ids.deformerId(deformer.id),
keyformBindingIndex = keyforms?.bindingIndex ?: 0,
isVisible = deformer.isVisible,
isEnabled = deformer.isEnabled,
parentPartIndex = parentPartIndex,
parentDeformerIndex = parentDeformerIndex,
baseAngle = deformer.baseAngle,
keyforms =
(0 until cellCount).map { cellIndex ->
val pivot =
bundle?.cells?.getOrNull(cellIndex)?.geometry
as? RotationPivotForm
val origin =
convertPointsToMoc(
space,
floatArrayOf(pivot?.originX ?: 0f, pivot?.originY ?: 0f),
context.canvas,
)
RotationKeyform(
originX = origin[0],
originY = origin[1],
angle = pivot?.angle ?: 0f,
scale = (pivot?.scale ?: 1f) / (if (scaleFactor != 0f) scaleFactor else 1f),
reflectX =
bundle?.let { flagOf(it, cellIndex, FormChannel.FLIP_X, deformer.flipX) }
?: deformer.flipX,
reflectY =
bundle?.let { flagOf(it, cellIndex, FormChannel.FLIP_Y, deformer.flipY) }
?: deformer.flipY,
opacity =
bundle?.let { scalarOf(it, cellIndex, FormChannel.OPACITY, deformer.opacity) }
?: deformer.opacity,
multiplyColor =
colorOf(bundle, cellIndex, FormChannel.MULTIPLY_COLOR, deformer.multiplyColor, context.colorsEnabled),
screenColor =
colorOf(bundle, cellIndex, FormChannel.SCREEN_COLOR, deformer.screenColor, context.colorsEnabled),
)
},
)
}
}
}
}
@@ -0,0 +1,230 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.CanvasInfo
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.interop.ExportNotice
import org.umamo.interop.ExportReport
import org.umamo.interop.moc3.Moc3ExportOptions
import org.umamo.interop.mocVersion
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PuppetModel
/**
* Lowers a [PuppetModel] into a [MocDocument] - the semantic half of writing a `.moc3` from a rig
* that may never have been one.
*
* This is a FULL SYNTHESIS, deliberately unlike the CMO3 export's state-based reconcile. That
* reconcile exists to preserve unmodeled XML the writer does not understand; a MOC3 has no such
* payload once every section index is modeled, so there is nothing to carry and a reference
* container would only constrain the output. A CMO3-origin or future UMA-origin document
* therefore exports exactly like a MOC3-origin one.
*
* THE LOAD-BEARING INVARIANT, which every geometry path here depends on:
* `drawable.mesh.positions[i] + cell.positionDeltas[i]` is the drawable's ABSOLUTE position in its
* parent-deformer space, for every document origin. `restMeshesToCanvasSpace` rewrites the base
* and compensates the deltas so the sum is untouched, and CMO3 stores the same mixed-space
* convention natively - which is what lets one lowering serve both.
*
* An export ALWAYS writes. Anything it cannot express becomes an [ExportNotice] rather than a
* silent drop, including hidden objects, which by default are CARRIED with their flag clear rather
* than deleted the way the official editor's bake deletes them. [Moc3ExportOptions] is where the
* rigger changes that: its hidden/guide flags feed [resolveExportEligibility], and its scale
* override feeds the [Moc3ExportContext]; the options-less default stays the carrying behavior.
*
* This object is only the orchestrator. The work sits in per-concern producers beside it -
* [resolveExportEligibility] for what gets written at all, then [lowerParameters], [lowerRenderOrder],
* [lowerParts], [lowerDeformers], [lowerArtMeshes], [lowerGlues], [lowerOffscreens], and
* [lowerBlendShapes] - over one immutable [Moc3ExportContext] and three collaborators each producer
* takes explicitly: the [Moc3KeyformPool] it interns bindings into, the [Moc3ExportIds] it claims
* written ids from, and the [Moc3ExportNotices] it reports through. A producer's signature is
* therefore the statement of what it can change.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
object Moc3Export {
/**
* The lowered document plus whatever the lowering could not express.
*
* @property MocDocument document The document to bake.
* @property ExportReport report The advisory findings; empty for a fully-lowered export.
* @property Moc3WrittenIds writtenIds What each object's id was written as, for the sidecars that
* have to name the same objects (see [Moc3WrittenIds]).
*/
class Lowered(
val document: MocDocument,
val report: ExportReport,
val writtenIds: Moc3WrittenIds,
)
/**
* Lowers [puppet] into a [MocDocument] at [version], stripping whatever that version cannot carry.
*
* The strip runs FIRST, on the model (see [Moc3VersionDowngrade]), so every producer works on a rig
* the target version can express completely - and the loss is reported against entities the rigger
* recognizes rather than against section indices.
*
* @param PuppetModel puppet The rig to export.
* @param MocVersion version The moc version to target; the document's own runtime target by default.
* @param CanvasToParentSpace? canvasToParentSpace Inverts the deformer chain for an unkeyed
* drawable; null drops those drawables with a notice instead (see [CanvasToParentSpace]).
* @param Moc3ExportOptions options What the rigger chose to include; the default is the
* options-less behavior.
* @return Lowered The document and its notices.
*/
fun toMocDocument(
puppet: PuppetModel,
version: MocVersion = puppet.runtimeTarget.mocVersion(),
canvasToParentSpace: CanvasToParentSpace? = null,
options: Moc3ExportOptions = Moc3ExportOptions.Default,
): Lowered {
val noticeSink = Moc3ExportNotices()
val downgraded = Moc3VersionDowngrade.strip(puppet, version)
noticeSink.addStripNotices(downgraded.notices)
// Everything below works on the STRIPPED rig, never the parameter. The two are the same object
// whenever the target carries every feature the rig uses, which is every corpus export and every
// re-target upward - so reading the parameter by mistake is invisible on all of them. Naming
// them apart is what makes the mistake say so.
val downgradedPuppet = downgraded.puppet
val eligibility = resolveExportEligibility(downgradedPuppet, canvasToParentSpace, options)
val plan = Moc3IndexPlan.of(downgradedPuppet, eligibility.drawables, eligibility.parts)
val context = Moc3ExportContext(downgradedPuppet, version, eligibility, plan, canvasToParentSpace, options)
val pool = Moc3KeyformPool { parameterId -> plan.parameterIndex(parameterId) }
// Built from the plan, so every id the file will contain is claimed before the first record is
// written and an id too wide for the record can only be shortened INTO a free name.
val ids = Moc3ExportIds(plan, downgradedPuppet.glues, noticeSink)
// Neither of these two interns: a parameter is an axis objects bind TO, and the render-order tree
// addresses objects that already exist.
val parameters = lowerParameters(context, ids)
val renderOrderGroups = lowerRenderOrder(downgradedPuppet, plan)
// The four producers below intern into the shared pool IN THIS ORDER, and that order is the
// file's binding numbering. Reordering them is semantically harmless - the numbering is a
// permutation nothing downstream reads - but it is also the visible symptom of a producer moving
// relative to a data dependency it has, which is not harmless. Moc3ExportBindingOrderTest pins
// it so that second thing cannot happen quietly.
val loweredParts = lowerParts(context, pool, ids, noticeSink)
val parts = loweredParts.records
val deformers = lowerDeformers(context, pool, ids, noticeSink)
val artMeshes = lowerArtMeshes(context, pool, ids, noticeSink)
val glues = lowerGlues(downgradedPuppet, context, pool, ids, noticeSink)
// LAST, so drop notices trail the per-object findings rather than leading them. The eligibility
// pass runs first, but a rigger reads its findings better after the rest.
noticeSink.reportDroppedDrawables(eligibility.droppedDrawables)
val document =
MocDocument(
version = version,
canvas =
CanvasInfo(
pixelsPerUnit = context.pixelsPerUnit,
// MOC3 §5.3 CanvasInfo originX / originY: read off the same mapping every converted
// position went through, so the record and the geometry share one origin.
originX = context.canvas.originX,
originY = context.canvas.originY,
width = downgradedPuppet.canvasWidth,
height = downgradedPuppet.canvasHeight,
),
parameters = parameters,
keyformBindings = pool.bindings().associateBy { binding -> binding.index },
parts = parts,
deformers = deformers,
artMeshes = artMeshes,
glues = glues,
renderOrderGroups = renderOrderGroups,
offscreens =
if (context.offscreensEnabled) {
lowerOffscreens(downgradedPuppet, plan, loweredParts.keyformsByPartId, context.colorsEnabled, noticeSink)
} else {
emptyList()
},
// Blend shapes arrived in Cubism 4.2; a lower target simply carries none.
blendShapes =
if (version.byteValue < 4) {
emptyList()
} else {
lowerBlendShapes(
plan.drawables,
plan.deformers,
plan.parts,
plan.parameters,
plan,
context.canvas,
{ parentId -> context.spaceOfParent(parentId) },
{ rotation -> context.rotationScaleFactorFor(rotation) },
context.colorsEnabled,
)
},
)
return Lowered(document, noticeSink.report(), ids.writtenIds())
}
/**
* Lowers [puppet] and bakes it to `.moc3` bytes.
*
* @param PuppetModel puppet The rig to export.
* @param MocVersion version The moc version to target; the document's own runtime target by default.
* @param CanvasToParentSpace? canvasToParentSpace The unkeyed-drawable space inverse, or null.
* @param Moc3ExportOptions options What the rigger chose to include; the default is the
* options-less behavior.
* @return Pair The bytes and the advisory report.
*/
fun write(
puppet: PuppetModel,
version: MocVersion = puppet.runtimeTarget.mocVersion(),
canvasToParentSpace: CanvasToParentSpace? = null,
options: Moc3ExportOptions = Moc3ExportOptions.Default,
): Pair<ByteArray, ExportReport> {
val lowered = toMocDocument(puppet, version, canvasToParentSpace, options)
return Moc3.write(lowered.document) to lowered.report
}
/**
* The pixels-per-unit a bake of [puppet] should carry.
*
* A moc's canvas scale is a BAKE parameter, not a project property: every corpus `.cmo3` stores
* `CModelInfo.pixelsPerUnit = 1` - a CMO3 works in canvas pixels - while the editor's bake of the
* same project writes a real scale, and the rigger picks it in the export dialog. Its default there
* is the canvas WIDTH, which 21 of the 25 corpus bakes use exactly (the four that do not chose their
* own: 9000 -> 5000, 9000 -> 3077, 4500 -> 3000, 5134 -> 5000).
*
* So a CMO3-origin export defaults to the canvas width, and a MOC3-origin one keeps the scale its
* file already had. Writing the project's literal 1 instead is not a smaller choice - it stores the
* whole rig at PIXEL scale, which every runtime then draws hundreds of times too large. A rigger
* who wants a different bake scale sets [Moc3ExportOptions.pixelsPerUnitOverride]; the export
* dialog seeds its scale field from this function, which is why it is public.
*
* The two cases are told apart by [PuppetModel.pixelsPerUnit] being NULL, never by the value's
* magnitude: 1 is a legitimate bake scale, so a `> 1` test would silently rescale a moc that baked
* at 1 - or at any scale below it - by the canvas width and shrink the rig by that whole factor.
*
* @param PuppetModel puppet The rig being exported.
* @return Float The canvas scale to write.
*/
fun mocPixelsPerUnitFor(puppet: PuppetModel): Float {
puppet.pixelsPerUnit?.let { recorded -> return recorded }
return puppet.canvasWidth.takeIf { width -> width > 0f } ?: 1f
}
}
/**
* Ensures an unkeyed drawable's rest mesh is in its parent deformer's space for the MOC3 write.
*
* An injected seam rather than a call, because the inverse lives in `:render` (a closed-form rotation
* inverse and a damped-Newton warp inverse over the evaluated chain) and `:interop` is its sibling
* over `:runtime`, not its dependent - the same shape as the atlas decode's injected byte reader.
*
* Only reached for a drawable with no keyform grid under a deformer: everything else already stores
* parent-local values. The implementation must invert canvas-space rests and leave already-parent-
* local rests unchanged - see [org.umamo.render.canvasToParentSpaceFor]. Returning null (or a
* differently-sized array) leaves the rest mesh as authored and raises a notice, which is the honest
* outcome when the chain cannot be inverted at all.
*
* @param DrawableId drawable The drawable being written.
* @param FloatArray positions Its interleaved rest positions (canvas or already parent-local).
* @return FloatArray? The interleaved parent-space positions, or null when the chain cannot invert.
*/
typealias CanvasToParentSpace = (drawable: DrawableId, positions: FloatArray) -> FloatArray?
@@ -0,0 +1,79 @@
package org.umamo.interop.moc3.export
import org.umamo.runtime.keyform.FormInterpolator
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.FormChannel
/*
* The channel-set helpers every object lowering shares: which render channels an object's grid should
* bundle at the target version, the static fallbacks behind them, and the narrowing that keeps a
* bundle to exactly those channels.
*/
/**
* The render channels an object's grid should bundle, gated on whether the version carries colors.
*
* @param Boolean colorsEnabled Whether the target version has color tables.
* @return Array<FormChannel> The channels to bundle.
*/
internal fun renderChannels(colorsEnabled: Boolean): Array<FormChannel> =
if (colorsEnabled) {
arrayOf(FormChannel.OPACITY, FormChannel.MULTIPLY_COLOR, FormChannel.SCREEN_COLOR)
} else {
arrayOf(FormChannel.OPACITY)
}
/**
* The static fallbacks for [renderChannels].
*
* Colors are omitted entirely below moc 4 rather than defaulted, so the bundle never manufactures a
* color cell the version has nowhere to store.
*
* @param Float opacity The owner's static opacity.
* @param ColorRgb multiplyColor The owner's static multiply color.
* @param ColorRgb screenColor The owner's static screen color.
* @param Boolean colorsEnabled Whether the target version has color tables.
* @return Map The statics per channel.
*/
internal fun renderStatics(
opacity: Float,
multiplyColor: ColorRgb,
screenColor: ColorRgb,
colorsEnabled: Boolean,
): Map<FormChannel, ChannelValue> =
if (colorsEnabled) {
mapOf(
FormChannel.OPACITY to ChannelValue.Scalar(opacity),
FormChannel.MULTIPLY_COLOR to ChannelValue.Color(multiplyColor),
FormChannel.SCREEN_COLOR to ChannelValue.Color(screenColor),
)
} else {
mapOf(FormChannel.OPACITY to ChannelValue.Scalar(opacity))
}
/** A geometry interpolator for owners that have no geometry at all (parts, glues). */
internal object UnitInterpolator : FormInterpolator<Unit> {
override fun interpolate(lower: Unit, upper: Unit, fraction: Float) = Unit
override fun isExactlyEqual(left: Unit, right: Unit): Boolean = true
}
/**
* This channel set restricted to [channels] - the tracks the owner's moc block can actually store.
*
* A runtime entity may carry tracks a given moc version has no field for (a color track on a v3
* export), and bundling those in would widen the grid with axes nothing reads.
*
* @param FormChannel channels The channels to keep.
* @return ChannelGrids The restricted set.
*/
internal fun ChannelGrids.onlyChannels(
vararg channels: FormChannel,
): ChannelGrids {
val keep = channels.toSet()
return ChannelGrids(
gridsByChannel.filterKeys { channel -> channel in keep },
)
}
@@ -0,0 +1,116 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.interop.moc3.Moc3ExportOptions
import org.umamo.interop.moc3.MocCanvasMapping
import org.umamo.interop.moc3.PointSpace
import org.umamo.interop.moc3.rotationAncestorsById
import org.umamo.interop.moc3.rotationScaleFactor
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
/**
* Everything the export producers derive from a rig before any of them writes a record.
*
* Immutable, and deliberately narrower than the encode side's `MocLoweringContext`: the two things a
* producer MUTATES - the keyform pool it interns bindings into and the notice sink it reports through -
* are passed alongside this rather than held here, so a producer's signature says what it changes.
*
* The rig here is the STRIPPED one. A producer that reached back to the caller's model would read
* features the target version cannot carry, and on every export at a model's own version the two are
* the same object - so nothing would notice.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
internal class Moc3ExportContext(
val puppet: PuppetModel,
val version: MocVersion,
val eligibility: Moc3ExportEligibility,
val plan: Moc3IndexPlan,
val canvasToParentSpace: CanvasToParentSpace?,
options: Moc3ExportOptions = Moc3ExportOptions.Default,
) {
/**
* The bake scale written into the canvas record and used to convert every position.
*
* Resolved HERE, before [canvas] is built, because an override that only patched the canvas
* record afterward would leave every converted position at the old scale - the record and the
* geometry must come from the same number.
*/
val pixelsPerUnit: Float =
options.pixelsPerUnitOverride?.takeIf { override -> override > 0f }
?: Moc3Export.mocPixelsPerUnitFor(puppet)
/**
* The px↔model mapping every geometry conversion goes through, and the origin the canvas record
* writes. MOC3 §5.3 CanvasInfo counts its origin in canvas orientation (y down), so the world
* origin's z (up) is negated back.
*/
val canvas: MocCanvasMapping = MocCanvasMapping(pixelsPerUnit, puppet.worldOriginX, -puppet.worldOriginZ)
/**
* Whether the target version carries the per-object color tables.
*
* Per-object multiply/screen color arrived in Cubism 4.2; below that the tables do not exist and
* every keyform must carry null rather than an identity, or the lowering would synthesize sections
* the version cannot address.
*/
val colorsEnabled: Boolean = version.byteValue >= 4
/**
* Whether the target version carries offscreen records.
*
* Offscreen rendering (an isolated part composited as one layer) arrived in Cubism 5.3, as did the
* extended blend surface. Two names for one number: they are separate features that happen to
* share a version, and a later version bump should be able to move one without the other - which is
* why this and [extendedBlendEnabled] stay separate fields rather than collapsing into one.
*/
val offscreensEnabled: Boolean = version.byteValue >= 6
/** Whether the target version carries the packed extended blend (MOC3 v6 §5.6 s153). */
val extendedBlendEnabled: Boolean = version.byteValue >= 6
/** Per rotation deformer, whether a rotation ancestor already applied the px→model factor. */
private val rotationAncestors: Map<DeformerId, Boolean> = rotationAncestorsById(plan.deformers)
/** Each drawable's owning part, null when unparented. */
val partByDrawable: Map<DrawableId, PartId?> get() = eligibility.partByDrawable
/** The org tree's part→parent link. */
val partParentById: Map<PartId, PartId> get() = eligibility.partParentById
/**
* The space a child of [parentId] stores its positions in.
*
* The export's mirror of the import's `pointSpaceOf`, resolved through the plan so an unknown parent
* normalizes to root exactly as the import normalizes an unresolvable index. Three callers - the
* deformer, art-mesh, and blend-shape lowerings - and they must all resolve identically, which is
* what makes this a context method rather than a local helper in one of them.
*
* @param DeformerId? parentId The owning object's parent deformer.
* @return PointSpace The space to store in.
*/
fun spaceOfParent(parentId: DeformerId?): PointSpace {
val index = plan.deformerIndex(parentId)
return when (plan.deformers.getOrNull(index)) {
is Deformer.Warp -> PointSpace.WarpLattice
is Deformer.Rotation -> PointSpace.RotationLocal
null -> PointSpace.ModelRoot
}
}
/**
* The px→model factor a rotation deformer's pivot scale divides by.
*
* Routed through the context because the deformer lowering and the blend-shape pass both need it
* and must agree; deriving it twice is how the two would drift.
*
* @param Deformer.Rotation rotation The rotation deformer.
* @return Float The scale factor.
*/
fun rotationScaleFactorFor(rotation: Deformer.Rotation): Float =
rotationScaleFactor(rotationAncestors[rotation.id] ?: false, canvas)
}
@@ -0,0 +1,168 @@
package org.umamo.interop.moc3.export
import org.umamo.interop.ExportNoticeReason
import org.umamo.interop.moc3.Moc3ExportOptions
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.partByDrawable
/**
* Which of a rig's objects an export actually writes, and why the rest were left out.
*
* @property List<Drawable> drawables The drawables that survive, in model order.
* @property Set<PartId> parts The part ids that survive.
* @property Map<DrawableId, PartId?> partByDrawable Each drawable's owning part, null when unparented.
* @property Map<PartId, PartId> partParentById The org tree's part→parent link, inverted once.
* @property Map<DrawableId, ExportNoticeReason> droppedDrawables Each omitted drawable and the reason,
* for notices.
*/
internal class Moc3ExportEligibility(
val drawables: List<Drawable>,
val parts: Set<PartId>,
val partByDrawable: Map<DrawableId, PartId?>,
val partParentById: Map<PartId, PartId>,
val droppedDrawables: Map<DrawableId, ExportNoticeReason>,
)
/**
* Decides which objects of [puppet] the export can write.
*
* Runs BEFORE the index plan, because the plan's indices are the file's addressing scheme: a drawable
* dropped after the plan was built would leave every later index - and every mask reference into them -
* naming the wrong object.
*
* Must also run AFTER the version strip, on the stripped rig. No strip currently touches the
* predicates below, so passing the un-stripped rig would be invisible today - which is exactly why the
* order is stated rather than left to be rediscovered.
*
* Structural drops (sketch subtree, no mesh, no parent-space inverse) are decided before the
* option-driven hidden drops, so the mask exemption below can never resurrect a drawable the file
* has no way to write.
*
* @param PuppetModel puppet The rig to export, already stripped to the target version.
* @param CanvasToParentSpace? canvasToParentSpace The unkeyed-drawable space inverse, or null.
* @param Moc3ExportOptions options What the rigger chose to include; the default is the
* options-less behavior (hidden objects carried, guides dropped).
* @return Moc3ExportEligibility The surviving objects and the drop reasons.
*/
internal fun resolveExportEligibility(
puppet: PuppetModel,
canvasToParentSpace: CanvasToParentSpace?,
options: Moc3ExportOptions = Moc3ExportOptions.Default,
): Moc3ExportEligibility {
// A SKETCH part is a guide overlay - a scan or a rough the rigger traces over - and the official
// bake leaves it out of the moc entirely. The whole subtree goes: a guide's drawables are the
// thing that would otherwise render in the runtime, sitting on top of the puppet.
val sketchParts =
if (options.exportGuideImageParts) {
emptySet()
} else {
partSubtree(puppet, puppet.parts.filter { part -> part.isSketch })
}
// A hidden part cascades over its whole subtree, matching the parts panel's eyeball: a visible
// child of a hidden part does not show, so omitting hidden parts omits the child's contents too.
val hiddenParts =
if (options.exportHiddenParts) {
emptySet()
} else {
partSubtree(puppet, puppet.parts.filter { part -> !part.isVisible })
}
val exportableParts =
puppet.parts.mapNotNullTo(LinkedHashSet()) { part ->
part.id.takeIf { it !in sketchParts && it !in hiddenParts }
}
val partByDrawable = puppet.partByDrawable()
// The org tree's part->parent link, inverted ONCE. Both of these are asked per object further
// down, and re-deriving either there turns its pass into a quadratic rescan of the whole tree.
val partParentById = HashMap<PartId, PartId>()
for (part in puppet.parts) {
for (child in part.children) {
if (child is OrgChild.Part) {
partParentById[child.id] = part.id
}
}
}
val dropped = LinkedHashMap<DrawableId, ExportNoticeReason>()
for (drawable in puppet.drawables) {
if (partByDrawable[drawable.id] in sketchParts) {
dropped[drawable.id] = ExportNoticeReason.SketchPartIsNotRuntimeContent
} else if (drawable.mesh == null) {
dropped[drawable.id] = ExportNoticeReason.DrawableHasNoMesh
} else if (drawable.geometryGrid == null && drawable.parentDeformerId != null && canvasToParentSpace == null) {
// With no grid there are no deltas to recover the parent-local form from. A canvas-space
// rest (MOC3 import) needs :render's chain inverse; an already-parent-local rest (UMA /
// CMO3) needs the same seam to confirm and pass through. Without it the drawable is
// dropped rather than written at the wrong scale.
dropped[drawable.id] = ExportNoticeReason.UnkeyedDrawableUnderDeformerHasNoParentGeometry
} else if (partByDrawable[drawable.id] in hiddenParts) {
dropped[drawable.id] = ExportNoticeReason.HiddenPartOmittedByExportOption
} else if (!options.exportHiddenDrawables && !drawable.isVisible) {
dropped[drawable.id] = ExportNoticeReason.HiddenDrawableOmittedByExportOption
}
}
// A hidden mask is routine in a Cubism rig - the mesh exists to clip, not to draw - so dropping
// it for being hidden would unclip everything it masks. A drawable dropped ONLY by the
// hidden-art-mesh option is therefore kept after all when a surviving drawable masks with it,
// written with its flag clear exactly as the options-less export writes it. One pass suffices:
// a mask's own mask list is not consulted by the runtime's mask render, so keeping it creates no
// further need. The exemption deliberately does not extend to hidden-PART drops - those take
// the part record itself, and a written drawable under an unwritten part is a state the index
// plan has no shape for - so there the mask reference is filtered with a notice instead (see
// the mask handling in the art-mesh lowering).
if (dropped.isNotEmpty()) {
val masksOfSurvivors = LinkedHashSet<DrawableId>()
for (drawable in puppet.drawables) {
if (drawable.id !in dropped) {
masksOfSurvivors.addAll(drawable.maskedBy)
}
}
for (maskId in masksOfSurvivors) {
if (dropped[maskId] == ExportNoticeReason.HiddenDrawableOmittedByExportOption) {
dropped.remove(maskId)
}
}
}
return Moc3ExportEligibility(
drawables = puppet.drawables.filter { drawable -> drawable.id !in dropped },
parts = exportableParts,
partByDrawable = partByDrawable,
partParentById = partParentById,
droppedDrawables = dropped,
)
}
/**
* Every part in the subtrees rooted at [roots], roots included.
*
* A guide image or a hidden group is usually one part, but nothing stops a rigger from grouping
* several under it - and a child of a guide is still a guide, a child of a hidden part still
* hidden.
*
* @param PuppetModel puppet The rig.
* @param List<Part> roots The subtree roots to close over.
* @return Set The part ids to omit.
*/
private fun partSubtree(puppet: PuppetModel, roots: List<Part>): Set<PartId> {
if (roots.isEmpty()) {
return emptySet()
}
val partsById = puppet.parts.associateBy { part -> part.id }
val omitted = LinkedHashSet<PartId>()
val pending = ArrayDeque(roots.map { part -> part.id })
while (pending.isNotEmpty()) {
val partId = pending.removeFirst()
if (!omitted.add(partId)) {
continue
}
for (child in partsById[partId]?.children.orEmpty()) {
if (child is OrgChild.Part) {
pending.addLast(child.id)
}
}
}
return omitted
}
@@ -0,0 +1,426 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.moc.Sections
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportNoticeReason
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.Glue
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PartId
/**
* The id each object is written under, one namespace per moc id space.
*
* MOC3 §5.4 makes every id a fixed 64-byte record, so an id whose UTF-8 form does not fit with room
* for the terminator cannot be written - the writer's own precondition rejects one, and an export that
* let that reach the caller would throw straight past the report and out of the file write. CMO3
* places no width limit on these ids, and 22 CJK characters already exceed the record, so shortening
* is a reachable path rather than a theoretical one.
*
* Shortening is also what MINTS DUPLICATES: two names that differ only past the 63rd byte truncate to
* the same string. A MOC3 addresses nothing by id, so the file itself takes the duplicate without
* complaint and the loss surfaces only on the way back, where a re-import merges the two objects into
* one - one mesh's masks, part membership, and keyforms landing on the other. So a shortened id is
* disambiguated here rather than reported and left colliding.
*
* Every id the model can write VERBATIM is claimed up front, at construction, rather than as each
* object is lowered. Otherwise the outcome would depend on lowering order: a shortened id could take
* a name that a later object holds outright, and that object - whose id needed no shortening at all -
* would be the one renamed. Claiming first means shortening can only ever yield ground, never take it.
*
* Drawables are the exception: their moc ids are the sanitized display names (`[A-Za-z0-9_-]`), not
* the Cubism `ArtMeshN` model ids, so VTube Studio and other runtimes that list meshes by id show
* "TopTeeth" rather than "ArtMesh13". Collisions and empty names fall back / disambiguate the same
* way over-long ids do.
*
* Mutable (it accumulates claims), so it is passed to each producer explicitly alongside the keyform
* pool and the notice sink rather than held on the immutable [Moc3ExportContext].
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.4</a>
*/
internal class Moc3ExportIds(
plan: Moc3IndexPlan,
glues: List<Glue>,
noticeSink: Moc3ExportNotices,
) {
// One namespace per id space, because a moc's sections are separate id tables: a part and a
// drawable sharing a name collide nowhere, so disambiguating across the two would rename an object
// for no reason.
private val parameterSpace = Moc3IdSpace(ExportEntityCategory.Parameter, plan.parameters.map { parameter -> parameter.id.raw }, noticeSink)
private val partSpace = Moc3IdSpace(ExportEntityCategory.Part, plan.parts.map { part -> part.id.raw }, noticeSink)
private val deformerSpace = Moc3IdSpace(ExportEntityCategory.Deformer, plan.deformers.map { deformer -> deformer.id.raw }, noticeSink)
// Model id → sanitized display-name id; claimed entirely up front (not via Moc3IdSpace) so the
// preferred names cannot be stolen by a later truncated claim.
private val drawableWrittenByModelId: Map<String, String> = claimDrawableExportIds(plan.drawables, noticeSink)
// A glue with no authored id gets one synthesized at lowering time, so only the authored ones can
// be claimed here. That is enough: a shortened id is at least ID_STRIDE - 4 bytes long (dropping
// one character sheds at most 4 UTF-8 bytes), and the synthesized "Glue_a_b_" form is far shorter
// than that, so the two can never name the same string.
private val glueSpace = Moc3IdSpace(ExportEntityCategory.Glue, glues.mapNotNull { glue -> glue.id }, noticeSink)
/**
* The id a parameter is written under.
*
* @param ParameterId id The parameter's model id.
* @return String The id to write.
*/
fun parameterId(id: ParameterId): String = parameterSpace.writtenId(id.raw)
/**
* The id a part is written under.
*
* @param PartId id The part's model id.
* @return String The id to write.
*/
fun partId(id: PartId): String = partSpace.writtenId(id.raw)
/**
* The id a deformer is written under.
*
* @param DeformerId id The deformer's model id.
* @return String The id to write.
*/
fun deformerId(id: DeformerId): String = deformerSpace.writtenId(id.raw)
/**
* The id a drawable is written under (sanitized display name).
*
* @param DrawableId id The drawable's model id.
* @return String The id to write.
*/
fun drawableId(id: DrawableId): String = drawableWrittenByModelId.getValue(id.raw)
/**
* The id a glue is written under.
*
* Takes a plain [String] because a glue's id is one: nothing references a glue, so the model carries
* no typed id for it, and the caller has already resolved the synthesized fallback for a glue that
* was authored without one.
*
* @param String id The glue's id, authored or synthesized.
* @return String The id to write.
*/
fun glueId(id: String): String = glueSpace.writtenId(id)
/**
* What every object asked about so far was written as, frozen for the sidecars to read.
*
* Called after the lowering, when each producer has asked once per record it wrote - so the result
* covers exactly the objects the file contains. Drawable ids are claimed entirely at construction
* (display-name export), so they are present even before [drawableId] is asked.
*
* @return Moc3WrittenIds The model-id → written-id mapping, by space.
*/
fun writtenIds(): Moc3WrittenIds =
Moc3WrittenIds(
parameters = parameterSpace.writtenIds(),
parts = partSpace.writtenIds(),
deformers = deformerSpace.writtenIds(),
drawables = drawableWrittenByModelId,
)
}
/**
* Claims a unique moc id for every exportable drawable from its display name, sanitized to
* `[A-Za-z0-9_-]`. Empty names fall back to the sanitized model id; collisions append `-2`, `-3`, ….
*
* @param List drawables The exportable drawables in plan order.
* @param Moc3ExportNotices noticeSink Notices when a name must be truncated to the id record.
* @return Map Model drawable id → written moc id.
*/
private fun claimDrawableExportIds(
drawables: List<Drawable>,
noticeSink: Moc3ExportNotices,
): Map<String, String> {
val preferredByModelId =
drawables.associate { drawable ->
drawable.id.raw to sanitizeMocExportId(drawable.name, fallback = drawable.id.raw).ifEmpty { "drawable" }
}
// Pre-claim every unique preferred id that fits, so a later truncated name cannot steal an id
// another drawable holds outright (same rule as [Moc3IdSpace] for model ids).
val preferredCounts = preferredByModelId.values.groupingBy { preferred -> preferred }.eachCount()
val claimed = HashSet<String>()
for (preferred in preferredByModelId.values) {
if (preferredCounts.getValue(preferred) == 1 && fitsIdRecord(preferred)) {
claimed.add(preferred)
}
}
val written = LinkedHashMap<String, String>(drawables.size)
for (drawable in drawables) {
val base = preferredByModelId.getValue(drawable.id.raw)
val truncated = !fitsIdRecord(base)
val exclusiveFit = !truncated && preferredCounts.getValue(base) == 1
if (exclusiveFit) {
written[drawable.id.raw] = base
continue
}
var candidate = if (truncated) fittedToIdRecord(base) else base
if (candidate.isEmpty()) {
candidate = "drawable"
}
var disambiguator = 2
var chosen = candidate
var collided = false
while (!claimed.add(chosen)) {
collided = true
chosen = fittedToIdRecord(base, "-$disambiguator")
disambiguator++
}
if (truncated || collided) {
noticeSink.unsupported(
ExportEntityCategory.Drawable,
drawable.id.raw,
if (collided) {
ExportNoticeReason.IdTruncatedAndDisambiguated(Sections.ID_STRIDE, chosen)
} else {
ExportNoticeReason.IdTruncated(Sections.ID_STRIDE, chosen)
},
)
}
written[drawable.id.raw] = chosen
}
return written
}
/**
* Sanitizes [displayName] into a moc-safe id: ASCII `[A-Za-z0-9_-]` (case preserved). Whitespace
* becomes `_`; other characters are dropped. Runs of `_` collapse; edges strip. When that yields
* nothing, [fallback] is scrubbed the same way; when that is also empty (e.g. a CJK-only Cubism id),
* the raw [fallback] is kept so record-width fitting can still shorten it.
*
* @param String displayName The drawable's display name.
* @param String fallback The model id when the name sanitizes to empty.
* @return String A non-empty id stem (may still need record fitting / disambiguation).
*/
internal fun sanitizeMocExportId(
displayName: String,
fallback: String,
): String {
fun scrub(source: String): String {
val out = StringBuilder(source.length)
var lastWasUnderscore = false
for (ch in source) {
val mapped =
when {
ch in 'a'..'z' || ch in 'A'..'Z' || ch in '0'..'9' || ch == '-' -> ch
ch == '_' || ch.isWhitespace() -> '_'
else -> null
} ?: continue
if (mapped == '_') {
if (!lastWasUnderscore && out.isNotEmpty()) {
out.append('_')
lastWasUnderscore = true
}
} else {
out.append(mapped)
lastWasUnderscore = false
}
}
while (out.isNotEmpty() && out.last() == '_') {
out.deleteAt(out.lastIndex)
}
while (out.isNotEmpty() && out.first() == '_') {
out.deleteAt(0)
}
return out.toString()
}
val fromName = scrub(displayName)
if (fromName.isNotEmpty()) {
return fromName
}
val fromFallback = scrub(fallback)
if (fromFallback.isNotEmpty()) {
return fromFallback
}
return fallback.ifEmpty { "drawable" }
}
/**
* What an export actually wrote each object's id as.
*
* The moc is not the only file in a bake: the `cdi3.json` beside it names parameters, parts, and art
* meshes BY ID to carry their display names, and the runtime joins the two on that string. So a
* sidecar built from the model's own ids silently unpairs itself from the moc for every id the record
* width forced short - the name, the parameter's group placement, and its combined-parameter pairing
* all address an object the moc does not contain under that name. Handing this back with the document
* is what lets the family agree with itself.
*
* An id the export never wrote (a dropped drawable) maps to itself, which is the only honest answer:
* there is no written form to report. Whether an object was written at all is a separate question, and
* one a sidecar has to ask before naming it - see [wrotePart] / [wroteDrawable].
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.4</a>
*/
class Moc3WrittenIds internal constructor(
private val parameters: Map<String, String>,
private val parts: Map<String, String>,
private val deformers: Map<String, String>,
private val drawables: Map<String, String>,
) {
/**
* Whether the moc contains a record for [id].
*
* A part in a sketch subtree is left out of the bake entirely, so a sidecar entry for it names
* nothing the file contains.
*
* @param PartId id The part's model id.
* @return Boolean True when the export wrote it.
*/
fun wrotePart(id: PartId): Boolean = id.raw in parts
/**
* Whether the moc contains a record for [id].
*
* A drawable can be dropped for several reasons (a sketch subtree, a missing mesh, an uninvertible
* deformer chain), and a dropped one holds no claim on its id - so an over-long id can be shortened
* onto exactly that string. A sidecar that named the dropped object anyway would then carry two
* entries under one id, and a join on that string would pick between them arbitrarily.
*
* @param DrawableId id The drawable's model id.
* @return Boolean True when the export wrote it.
*/
fun wroteDrawable(id: DrawableId): Boolean = id.raw in drawables
/**
* The id [id] was written under.
*
* @param ParameterId id The parameter's model id.
* @return String The written id.
*/
fun parameterId(id: ParameterId): String = parameters[id.raw] ?: id.raw
/**
* The id [id] was written under.
*
* @param PartId id The part's model id.
* @return String The written id.
*/
fun partId(id: PartId): String = parts[id.raw] ?: id.raw
/**
* The id [id] was written under.
*
* Carried for completeness rather than for a reader that exists today: a moc names its deformers
* and nothing else does, since cdi3 has no deformer entries.
*
* @param DeformerId id The deformer's model id.
* @return String The written id.
*/
fun deformerId(id: DeformerId): String = deformers[id.raw] ?: id.raw
/**
* The id [id] was written under.
*
* @param DrawableId id The drawable's model id.
* @return String The written id.
*/
fun drawableId(id: DrawableId): String = drawables[id.raw] ?: id.raw
}
/**
* One moc id table: which names are spoken for, and what each model id ended up written as.
*
* @param List<String> modelIds Every id the rig gives this space, claimed if it fits.
* @property ExportEntityCategory category The entity category, for the notices it raises.
* @property Moc3ExportNotices noticeSink Appended to when an id has to be shortened.
*/
private class Moc3IdSpace(
private val category: ExportEntityCategory,
modelIds: List<String>,
private val noticeSink: Moc3ExportNotices,
) {
// Only the ids that FIT are claimed: an over-long one is not written under its own name, so
// reserving it would block a shortened id from a string the file never contains.
private val claimedIds: MutableSet<String> = modelIds.filterTo(HashSet()) { modelId -> fitsIdRecord(modelId) }
// Memoized so an object asked about twice gets one answer and one notice. The deformer lowering
// asks from each of its two type branches, and a second unmemoized call would "collide" the id
// with the claim its own first call made.
private val writtenIdByModelId = HashMap<String, String>()
/**
* The id [modelId] is written under, shortened and disambiguated if it cannot be written as-is.
*
* @param String modelId The id the model carries.
* @return String The id to write.
*/
fun writtenId(modelId: String): String = writtenIdByModelId.getOrPut(modelId) { claim(modelId) }
/**
* A snapshot of what this space has written so far.
*
* @return Map<String, String> Model id → written id.
*/
fun writtenIds(): Map<String, String> = writtenIdByModelId.toMap()
/**
* Resolves and claims the written form of [modelId], reporting whatever had to be cut.
*
* @param String modelId The id the model carries.
* @return String The id to write.
*/
private fun claim(modelId: String): String {
if (fitsIdRecord(modelId)) {
claimedIds.add(modelId)
return modelId
}
val truncated = fittedToIdRecord(modelId)
var written = truncated
var disambiguator = 2
// The suffix has to be part of what gets fitted, not appended after it, or disambiguating would
// push the id back over the record width it was just trimmed to.
while (!claimedIds.add(written)) {
written = fittedToIdRecord(modelId, "-$disambiguator")
disambiguator++
}
noticeSink.unsupported(
category,
modelId,
if (written == truncated) {
ExportNoticeReason.IdTruncated(Sections.ID_STRIDE, written)
} else {
ExportNoticeReason.IdTruncatedAndDisambiguated(Sections.ID_STRIDE, written)
},
)
return written
}
}
/**
* Whether [id] can be written into a moc id record as-is.
*
* @param String id The id to measure.
* @return Boolean True when its UTF-8 form leaves room for the terminator.
*/
private fun fitsIdRecord(id: String): Boolean = id.encodeToByteArray().size < Sections.ID_STRIDE
/**
* The longest leading run of [id] that fits a moc id record with [suffix] appended.
*
* @param String id The id to shorten.
* @param String suffix A disambiguating suffix to keep room for; empty for a plain truncation.
* @return String The shortened id, suffix included.
*/
private fun fittedToIdRecord(
id: String,
suffix: String = "",
): String {
val suffixBytes = suffix.encodeToByteArray().size
// Trimmed by CHARACTER so the result stays valid UTF-8; cutting at a byte offset could land
// mid-sequence and write a broken code point into the record.
var fitted = id
while (fitted.isNotEmpty() && fitted.encodeToByteArray().size + suffixBytes >= Sections.ID_STRIDE) {
fitted = fitted.dropLast(1)
}
// A Kotlin Char is a UTF-16 code unit, so an astral character (emoji, rarer CJK) is TWO of them:
// trimming can leave the leading half behind, which encodes as a replacement byte rather than as
// the character it was part of. Dropping it only shortens the result, so it cannot re-overflow.
if (fitted.isNotEmpty() && fitted.last().isHighSurrogate()) {
fitted = fitted.dropLast(1)
}
return fitted + suffix
}
@@ -0,0 +1,85 @@
package org.umamo.interop.moc3.export
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportFormat
import org.umamo.interop.ExportNotice
import org.umamo.interop.ExportNoticeReason
import org.umamo.interop.ExportReport
import org.umamo.runtime.model.DrawableId
/**
* The advisory findings a lowering accumulates, in the order a rigger will read them.
*
* An export ALWAYS writes; anything it cannot express lands here instead of being silently dropped.
* The order is user-visible - the editor logs the report as a list and shows it in the export panel -
* so the two positional decisions are stated rather than inherited from whatever order the producers
* happen to run in: the version strip's own notices come FIRST (they describe the rig the rest of the
* lowering then worked on), and the dropped-drawable flush comes LAST.
*
* Mutable on purpose, and passed to each producer explicitly rather than hidden inside the export
* context, so a producer's signature says whether it can report.
*/
internal class Moc3ExportNotices {
private val collected = ArrayList<ExportNotice>()
/** Everything reported so far, in report order. */
val notices: List<ExportNotice> get() = collected
/**
* The report to hand back with the document.
*
* @return ExportReport The advisory findings; empty for a fully-lowered export.
*/
fun report(): ExportReport = ExportReport(ExportFormat.Moc3, collected.toList())
/**
* Adopts the version strip's notices, which describe losses taken before any lowering ran.
*
* @param List<ExportNotice> stripNotices The strip's findings.
*/
fun addStripNotices(stripNotices: List<ExportNotice>) {
collected.addAll(stripNotices)
}
/**
* Records a notice for something the lowering could not express.
*
* @param ExportEntityCategory category The entity category.
* @param String subject The entity's id.
* @param ExportNoticeReason reason Why it was not lowered.
*/
fun unsupported(category: ExportEntityCategory, subject: String, reason: ExportNoticeReason) {
collected.add(ExportNotice.UnsupportedChange(category, subject, reason))
}
/**
* Reports every channel a bundle had to drop to its static.
*
* @param ExportEntityCategory category The entity category.
* @param String subject The entity's id.
* @param Moc3ObjectKeyforms? keyforms The lowered keyforms, or null when unrepresentable.
*/
fun reportDemotions(
category: ExportEntityCategory,
subject: String,
keyforms: Moc3ObjectKeyforms?,
) {
for (channel in keyforms?.demotedChannels.orEmpty()) {
unsupported(category, subject, ExportNoticeReason.ChannelDemotedToStatic(channel))
}
}
/**
* Reports every drawable the eligibility pass left out, with the reason it gave.
*
* Called LAST by the orchestrator, so drop notices trail the per-object findings rather than
* leading them - the eligibility pass runs first, but its findings read better after the rest.
*
* @param Map<DrawableId, ExportNoticeReason> droppedDrawables Each omitted drawable and why.
*/
fun reportDroppedDrawables(droppedDrawables: Map<DrawableId, ExportNoticeReason>) {
for ((drawableId, reason) in droppedDrawables) {
unsupported(ExportEntityCategory.Drawable, drawableId.raw, reason)
}
}
}
@@ -0,0 +1,77 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.model.GlueVertexPair
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportNoticeReason
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.PuppetModel
import org.umamo.format.moc3.model.Glue as MocGlue
/**
* Lowers every glue whose two meshes both survived into its MOC3 record.
*
* Interns LAST of the four object kinds, and a glue naming a dropped mesh returns before it would have
* interned - so restructuring the filter to intern first would shift every binding index after it.
*
* @param PuppetModel puppet The stripped rig, for its glue list.
* @param Moc3ExportContext context The export's derived state.
* @param Moc3KeyformPool pool Interned into: every surviving glue claims a binding index here.
* @param Moc3ExportIds ids Claimed from: each surviving glue's written id.
* @param Moc3ExportNotices noticeSink Appended to: demotions and unknown mesh references.
* @return List<MocGlue> The records, in model order.
*/
internal fun lowerGlues(
puppet: PuppetModel,
context: Moc3ExportContext,
pool: Moc3KeyformPool,
ids: Moc3ExportIds,
noticeSink: Moc3ExportNotices,
): List<MocGlue> {
val plan = context.plan
return puppet.glues.mapIndexedNotNull { glueIndex, glue ->
val meshA = plan.drawableIndex(glue.meshA)
val meshB = plan.drawableIndex(glue.meshB)
if (meshA < 0 || meshB < 0) {
noticeSink.unsupported(
ExportEntityCategory.Glue,
glue.id ?: "Glue$glueIndex",
ExportNoticeReason.GlueNamesAnUnknownDrawable,
)
return@mapIndexedNotNull null
}
val keyforms =
lowerObjectKeyforms(
pool,
null as KeyformGrid<Unit>?,
UnitInterpolator,
glue.channelGrids.onlyChannels(FormChannel.GLUE_INTENSITY),
mapOf(FormChannel.GLUE_INTENSITY to ChannelValue.Scalar(glue.intensity)),
requireGeometry = false,
)
// ONE fallback, computed once: a notice naming a subject the file does not contain sends the
// reader searching the export for an object that was never written under that name. The
// drop notice above is the exception on purpose - a dropped glue has no written id to cite,
// so its ordinal is the only handle left.
val glueId = glue.id ?: "Glue_${meshA}_${meshB}_"
noticeSink.reportDemotions(ExportEntityCategory.Glue, glueId, keyforms)
val bundle = keyforms?.bundle
val cellCount = maxOf(bundle?.cells?.size ?: 0, 1)
MocGlue(
id = ids.glueId(glueId),
meshAIndex = meshA,
meshBIndex = meshB,
keyformBindingIndex = keyforms?.bindingIndex ?: 0,
pairs =
glue.pairs.map { pair ->
GlueVertexPair(pair.indexA, pair.indexB, pair.weightA, pair.weightB)
},
intensityKeyforms =
FloatArray(cellCount) { cellIndex ->
bundle?.let { scalarOf(it, cellIndex, FormChannel.GLUE_INTENSITY, glue.intensity) }
?: glue.intensity
},
)
}
}
@@ -0,0 +1,167 @@
package org.umamo.interop.moc3.export
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
/**
* Every ordering and index decision an export makes, resolved ONCE.
*
* A `.moc3` is entirely index-addressed - a drawable names its part and its deformer by list
* position, a deformer names its parent, a render-order child names a drawable. So the file
* order of each object list is not a detail: it is the addressing scheme, and every lowering has
* to agree on it exactly. Resolving it here means a lowering can only ask "what index is this
* id?" and never invent an answer.
*
* Two orderings are load-bearing rather than arbitrary. Parts and deformers are emitted
* PARENT-BEFORE-CHILD because every corpus file is written that way (parent index < own index,
* universally, v1 through v6) and the runtime's own single forward pass over the deformer list
* depends on it - a child seen before its parent would read an unresolved transform.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
class Moc3IndexPlan private constructor(
val parts: List<Part>,
val deformers: List<Deformer>,
val drawables: List<Drawable>,
val parameters: List<Parameter>,
private val partIndexById: Map<PartId, Int>,
private val deformerIndexById: Map<DeformerId, Int>,
private val drawableIndexById: Map<DrawableId, Int>,
private val parameterIndexById: Map<ParameterId, Int>,
) {
/** The file index of [id], or -1 when it names nothing (the moc's own "absent" encoding). */
fun partIndex(id: PartId?): Int = id?.let { partIndexById[it] } ?: -1
/** The file index of [id], or -1 when it names nothing. */
fun deformerIndex(id: DeformerId?): Int = id?.let { deformerIndexById[it] } ?: -1
/** The file index of [id], or -1 when it names nothing. */
fun drawableIndex(id: DrawableId?): Int = id?.let { drawableIndexById[it] } ?: -1
/** The file index of [id], or -1 when it names nothing. */
fun parameterIndex(id: ParameterId?): Int = id?.let { parameterIndexById[it] } ?: -1
companion object {
/**
* Resolves the file order of every object list in [puppet].
*
* @param PuppetModel puppet The rig to export.
* @param List exportableDrawables The drawables that will actually be written.
* @param Set exportableParts The parts that will actually be written.
* @return Moc3IndexPlan The resolved plan.
*/
fun of(
puppet: PuppetModel,
exportableDrawables: List<Drawable> = puppet.drawables,
exportableParts: Set<PartId> = puppet.parts.mapTo(HashSet()) { part -> part.id },
): Moc3IndexPlan {
// Same reason the drawable list is filtered: a part the export omits must not hold an index,
// or every part after it - and every drawable's owning-part reference - names the wrong one.
val orderedParts = partsParentFirst(puppet).filter { part -> part.id in exportableParts }
val orderedDeformers = deformersParentFirst(puppet.deformers)
return Moc3IndexPlan(
parts = orderedParts,
deformers = orderedDeformers,
// Drawables and parameters carry no intra-list dependency, so their runtime order is
// already a valid file order and keeping it makes the export's output stable.
//
// The list is the drawables that will ACTUALLY be written, not every drawable the rig has.
// A MOC3 addresses drawables by position, so if the export drops one - a mesh-less drawable,
// say - and the plan still counted it, every index after it would name the wrong drawable
// and every mask reference would silently shift.
drawables = exportableDrawables,
parameters = puppet.parameters,
partIndexById = orderedParts.withIndex().associate { (index, part) -> part.id to index },
deformerIndexById =
orderedDeformers.withIndex().associate { (index, deformer) -> deformer.id to index },
drawableIndexById =
exportableDrawables.withIndex().associate { (index, drawable) -> drawable.id to index },
parameterIndexById =
puppet.parameters.withIndex().associate { (index, parameter) -> parameter.id to index },
)
}
/**
* The parts in org-tree pre-order, so a parent always precedes its children.
*
* Walks the TREE rather than sorting the flat list, because the tree is the authoritative
* hierarchy - the flat [PuppetModel.parts] is a lookup list whose order carries no meaning. A
* part the tree never reaches (an orphan) is appended so the export cannot silently drop it.
*
* @param PuppetModel puppet The rig.
* @return List<Part> The parts in file order.
*/
private fun partsParentFirst(puppet: PuppetModel): List<Part> {
val partById = puppet.parts.associateBy { part -> part.id }
val ordered = ArrayList<Part>(puppet.parts.size)
val visited = HashSet<PartId>()
fun walk(children: List<OrgChild>) {
for (child in children) {
if (child !is OrgChild.Part) {
continue
}
val part = partById[child.id] ?: continue
// The guard also breaks a malformed cycle rather than recursing forever.
if (!visited.add(part.id)) {
continue
}
ordered.add(part)
walk(part.children)
}
}
walk(puppet.rootChildren)
for (part in puppet.parts) {
if (visited.add(part.id)) {
ordered.add(part)
}
}
return ordered
}
/**
* The deformers ordered so a parent always precedes its children.
*
* A stable depth-first emit rather than a general topological sort: it preserves the input's
* relative order among siblings, which keeps the output stable across runs and keeps a
* round-tripped file close to its source instead of arbitrarily permuted.
*
* @param List deformers The rig's deformers.
* @return List<Deformer> The deformers in file order.
*/
private fun deformersParentFirst(deformers: List<Deformer>): List<Deformer> {
val byId = deformers.associateBy { deformer -> deformer.id }
val childrenByParent = deformers.groupBy { deformer -> deformer.parent }
val ordered = ArrayList<Deformer>(deformers.size)
val visited = HashSet<DeformerId>()
fun walk(deformer: Deformer) {
if (!visited.add(deformer.id)) {
return
}
ordered.add(deformer)
childrenByParent[deformer.id]?.forEach(::walk)
}
// Roots are deformers with no parent, plus any whose parent id does not resolve - an
// unresolvable parent is treated as root exactly as the import treats it.
for (deformer in deformers) {
if (deformer.parent == null || byId[deformer.parent] == null) {
walk(deformer)
}
}
// Anything still unvisited sits in a parent cycle; emit it so nothing is dropped.
for (deformer in deformers) {
walk(deformer)
}
return ordered
}
}
}
@@ -0,0 +1,196 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.model.KeyformBinding
import org.umamo.format.moc3.model.Rgb
import org.umamo.interop.KeyformBundle
import org.umamo.interop.KeyformBundleResult
import org.umamo.interop.OutOfSpanPolicy
import org.umamo.interop.buildKeyformBundle
import org.umamo.runtime.keyform.FormInterpolator
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformGrid
import org.umamo.format.moc3.model.KeyformAxis as MocKeyformAxis
/**
* The keyform-binding pool a `.moc3` addresses every object's forms through, plus the per-object
* bundles that ride it.
*
* The runtime keeps geometry and each channel on their own axes; a MOC3 stores ONE dense grid per
* object and every object points at a shared, deduplicated binding record describing that grid's
* parameter axes. So an export has to re-bundle each object (shared with the CMO3 path - see
* [buildKeyformBundle]) and then intern the resulting axis signature into a pool.
*
* BINDING 0 IS RESERVED for the zero-axis (static) binding and emitted whether or not anything
* references it. That is not tidiness: it is corpus-universal across all 26 samples, and the
* mesh-less `ModelWithOffscreen` family proves the runtime expects the record to exist even when
* only static parts point at it.
*
* The pool's NUMBERING will not match the source file's on a round trip. A MOC3's binding indices
* are the editor's internal creation order - first-reference order over the object lists is
* non-ascending in 9 of 10 non-trivial corpus models - and [org.umamo.runtime.model.PuppetModel]
* deliberately does not carry them, since format indices in the runtime model would invert the
* module graph. The pool is therefore semantically equivalent, not byte-identical, and every
* round-trip gate canonicalizes before comparing.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
class Moc3KeyformPool(private val parameterIndexOf: (org.umamo.runtime.model.ParameterId) -> Int) {
/** Signature → binding index, so two objects on the same axes share one record. */
private val indexBySignature = LinkedHashMap<List<Pair<Int, List<Float>>>, Int>()
private val bindings = ArrayList<KeyformBinding>()
init {
// Reserve index 0 for the static binding before anything else can claim it.
intern(emptyList())
}
/** Every interned binding, in index order - what `MocDocument.keyformBindings` is built from. */
fun bindings(): List<KeyformBinding> = bindings.toList()
/**
* The binding index for [bundle]'s axes, interning it when new.
*
* @param KeyformBundle bundle The re-bundled grid.
* @return Int The pool index.
*/
fun indexOf(bundle: KeyformBundle): Int =
intern(
bundle.axes.map { axis -> parameterIndexOf(axis.parameterId) to axis.keys.toList() },
)
/**
* Interns an axis signature, returning its stable index.
*
* @param List signature Per axis, its parameter index and key positions.
* @return Int The pool index.
*/
private fun intern(signature: List<Pair<Int, List<Float>>>): Int =
indexBySignature.getOrPut(signature) {
val index = bindings.size
bindings.add(
KeyformBinding(
index,
signature.map { (parameterIndex, keys) -> MocKeyformAxis(parameterIndex, keys.toFloatArray()) },
),
)
index
}
}
/**
* One object's lowered keyforms: the binding it points at and its dense cell list.
*
* @property Int bindingIndex The pool index this object's grid uses.
* @property KeyformBundle bundle The bundled grid, whose cells are already in the moc's
* first-axis-fastest order.
*/
class Moc3ObjectKeyforms(
val bindingIndex: Int,
val bundle: KeyformBundle,
) {
/**
* Channels the bundling dropped to their static, which the caller turns into notices.
*
* Delegated rather than copied into a field of its own: two stores of one fact let a later change
* filter the demotions in one place and leave the other reading the unfiltered list, with nothing
* in the type system to catch the divergence.
*/
val demotedChannels: List<FormChannel> get() = bundle.demotedChannels
}
/**
* Re-bundles one object and interns its binding.
*
* MOC3 takes [OutOfSpanPolicy.DemoteChannel] rather than CMO3's reject: every moc object must carry at
* least one keyform, so declining an owner would mean writing nothing for it and producing a file the
* runtime cannot load. Losing one channel's animation is the strictly smaller loss, and the caller
* turns the demotion into a notice so it is never silent.
*
* @param Moc3KeyformPool pool The shared binding pool.
* @param KeyformGrid? geometryGrid The object's geometry grid, or null when it has none.
* @param FormInterpolator geometryBlend The geometry interpolator.
* @param ChannelGrids channels The object's channel tracks.
* @param Map statics Fallback value per channel the object owns.
* @param Boolean requireGeometry Whether a geometry-less object is an error.
* @return Moc3ObjectKeyforms? The lowered keyforms, or null when unrepresentable.
*/
fun <TGeometry> lowerObjectKeyforms(
pool: Moc3KeyformPool,
geometryGrid: KeyformGrid<TGeometry>?,
geometryBlend: FormInterpolator<TGeometry>,
channels: ChannelGrids,
statics: Map<FormChannel, ChannelValue>,
requireGeometry: Boolean,
): Moc3ObjectKeyforms? {
val result =
buildKeyformBundle(
geometryGrid,
geometryBlend,
channels,
statics,
requireGeometry,
OutOfSpanPolicy.DemoteChannel,
)
if (result !is KeyformBundleResult.Bundled) {
return null
}
val bundle = result.bundle
return Moc3ObjectKeyforms(pool.indexOf(bundle), bundle)
}
/**
* The scalar value of [channel] in [cellIndex], falling back to [fallback].
*
* @param KeyformBundle bundle The bundled grid.
* @param Int cellIndex The cell ordinal.
* @param FormChannel channel The channel to read.
* @param Float fallback The value when the channel is absent or not a scalar.
* @return Float The cell's value.
*/
fun scalarOf(bundle: KeyformBundle, cellIndex: Int, channel: FormChannel, fallback: Float): Float =
(bundle.cells.getOrNull(cellIndex)?.channels?.get(channel) as? ChannelValue.Scalar)?.value ?: fallback
/**
* The flag value of [channel] in [cellIndex], falling back to [fallback].
*
* @param KeyformBundle bundle The bundled grid.
* @param Int cellIndex The cell ordinal.
* @param FormChannel channel The channel to read.
* @param Boolean fallback The value when the channel is absent or not a flag.
* @return Boolean The cell's value.
*/
fun flagOf(bundle: KeyformBundle, cellIndex: Int, channel: FormChannel, fallback: Boolean): Boolean =
(bundle.cells.getOrNull(cellIndex)?.channels?.get(channel) as? ChannelValue.Flag)?.flag ?: fallback
/**
* The color of [channel] in [cellIndex] as the format's [Rgb], or null when the target version has no
* color tables.
*
* A null return is meaningful rather than a failure: the lowering writes the color sections only when
* some object carries a color, so a pre-4.2 export must produce nulls throughout or it would
* synthesize tables the version cannot address.
*
* @param KeyformBundle? bundle The bundled grid, or null for an unkeyed owner.
* @param Int cellIndex The cell ordinal.
* @param FormChannel channel The color channel to read.
* @param ColorRgb fallback The owner's static color.
* @param Boolean enabled Whether the target version carries color tables.
* @return Rgb? The cell's color, or null when colors are not written.
*/
fun colorOf(
bundle: KeyformBundle?,
cellIndex: Int,
channel: FormChannel,
fallback: ColorRgb,
enabled: Boolean,
): Rgb? {
if (!enabled) {
return null
}
val value =
(bundle?.cells?.getOrNull(cellIndex)?.channels?.get(channel) as? ChannelValue.Color)?.color ?: fallback
return Rgb(value.red, value.green, value.blue)
}
@@ -0,0 +1,92 @@
package org.umamo.interop.moc3.export
import org.umamo.interop.ExportEntityCategory
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.PartId
import org.umamo.format.moc3.model.Part as MocPart
/**
* The lowered parts, plus the keyform bundles the offscreen lowering has to reuse.
*
* @property List<MocPart> records The part records, in file order.
* @property Map keyformsByPartId Each part's bundle, for the offscreen lowering.
*/
internal class Moc3LoweredParts(
val records: List<MocPart>,
val keyformsByPartId: Map<PartId, Moc3ObjectKeyforms?>,
)
/**
* Lowers every exportable part into a MOC3 part record.
*
* An offscreen's keyforms ride its OWNER PART'S grid - Σ of the owner grid sizes is CountInfo 36 - so
* the part's bundle is built once here and handed back for the offscreen lowering to read. Building it
* twice would let the two disagree about the grid an offscreen is indexed against; RETURNING it rather
* than writing it into shared state is what makes lowering offscreens first a compile error instead of
* a silently empty map.
*
* @param Moc3ExportContext context The export's derived state.
* @param Moc3KeyformPool pool Interned into: every part claims a binding index here.
* @param Moc3ExportIds ids Claimed from: each part's written id.
* @param Moc3ExportNotices noticeSink Appended to: channel demotions.
* @return Moc3LoweredParts The records and their bundles.
*/
internal fun lowerParts(
context: Moc3ExportContext,
pool: Moc3KeyformPool,
ids: Moc3ExportIds,
noticeSink: Moc3ExportNotices,
): Moc3LoweredParts {
val plan = context.plan
val partKeyformsById = HashMap<PartId, Moc3ObjectKeyforms?>()
val records =
plan.parts.map { part ->
// An isolated part's composite channels ride the same cells as its draw order, so they are
// bundled together; a non-isolated part has no composite to key.
val compositeChannels =
if (context.offscreensEnabled && part.isIsolated) {
renderChannels(context.colorsEnabled)
} else {
emptyArray()
}
val compositeStatics =
if (context.offscreensEnabled && part.isIsolated) {
renderStatics(
part.composite.opacity,
part.composite.multiplyColor,
part.composite.screenColor,
context.colorsEnabled,
)
} else {
emptyMap()
}
val keyforms =
lowerObjectKeyforms(
pool,
null as KeyformGrid<Unit>?,
UnitInterpolator,
part.channelGrids.onlyChannels(*(compositeChannels + arrayOf(FormChannel.DRAW_ORDER))),
compositeStatics + mapOf(FormChannel.DRAW_ORDER to ChannelValue.Scalar(part.drawOrder.toFloat())),
requireGeometry = false,
)
noticeSink.reportDemotions(ExportEntityCategory.Part, part.id.raw, keyforms)
partKeyformsById[part.id] = keyforms
val bundle = keyforms?.bundle
val cellCount = bundle?.cells?.size ?: 0
MocPart(
id = ids.partId(part.id),
parentPartIndex = plan.partIndex(context.partParentById[part.id]),
// A static part points at binding 0, which is what the import's `> 0` static test expects.
keyformBindingIndex = if (cellCount > 1) keyforms!!.bindingIndex else 0,
drawOrderKeyforms =
FloatArray(maxOf(cellCount, 1)) { cellIndex ->
bundle?.let { scalarOf(it, cellIndex, FormChannel.DRAW_ORDER, part.drawOrder.toFloat()) }
?: part.drawOrder.toFloat()
},
isVisible = part.isVisible,
)
}
return Moc3LoweredParts(records, partKeyformsById)
}
@@ -0,0 +1,98 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.moc.ConstantFlag
import org.umamo.format.moc3.model.Offscreen
import org.umamo.format.moc3.model.OffscreenKeyform
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportNoticeReason
import org.umamo.interop.exactLegacyBlendFlagOf
import org.umamo.interop.packedBlendOf
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.drawablesByPartSubtree
import org.umamo.runtime.model.flattenedMasks
/**
* Lowers every isolated part into a MOC3 v6 offscreen record.
*
* An offscreen is a part rendered into its own buffer and composited back as one layer, which is what
* gives a part an opacity and a blend mode of its own. The MOC3 models it as a separate object list
* keyed by owner part index rather than as fields on the part, so this walks the parts once and emits a
* record per [org.umamo.runtime.model.PartGroupMode.Isolated] one, in ascending part-index order (the
* corpus-confirmed ordering invariant).
*
* @param PuppetModel puppet The rig being exported.
* @param Moc3IndexPlan plan The file's addressing scheme.
* @param Map keyformsByPartId The part bundles the part lowering already built.
* @param Boolean colorsEnabled Whether the target version has color tables.
* @param Moc3ExportNotices noticeSink Where anything unrepresentable is reported.
* @return List<Offscreen> The records, owner-index ascending.
*/
internal fun lowerOffscreens(
puppet: PuppetModel,
plan: Moc3IndexPlan,
keyformsByPartId: Map<PartId, Moc3ObjectKeyforms?>,
colorsEnabled: Boolean,
noticeSink: Moc3ExportNotices,
): List<Offscreen> {
val isolated = plan.parts.filter { part -> part.isIsolated }
if (isolated.isEmpty()) {
return emptyList()
}
// One index for the whole batch - flattenedMasks' docblock requires it, and a per-composite rebuild
// would walk the whole part tree once per isolated part.
val subtrees = puppet.drawablesByPartSubtree()
return isolated
.map { part ->
val composite = part.composite
// The SHARED mask expansion: resolving part-masks a second way here would let the shipped
// file clip differently from the viewport that authored it.
val maskDrawables = flattenedMasks(composite, subtrees)
val maskIndices =
maskDrawables
.map { drawableId -> plan.drawableIndex(drawableId) }
.filter { index -> index >= 0 }
if (maskIndices.size < maskDrawables.size) {
noticeSink.unsupported(
ExportEntityCategory.Part,
part.id.raw,
ExportNoticeReason.OffscreenMaskNotInExport,
)
}
val bundle = keyformsByPartId[part.id]?.bundle
// Exactly the owner part's grid size: Σ over the owner bindings is CountInfo 36, so a row count
// that disagrees with the part's own keyform count desynchronizes every later offscreen.
val cellCount = maxOf(bundle?.cells?.size ?: 0, 1)
Offscreen(
ownerPartIndex = plan.partIndex(part.id),
// MOC3 v6 §5.6 s156: the drawable flag byte's shape, reused. Bit 2 (double-sided) is set on
// every corpus offscreen - a composited layer is a quad with no back face to cull - and the
// legacy pair restates the mode when, and only when, it can name it exactly, which is the
// opposite of what the same version does for a drawable (there the pair stays clear). Both
// are what the editor writes.
constantFlags =
ConstantFlag.IS_DOUBLE_SIDED or
exactLegacyBlendFlagOf(composite.blendMode) or
(if (composite.invertMask) ConstantFlag.IS_INVERTED_MASK else 0),
// MOC3 v6 §5.6 s157: packed colorMode | (alphaMode shl 8).
blendMode = packedBlendOf(composite.blendMode, composite.alphaBlendMode),
maskCount = maskIndices.size,
keyforms =
List(cellCount) { cellIndex ->
OffscreenKeyform(
opacity =
bundle?.let { scalarOf(it, cellIndex, FormChannel.OPACITY, composite.opacity) }
?: composite.opacity,
multiplyColor =
colorOf(bundle, cellIndex, FormChannel.MULTIPLY_COLOR, composite.multiplyColor, colorsEnabled),
screenColor =
colorOf(bundle, cellIndex, FormChannel.SCREEN_COLOR, composite.screenColor, colorsEnabled),
)
},
maskIndices = maskIndices.toIntArray(),
)
}
.sortedBy { offscreen -> offscreen.ownerPartIndex }
}
@@ -0,0 +1,39 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.moc.ParameterType
import org.umamo.runtime.model.ParameterKind
import org.umamo.format.moc3.moc.MocParameter as MocParameter
/**
* Lowers every parameter in the plan into its MOC3 record.
*
* Takes no keyform pool, which is the point of the signature: a parameter is an axis objects bind TO,
* so this pass cannot intern a binding and the type says so.
*
* @param Moc3ExportContext context The export's derived state.
* @param Moc3ExportIds ids Claimed from: each parameter's written id (over-long ones reported).
* @return List<MocParameter> The records, in plan order.
*/
internal fun lowerParameters(
context: Moc3ExportContext,
ids: Moc3ExportIds,
): List<MocParameter> {
val version = context.version
val plan = context.plan
return plan.parameters.map { parameter ->
MocParameter(
id = ids.parameterId(parameter.id),
minimumValue = parameter.min,
maximumValue = parameter.max,
defaultValue = parameter.default,
// Parameter.Types is moc 4+; below that every parameter is normal and the section is absent.
type =
when {
version.byteValue < 4 -> null
parameter.kind == ParameterKind.BLEND_SHAPE -> ParameterType.BLEND_SHAPE
else -> ParameterType.NORMAL
},
repeats = parameter.repeat,
)
}
}
@@ -0,0 +1,79 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.model.RenderOrderChild
import org.umamo.format.moc3.model.RenderOrderGroup
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RenderDrawable
import org.umamo.runtime.model.RenderGroup
import org.umamo.runtime.model.RenderNode
/**
* Lowers the runtime's render tree into the MOC3's draw-group records.
*
* The shapes already correspond: a MOC3 draw group holds an ordered child list where each child is
* either an art mesh or a nested group tagged with the part that supplies its depth, and
* `RenderGroup` is that same thing. Group 0 is the root by convention, and records are allocated
* in the order the tree is walked so a parent always precedes its children.
*
* The format has one hard rule worth stating: EVERY art mesh must appear exactly once across the
* whole tree. A runtime that finds a drawable referenced twice, or not at all, is documented as
* free to behave erratically - so the guarantee has to arrive with the tree rather than be checked
* here: the render tree the import builds supplies it through its own append-the-missing safety
* net, and this walk preserves that shape, skipping only a child whose drawable or part could not
* be written at all.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
internal fun lowerRenderOrder(puppet: PuppetModel, plan: Moc3IndexPlan): List<RenderOrderGroup> {
val groups = ArrayList<RenderOrderGroup>()
/**
* Allocates a record for [group] and recursively for its sub-groups, returning its index.
*
* The record is reserved BEFORE its children are walked, so a nested group's own index is already
* assigned when its parent's child entry needs to name it.
*
* @param RenderGroup group The subtree root.
* @return Int The allocated record index.
*/
fun allocate(group: RenderGroup): Int {
val recordIndex = groups.size
// Placeholder, replaced below: the slot must exist before the children can reference it.
groups.add(RenderOrderGroup(emptyList()))
val children = ArrayList<RenderOrderChild>(group.children.size)
for (child: RenderNode in group.children) {
when (child) {
is RenderDrawable -> {
val drawableIndex = plan.drawableIndex(child.id)
if (drawableIndex >= 0) {
// MOC3 §5.6 render-order child kind 0: an art-mesh leaf. groupIndex is unused for a leaf.
children.add(RenderOrderChild(kind = 0, index = drawableIndex, groupIndex = 0))
}
}
is RenderGroup -> {
val partIndex = plan.partIndex(child.partId)
// The part check comes BEFORE the record is allocated. Allocating first and then
// declining to reference it leaves a group in the table that no child names - an
// unreachable record still counted by CI_RENDER_ORDER_GROUPS and still consuming a slot
// in the child-start prefix sum.
//
// Skipping the record takes its whole subtree with it, which is only sound because the
// sole reason a part is unwritable is that it is a sketch, and the export drops every
// drawable under a sketch part too. A future rule that drops a part while KEEPING its
// drawables would strand those art meshes outside the render tree, which the format
// says leaves the runtime free to behave erratically.
if (partIndex >= 0) {
val childRecord = allocate(child)
// Kind 1: a "group by draw order" part, whose members live in the named record.
children.add(RenderOrderChild(kind = 1, index = partIndex, groupIndex = childRecord))
}
}
}
}
groups[recordIndex] = RenderOrderGroup(children)
return recordIndex
}
allocate(puppet.renderRoot)
return groups
}
@@ -0,0 +1,384 @@
package org.umamo.interop.moc3.export
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.moc.Section
import org.umamo.interop.ExportNotice
import org.umamo.interop.nearestLegacyBlendMode
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RuntimeFeature
import org.umamo.runtime.model.RuntimeTarget
import org.umamo.runtime.model.multiplyColor
import org.umamo.runtime.model.screenColor
/**
* Removes from a copy of the rig everything the export target's runtime cannot load.
*
* A MOC3 version is a hard capability boundary: a Cubism 3.0 MOC3 has nowhere to put a blend shape, a color
* table, or an offscreen, and the sections that would carry them do not exist in its table. Dropping
* them at the SECTION level is not enough - the CountInfo would still count the keyforms a stripped
* section no longer holds - so the removal happens here, on the [PuppetModel], before any lowering
* runs. The lowering then sees one shape it can express completely.
*
* Reporting is the other half of the reason: a notice raised here names entities the rigger
* recognizes ("Warp40", "ParamAngleX"), while the same loss detected after lowering could only name
* section indices.
*
* What can be carried is asked of the SECTION TABLE, not of [RuntimeTarget.supports]. The two ladders
* are close but not the same, and where they differ the section table is the one that decides what a
* file can hold: [RuntimeTarget] follows the official editor's target dialog, which gates the reversed
* mask at Cubism 4.0 and the parameter repeat at Cubism 5.3 even though both are carried by every MOC3 version back
* to v1. Stripping on the editor's ladder would make a v5 file that uses either one round-trip
* LOSSILY through a v5 export - LimeBirb's repeating parameters are exactly that case in the corpus.
* RuntimeTarget's own docblock anticipates this and says so: edit gating is editor parity, the
* section-level nuances belong to export lowering.
*
* The consequence is that a pre-export confirmation built on
* [org.umamo.runtime.model.unsupportedFeaturesInUse] can name a feature this does not strip. That is
* the conservative direction (it over-warns, never under-warns), and the report returned here is what
* actually happened.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md § Export</a>
*/
object Moc3VersionDowngrade {
/**
* A rig reduced to a target's capabilities, plus what that cost.
*
* @property PuppetModel puppet The stripped copy; the caller's model is untouched.
* @property List notices One [ExportNotice.FeatureStripped] per feature actually removed.
*/
class Stripped(val puppet: PuppetModel, val notices: List<ExportNotice>)
/**
* Strips [puppet] down to what moc [version] can carry.
*
* @param PuppetModel puppet The rig to export.
* @param MocVersion version The moc version being written.
* @return Stripped The reduced rig and its notices; the input model when nothing had to go.
*/
fun strip(puppet: PuppetModel, version: MocVersion): Stripped {
val unsupported = RuntimeFeature.entries.filterNot { feature -> carries(feature, version) }
if (unsupported.isEmpty()) {
return Stripped(puppet, emptyList())
}
val notices = ArrayList<ExportNotice>()
var stripped = puppet
/**
* Records one feature's removal, skipping the notice when nothing carried it.
*
* @param RuntimeFeature feature The feature removed.
* @param List subjects The entities it was removed from.
*/
fun report(feature: RuntimeFeature, subjects: List<String>) {
if (subjects.isNotEmpty()) {
notices.add(ExportNotice.FeatureStripped(feature, subjects))
}
}
for (feature in unsupported) {
stripped =
when (feature) {
RuntimeFeature.WarpQuadTransform -> stripQuadTransform(stripped, ::report)
RuntimeFeature.MeshWarpBlendShapes -> stripMeshWarpBlendShapes(stripped, ::report)
RuntimeFeature.BlendShapeParameters -> stripBlendShapeParameters(stripped, ::report)
RuntimeFeature.MultiplyColor ->
stripColorChannel(stripped, FormChannel.MULTIPLY_COLOR, ColorRgb.MultiplyIdentity, ::report)
RuntimeFeature.ScreenColor ->
stripColorChannel(stripped, FormChannel.SCREEN_COLOR, ColorRgb.ScreenIdentity, ::report)
RuntimeFeature.ExtendedBlendShapes -> stripExtendedBlendShapes(stripped, ::report)
RuntimeFeature.ExtendedBlendModes -> stripExtendedBlendModes(stripped, ::report)
RuntimeFeature.PartComposite -> stripPartComposites(stripped, ::report)
// Carried by EVERY moc version, so `carries` is unconditionally true for both and neither
// ever reaches this loop: the reversed mask is a bit in the constant-flag byte and
// parameter repeat is section 54, and both go back to v1. The arm exists to keep the
// `when` exhaustive, not because there is work to do. If a future version gate ever
// drops one of them, this has to grow a real strip - returning the model unchanged would
// write the feature into a file with nowhere to put it.
RuntimeFeature.ReversedMask, RuntimeFeature.ParameterRepeat -> stripped
// Neither is representable in PuppetModel, so there is nothing here to remove: motion
// sync is a sidecar family and an art path survives only as CMO3 round-trip payload.
RuntimeFeature.MotionSync, RuntimeFeature.ArtPath -> stripped
}
}
return Stripped(stripped, notices)
}
/**
* Whether moc [version] has somewhere to put [feature].
*
* Asked of the [Section] table itself rather than restated as version numbers, so a section whose
* introduction version is corrected in one place cannot leave this saying otherwise - and each
* branch doubles as the citation for why the feature has that floor.
*
* @param RuntimeFeature feature The feature to place.
* @param MocVersion version The version being written.
* @return Boolean True when the version can carry it.
*/
private fun carries(feature: RuntimeFeature, version: MocVersion): Boolean =
when (feature) {
RuntimeFeature.WarpQuadTransform -> Section.WARP_MODE.indexIn(version) >= 0
RuntimeFeature.MeshWarpBlendShapes -> Section.BLENDSHAPE_MESH_OBJECT.indexIn(version) >= 0
RuntimeFeature.BlendShapeParameters -> Section.PARAM_TYPE.indexIn(version) >= 0
RuntimeFeature.MultiplyColor, RuntimeFeature.ScreenColor -> Section.COLOR_MULTIPLY_R.indexIn(version) >= 0
RuntimeFeature.ExtendedBlendShapes -> Section.BLENDSHAPE_ROTATION_OBJECT.indexIn(version) >= 0
RuntimeFeature.ExtendedBlendModes -> Section.ARTMESH_EXTENDED_BLEND.indexIn(version) >= 0
RuntimeFeature.PartComposite -> Section.OFFSCREEN_OWNER_PART.indexIn(version) >= 0
RuntimeFeature.ParameterRepeat -> Section.PARAM_REPEAT.indexIn(version) >= 0
// The reversed mask is a BIT in the drawable/offscreen constant-flag byte, not a section of
// its own, and that byte is in every version - so no moc version has to give it up.
RuntimeFeature.ReversedMask -> true
// Neither is representable in PuppetModel, so no version can fail to carry what is not there.
RuntimeFeature.MotionSync, RuntimeFeature.ArtPath -> true
}
/** The quad-transform flag (Cubism 3.3's warp method) cleared on every warp that set it. */
private fun stripQuadTransform(puppet: PuppetModel, report: Reporter): PuppetModel {
val affected = ArrayList<String>()
val deformers =
puppet.deformers.map { deformer ->
if (deformer is Deformer.Warp && deformer.isQuadTransform) {
affected.add(deformer.name)
deformer.copy(isQuadTransform = false)
} else {
deformer
}
}
report(RuntimeFeature.WarpQuadTransform, affected)
return if (affected.isEmpty()) puppet else puppet.copy(deformers = deformers)
}
/** Every mesh and warp blend-shape binding dropped (moc 4.2 introduced them). */
private fun stripMeshWarpBlendShapes(puppet: PuppetModel, report: Reporter): PuppetModel {
val affected = ArrayList<String>()
val drawables =
puppet.drawables.map { drawable ->
if (drawable.blendShapes.isEmpty()) {
drawable
} else {
affected.add(drawable.name)
drawable.copy(blendShapes = emptyList())
}
}
val deformers =
puppet.deformers.map { deformer ->
if (deformer is Deformer.Warp && deformer.blendShapes.isNotEmpty()) {
affected.add(deformer.name)
deformer.copy(blendShapes = emptyList())
} else {
deformer
}
}
report(RuntimeFeature.MeshWarpBlendShapes, affected)
return if (affected.isEmpty()) puppet else puppet.copy(drawables = drawables, deformers = deformers)
}
/** Rotation- and part-target blend records dropped (moc 5.0 introduced those two targets). */
private fun stripExtendedBlendShapes(puppet: PuppetModel, report: Reporter): PuppetModel {
val affected = ArrayList<String>()
val deformers =
puppet.deformers.map { deformer ->
if (deformer is Deformer.Rotation && deformer.blendShapes.isNotEmpty()) {
affected.add(deformer.name)
deformer.copy(blendShapes = emptyList())
} else {
deformer
}
}
val parts =
puppet.parts.map { part ->
if (part.blendShapes.isEmpty()) {
part
} else {
affected.add(part.name)
part.copy(blendShapes = emptyList())
}
}
report(RuntimeFeature.ExtendedBlendShapes, affected)
return if (affected.isEmpty()) puppet else puppet.copy(deformers = deformers, parts = parts)
}
/** Blend-shape parameters demoted to normal axes; their records are already gone by this point. */
private fun stripBlendShapeParameters(puppet: PuppetModel, report: Reporter): PuppetModel {
val affected = ArrayList<String>()
val parameters =
puppet.parameters.map { parameter: Parameter ->
if (parameter.kind == ParameterKind.BLEND_SHAPE) {
affected.add(parameter.id.raw)
parameter.copy(kind = ParameterKind.NORMAL)
} else {
parameter
}
}
report(RuntimeFeature.BlendShapeParameters, affected)
return if (affected.isEmpty()) puppet else puppet.copy(parameters = parameters)
}
/** One color channel reset to its identity everywhere - statics and tracks alike. */
private fun stripColorChannel(
puppet: PuppetModel,
channel: FormChannel,
identity: ColorRgb,
report: Reporter,
): PuppetModel {
val isMultiply = channel == FormChannel.MULTIPLY_COLOR
val identityValue = ChannelValue.Color(identity)
val affected = ArrayList<String>()
/**
* Whether an owner tints through this channel - a non-identity static or a track.
*
* @param ColorRgb staticColor The owner's static color.
* @param ChannelGrids grids The owner's tracks.
* @return Boolean True when the channel is in use.
*/
fun tints(staticColor: ColorRgb, grids: ChannelGrids): Boolean =
staticColor != identity || grids.varies(channel, identityValue)
val drawables =
puppet.drawables.map { drawable: Drawable ->
val staticColor = if (isMultiply) drawable.multiplyColor else drawable.screenColor
if (!tints(staticColor, drawable.channelGrids)) {
drawable
} else {
affected.add(drawable.name)
drawable
.copy(channelGrids = drawable.channelGrids.without(channel))
.let { if (isMultiply) it.copy(multiplyColor = identity) else it.copy(screenColor = identity) }
}
}
val deformers =
puppet.deformers.map { deformer ->
val staticColor = if (isMultiply) deformer.multiplyColor else deformer.screenColor
if (!tints(staticColor, deformer.channelGrids)) {
deformer
} else {
affected.add(deformer.name)
val grids = deformer.channelGrids.without(channel)
when (deformer) {
is Deformer.Warp ->
if (isMultiply) {
deformer.copy(channelGrids = grids, multiplyColor = identity)
} else {
deformer.copy(channelGrids = grids, screenColor = identity)
}
is Deformer.Rotation ->
if (isMultiply) {
deformer.copy(channelGrids = grids, multiplyColor = identity)
} else {
deformer.copy(channelGrids = grids, screenColor = identity)
}
}
}
}
val parts =
puppet.parts.map { part: Part ->
val composite = part.activeComposite ?: return@map part
val staticColor = if (isMultiply) composite.multiplyColor else composite.screenColor
if (!tints(staticColor, part.channelGrids)) {
part
} else {
affected.add(part.name)
val reset: PartComposite =
if (isMultiply) {
composite.copy(multiplyColor = identity)
} else {
composite.copy(screenColor = identity)
}
part.copy(composite = reset, channelGrids = part.channelGrids.without(channel))
}
}
report(if (isMultiply) RuntimeFeature.MultiplyColor else RuntimeFeature.ScreenColor, affected)
return if (affected.isEmpty()) {
puppet
} else {
puppet.copy(drawables = drawables, deformers = deformers, parts = parts)
}
}
/** The 5.3 blend surface degraded to its nearest pre-5.3 ancestor, alpha back to Over. */
private fun stripExtendedBlendModes(puppet: PuppetModel, report: Reporter): PuppetModel {
val affected = ArrayList<String>()
val drawables =
puppet.drawables.map { drawable ->
if (drawable.blendMode.isLegacy && drawable.alphaBlendMode == AlphaBlendMode.Over) {
drawable
} else {
affected.add(drawable.name)
drawable.copy(
blendMode = nearestLegacyBlendMode(drawable.blendMode),
alphaBlendMode = AlphaBlendMode.Over,
)
}
}
val parts =
puppet.parts.map { part ->
val composite = part.activeComposite ?: return@map part
if (composite.blendMode.isLegacy && composite.alphaBlendMode == AlphaBlendMode.Over) {
part
} else {
affected.add(part.name)
part.copy(
composite =
composite.copy(
blendMode = nearestLegacyBlendMode(composite.blendMode),
alphaBlendMode = AlphaBlendMode.Over,
),
)
}
}
report(RuntimeFeature.ExtendedBlendModes, affected)
return if (affected.isEmpty()) puppet else puppet.copy(drawables = drawables, parts = parts)
}
/**
* Isolated parts demoted to grouped: the subtree keeps its single stacking slot but stops being
* composited as its own layer. The composite settings stay on the part - they are latent by
* design, and this strip runs on an export copy the rigger never sees.
*/
private fun stripPartComposites(puppet: PuppetModel, report: Reporter): PuppetModel {
val affected = ArrayList<String>()
val parts =
puppet.parts.map { part ->
if (part.isIsolated) {
affected.add(part.name)
part.copy(groupMode = PartGroupMode.Grouped)
} else {
part
}
}
report(RuntimeFeature.PartComposite, affected)
return if (affected.isEmpty()) puppet else puppet.copy(parts = parts)
}
}
/** How each strip hands its result back: the feature removed and who it was removed from. */
private typealias Reporter = (RuntimeFeature, List<String>) -> Unit
/**
* This owner's tracks without [channel], sharing [ChannelGrids.Empty] when nothing is left.
*
* @param FormChannel channel The channel to drop.
* @return ChannelGrids The remaining tracks.
*/
private fun ChannelGrids.without(channel: FormChannel): ChannelGrids {
if (this[channel] == null) {
return this
}
val remaining = gridsByChannel - channel
return if (remaining.isEmpty()) ChannelGrids.Empty else ChannelGrids(remaining)
}
@@ -0,0 +1,34 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.MocDocument
import org.umamo.interop.AtlasPageSet
/**
* Collects a MOC3-imported puppet's atlas pages from its sidecar page bytes.
*
* A `.moc3` embeds no pixels: the pages are external PNG files listed in model3.json's
* `FileReferences.Textures` (in order - a drawable's `textureIndex` indexes that list), so the caller
* reads those files and hands their bytes here in the same order. All this adds is the per-drawable
* index; the page list passes straight through.
*
* Unlike a CMO3, a page that will not decode should fail the whole import rather than be dropped - the
* pages are sibling files named by the manifest, so one that will not decode means the family on disk
* is incomplete or mismatched. That is the decoder's policy and the loader states it there.
*
* @param MocDocument mocDocument The decoded moc, whose art meshes carry the per-mesh textureIndex.
* @param List<ByteArray> pageBytes The PNG bytes per manifest texture, in Textures order.
* @return AtlasPageSet The pages + per-drawable index.
*/
public fun moc3AtlasPages(mocDocument: MocDocument, pageBytes: List<ByteArray>): AtlasPageSet =
AtlasPageSet(
pageBytes,
// MOC3: ArtMesh.textureIndex, decoded from section 41 (Section.ARTMESH_TEXTURE) - the mesh's page
// slot, indexing model3's Textures list.
mocDocument.artMeshes.associate { artMesh -> artMesh.id to artMesh.textureIndex },
// Cubism texture files are straight-alpha PNGs (premultiplication is a runtime load option, not a
// property of the files), matching the straight-alpha stream PngCodec yields. The premultiplied-
// vs-straight COMPOSITING distinction (legacy vs 5.3+ blend modes) rides BlendMode.isLegacy, not
// this flag; see PuppetTextures.premultipliedAlpha and docs/format/CMO3.md, "Premultiplied vs
// straight alpha".
premultipliedAlpha = false,
)
@@ -0,0 +1,322 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.model.BlendShapeKeyform
import org.umamo.format.moc3.model.Rgb
import org.umamo.interop.moc3.PointSpace
import org.umamo.runtime.eval.colorAt
import org.umamo.runtime.eval.flagAt
import org.umamo.runtime.eval.meshGridDefaultDeltas
import org.umamo.runtime.eval.rotationFormAt
import org.umamo.runtime.eval.scalarAt
import org.umamo.runtime.eval.warpControlPointsAt
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.BlendWeightLimit
import org.umamo.runtime.model.BlendWeightLimitPoint
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PartForm
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpForm
import org.umamo.format.moc3.model.BlendShape as MocBlendShape
/*
* Blend-shape ingest (MOC3 v4+ §5.6), one builder per target kind.
*
* A moc stores a blend key as a DELTA against the object's pose at the parameter defaults, while the
* runtime stores the referenced value itself. So every builder here does the same two things: sample
* the owner's grid at the default pose to recover that reference, then add each stored row onto it.
* The evaluator subtracts the same reference back out, which is why the reference has to be sampled the
* way it samples it - `BlendShapeChannelOracleTest` and `BlendShapeOracleTest` are what hold the two
* together, since a reference that is wrong by a constant still round-trips through our own export.
*
* Every builder runs on an object that is already CONSTRUCTED, because the object's own keyform grid is
* the reference source.
*/
/**
* Maps [records] onto [drawable] as mesh blend bindings: each stored delta row plus the
* grid-at-default reference (positions, draw order, opacity), converted to runtime space.
*
* @param Moc3ImportContext context The import's derived state.
* @param Drawable drawable The constructed runtime drawable (its grid is the reference source).
* @param PointSpace space The drawable's stored point space.
* @param List<MocBlendShape> records The drawable's records.
* @return List<BlendShapeBinding<MeshForm>> The runtime bindings.
*/
internal fun meshBlendShapesOf(
context: Moc3ImportContext,
drawable: Drawable,
space: PointSpace,
records: List<MocBlendShape>,
): List<BlendShapeBinding<MeshForm>> {
val defaultValue: (ParameterId) -> Float = context::defaultValueOf
val referenceDeltas = meshGridDefaultDeltas(drawable, defaultValue) ?: FloatArray(0)
// The scalar reference is each channel's own value at the DEFAULT pose. An untracked or
// out-of-range channel falls back to the drawable's static, which for an imported drawable is
// Cubism's 500 / full opacity - the same fallback meshBlendState uses, so the evaluator's
// subtraction cancels exactly even for an ungridded drawable.
val referenceDrawOrder =
drawable.channelGrids.scalarAt(FormChannel.DRAW_ORDER, drawable.drawOrder, defaultValue)
val referenceOpacity = drawable.channelGrids.scalarAt(FormChannel.OPACITY, drawable.opacity, defaultValue)
val referenceMultiply =
drawable.channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, drawable.multiplyColor, defaultValue)
val referenceScreen =
drawable.channelGrids.colorAt(FormChannel.SCREEN_COLOR, drawable.screenColor, defaultValue)
return records.mapNotNull { record ->
val payloads =
record.keyforms.map { keyform ->
(keyform as? BlendShapeKeyform.Mesh)?.form ?: return@mapNotNull null
}
if (payloads.size != record.keyPositions.size) {
return@mapNotNull null
}
bindingOfRecord(context, record) { keyIndex ->
MeshForm(
positionDeltas =
addReference(
referenceDeltas,
context.convertDeltas(space, payloads[keyIndex].vertexPositions),
),
drawOrder = referenceDrawOrder + payloads[keyIndex].drawOrder,
opacity = referenceOpacity + payloads[keyIndex].opacity,
// Color delta rows are ADDITIVE like the scalars, so their identity is zero rather
// than Cubism's white multiply / black screen; a record without color tables has no
// row at all and contributes nothing.
multiplyColor = addColorDelta(referenceMultiply, payloads[keyIndex].multiplyColor),
screenColor = addColorDelta(referenceScreen, payloads[keyIndex].screenColor),
)
}
}
}
/**
* Maps [records] onto [warp] as lattice blend bindings: each stored control-point delta row
* plus the lattice's grid-at-default reference, and the same treatment for the deformer's own
* render channels (opacity, multiply / screen color), which CASCADE onto every drawable
* underneath.
*
* @param Moc3ImportContext context The import's derived state.
* @param Deformer.Warp warp The constructed runtime warp (its grid is the reference source).
* @param PointSpace space The warp's stored point space.
* @param List<MocBlendShape> records The warp's records.
* @return List<BlendShapeBinding<WarpForm>> The runtime bindings.
*/
internal fun warpBlendShapesOf(
context: Moc3ImportContext,
warp: Deformer.Warp,
space: PointSpace,
records: List<MocBlendShape>,
): List<BlendShapeBinding<WarpForm>> {
val defaultValue: (ParameterId) -> Float = context::defaultValueOf
val reference = warpControlPointsAt(warp.geometryGrid, defaultValue) ?: FloatArray(0)
val referenceOpacity = warp.channelGrids.scalarAt(FormChannel.OPACITY, warp.opacity, defaultValue)
val referenceMultiply =
warp.channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, warp.multiplyColor, defaultValue)
val referenceScreen = warp.channelGrids.colorAt(FormChannel.SCREEN_COLOR, warp.screenColor, defaultValue)
return records.mapNotNull { record ->
val payloads =
record.keyforms.map { keyform ->
(keyform as? BlendShapeKeyform.Warp)?.form ?: return@mapNotNull null
}
if (payloads.size != record.keyPositions.size) {
return@mapNotNull null
}
bindingOfRecord(context, record) { keyIndex ->
WarpForm(
addReference(reference, context.convertDeltas(space, payloads[keyIndex].controlPoints)),
opacity = referenceOpacity + payloads[keyIndex].opacity,
multiplyColor = addColorDelta(referenceMultiply, payloads[keyIndex].multiplyColor),
screenColor = addColorDelta(referenceScreen, payloads[keyIndex].screenColor),
)
}
}
}
/**
* Maps [records] onto [rotation] as affine blend bindings: origin/angle/scale delta rows plus
* the grid-at-default reference. The scale delta carries the same px→model seam factor as
* the grid keyforms; flips are not blendable, so the FLIP tracks' value at the default pose
* fills the form. The deformer's own opacity/color rows get the same reference treatment as
* the geometry and CASCADE onto every drawable underneath (see `DeformerCascade`).
*
* @param Moc3ImportContext context The import's derived state.
* @param Deformer.Rotation rotation The constructed runtime rotation (reference source).
* @param PointSpace space The rotation's stored point space.
* @param Float scaleFactor The px→model seam factor (1 under a rotation ancestor, else ppu).
* @param List<MocBlendShape> records The rotation's records.
* @return List<BlendShapeBinding<RotationForm>> The runtime bindings.
*/
internal fun rotationBlendShapesOf(
context: Moc3ImportContext,
rotation: Deformer.Rotation,
space: PointSpace,
scaleFactor: Float,
records: List<MocBlendShape>,
): List<BlendShapeBinding<RotationForm>> {
val defaultValue: (ParameterId) -> Float = context::defaultValueOf
// The fallback mirrors rotationBlendDeltas' (identity transform, scale 1) so the
// evaluator's subtraction cancels exactly even for an unkeyed rotation.
val reference =
rotationFormAt(rotation.geometryGrid, defaultValue)
?: RotationPivotForm(0f, 0f, 0f, 1f)
val referenceOpacity = rotation.channelGrids.scalarAt(FormChannel.OPACITY, rotation.opacity, defaultValue)
val referenceMultiply =
rotation.channelGrids.colorAt(FormChannel.MULTIPLY_COLOR, rotation.multiplyColor, defaultValue)
val referenceScreen =
rotation.channelGrids.colorAt(FormChannel.SCREEN_COLOR, rotation.screenColor, defaultValue)
return records.mapNotNull { record ->
val payloads =
record.keyforms.map { keyform ->
(keyform as? BlendShapeKeyform.Rotation)?.form ?: return@mapNotNull null
}
if (payloads.size != record.keyPositions.size) {
return@mapNotNull null
}
bindingOfRecord(context, record) { keyIndex ->
val originDelta =
context.convertDeltas(space, floatArrayOf(payloads[keyIndex].originX, payloads[keyIndex].originY))
RotationForm(
originX = reference.originX + originDelta[0],
originY = reference.originY + originDelta[1],
angle = reference.angle + payloads[keyIndex].angle,
scale = reference.scale + payloads[keyIndex].scale * scaleFactor,
// The reference pivot carries no flips - reflections are FLAG channels on the deformer,
// and a blend shape never varies them (MOC3 stores no flip delta rows). Sampled from
// the FLIP tracks at the default pose: at this point in the import the statics are still
// their constructor defaults (compaction lifts constant flip tracks only at the end),
// so reading rotation.flipX here would be constant false and drop the reflection.
flipX = rotation.channelGrids.flagAt(FormChannel.FLIP_X, rotation.flipX, defaultValue),
flipY = rotation.channelGrids.flagAt(FormChannel.FLIP_Y, rotation.flipY, defaultValue),
opacity = referenceOpacity + payloads[keyIndex].opacity,
multiplyColor = addColorDelta(referenceMultiply, payloads[keyIndex].multiplyColor),
screenColor = addColorDelta(referenceScreen, payloads[keyIndex].screenColor),
)
}
}
}
/**
* Maps [records] onto a part as draw-order blend bindings.
*
* A part's only blendable channel is its draw order, so a record carries a single scalar delta
* per key. It gets the same reference treatment as every other blend payload - the stored delta
* plus the channel's value at the DEFAULT pose - so the evaluator's subtraction cancels exactly.
*
* @param Moc3ImportContext context The import's derived state.
* @param Float staticOrder The part's static draw order.
* @param ChannelGrids channelGrids The part's own keyform tracks (the reference source).
* @param List<MocBlendShape> records The part's records.
* @return List<BlendShapeBinding<PartForm>> The runtime bindings.
*/
internal fun partBlendShapesOf(
context: Moc3ImportContext,
staticOrder: Float,
channelGrids: ChannelGrids,
records: List<MocBlendShape>,
): List<BlendShapeBinding<PartForm>> {
val defaultValue: (ParameterId) -> Float = context::defaultValueOf
val referenceDrawOrder = channelGrids.scalarAt(FormChannel.DRAW_ORDER, staticOrder, defaultValue)
return records.mapNotNull { record ->
val payloads =
record.keyforms.map { keyform ->
(keyform as? BlendShapeKeyform.Part)?.drawOrderDelta ?: return@mapNotNull null
}
if (payloads.size != record.keyPositions.size) {
return@mapNotNull null
}
bindingOfRecord(context, record) { keyIndex ->
PartForm(drawOrder = referenceDrawOrder + payloads[keyIndex])
}
}
}
/**
* Assembles one runtime binding from a record: the moc keys already include the inserted
* neutral, whose form slot imports as null (the stored neutral delta row is all-zero).
*
* @param Moc3ImportContext context The import's derived state, for the parameter id table.
* @param MocBlendShape record The record to map.
* @param Function formAt Builds the synthesized runtime form for a non-neutral key.
* @return BlendShapeBinding<TForm> The runtime binding.
*/
private fun <TForm : Any> bindingOfRecord(
context: Moc3ImportContext,
record: MocBlendShape,
formAt: (keyIndex: Int) -> TForm?,
): BlendShapeBinding<TForm> =
BlendShapeBinding(
parameterId = context.parameterIds.getOrElse(record.parameterIndex) { ParameterId("") },
keys = record.keyPositions.copyOf(),
neutralIndex = record.neutralKeyIndex,
forms =
record.keyPositions.indices.map { keyIndex ->
if (keyIndex == record.neutralKeyIndex) null else formAt(keyIndex)
},
limits = blendLimitsOf(context, record),
)
/**
* Maps a record's limit curves to the runtime's min-combined [BlendWeightLimit] list.
*
* @param Moc3ImportContext context The import's derived state, for the parameter id table.
* @param MocBlendShape record The record whose limits to map.
* @return List<BlendWeightLimit> The runtime limit curves.
*/
private fun blendLimitsOf(
context: Moc3ImportContext,
record: MocBlendShape,
): List<BlendWeightLimit> =
record.limits.map { limit ->
BlendWeightLimit(
parameterId = context.parameterIds.getOrElse(limit.parameterIndex) { ParameterId("") },
points =
limit.keyPositions.indices.map { pointIndex ->
BlendWeightLimitPoint(limit.keyPositions[pointIndex], limit.weights[pointIndex])
},
)
}
/**
* Elementwise sum of [reference] and [deltas] (sized like [deltas]; a size-mismatched
* reference contributes only its overlapping prefix, mirroring the evaluator's guards).
*
* @param FloatArray reference The grid-at-default reference components.
* @param FloatArray deltas The converted delta components.
* @return FloatArray The synthesized absolute/rest-relative components.
*/
private fun addReference(
reference: FloatArray,
deltas: FloatArray,
): FloatArray =
FloatArray(deltas.size) { componentIndex ->
deltas[componentIndex] + (reference.getOrNull(componentIndex) ?: 0f)
}
/**
* Adds a color delta row onto its grid-at-default reference, the color analogue of
* [addReference].
*
* A blend record's color rows are ADDITIVE, so a zero row is the identity and a null row (a
* model whose color tables are absent entirely, pre-4.2) contributes nothing. Not clamped
* here: the evaluator subtracts this same reference back out and clamps only after summing every
* contribution, so clamping now would bias a record whose neighbors pull the other way.
*
* @param ColorRgb reference The channel's value at the default pose.
* @param Rgb? delta The record's stored delta row, or null when the model has no colors.
* @return ColorRgb The referenced color this key blends toward.
*/
private fun addColorDelta(
reference: ColorRgb,
delta: Rgb?,
): ColorRgb =
if (delta == null) {
reference
} else {
ColorRgb(reference.red + delta.r, reference.green + delta.g, reference.blue + delta.b)
}
@@ -0,0 +1,285 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
import org.umamo.interop.moc3.rotationScaleFactor
import org.umamo.runtime.keyform.fanOutRotation
import org.umamo.runtime.keyform.fanOutWarp
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.WarpForm
/**
* Imports every deformer, warps and rotations alike, in file order.
*
* File order is preserved because every cross-reference in a MOC3 - a parent link, an art mesh's owner,
* a blend record's target - is a position in this list, so reordering here would silently repoint all of
* them.
*
* Each deformer's keyform grid is built ONCE as a bundled form and then fanned into its geometry and its
* render tracks, rather than walked twice: the opacity and color tracks CASCADE onto every drawable
* underneath, so a second walk that disagreed with the first about a cell would shift a whole subtree.
*
* @param Moc3ImportContext context The import's derived state.
* @return List<Deformer> The runtime deformers, in file order.
*/
internal fun importDeformers(context: Moc3ImportContext): List<Deformer> {
val mocDocument = context.mocDocument
// A bake stores no deformer display name, so the label is the id - readable, but it says nothing
// about what the deformer moves. Where the answer is unambiguous, the drawable it deforms is
// appended as an anchor: "Warp40 (ArtMesh5)". See [soleDrawableByDeformer] for what counts.
val soleDrawable = soleDrawableByDeformer(mocDocument)
/**
* The display name of the deformer at [deformerIndex]: its id, plus the drawable it deforms
* when exactly one is in reach.
*
* @param Int deformerIndex The deformer's file index.
* @param DeformerId id The deformer's resolved runtime id.
* @return String The display name.
*/
fun deformerNameOf(
deformerIndex: Int,
id: DeformerId,
): String {
val anchorIndex = soleDrawable[deformerIndex] ?: return id.raw
val anchorName = mocDocument.artMeshes.getOrNull(anchorIndex)?.id ?: return id.raw
return "${id.raw} ($anchorName)"
}
return mocDocument.deformers.mapIndexed { deformerIndex, source ->
val id = context.deformerIds[deformerIndex]
val parent = context.deformerIds.getOrNull(source.parentDeformerIndex)
val keyformSpace = context.pointSpaceOf(source.parentDeformerIndex)
val binding = context.bindingOf(source.keyformBindingIndex)
when (source) {
is WarpDeformer -> {
// One bundled grid, then split into lattice geometry and the render tracks that cascade
// down onto every drawable under this deformer.
val fannedWarp =
gridOf(context, binding) { gridIndex ->
source.keyforms.getOrNull(gridIndex)?.let { keyform ->
WarpForm(
context.convertPoints(keyformSpace, keyform.controlPoints),
opacity = keyform.opacity,
multiplyColor = colorRgbOf(keyform.multiplyColor) ?: ColorRgb.MultiplyIdentity,
screenColor = colorRgbOf(keyform.screenColor) ?: ColorRgb.ScreenIdentity,
)
}
}?.fanOutWarp()
val warp =
Deformer.Warp(
id = id,
name = deformerNameOf(deformerIndex, id),
parent = parent,
// MOC3 §5.6 s15: the deformer's own org-tree part; -1 (→ null) at the root.
partId = context.partIds.getOrNull(source.parentPartIndex),
// MOC3 §5.6 s13/s14: the editor's eye toggle and its unpinned partner.
isVisible = source.isVisible,
isEnabled = source.isEnabled,
rows = source.rows,
columns = source.columns,
// MOC3 §5.6 warp mode: 0 = triangle split, non-zero = bilinear (quad).
isQuadTransform = source.mode != 0,
geometryGrid = fannedWarp?.geometry,
channelGrids = fannedWarp?.channels ?: ChannelGrids.Empty,
)
val warpRecords = context.blendRecordsByTarget[BlendShapeTarget.WARP to deformerIndex].orEmpty()
if (warpRecords.isEmpty()) {
warp
} else {
warp.copy(blendShapes = warpBlendShapesOf(context, warp, keyformSpace, warpRecords))
}
}
is RotationDeformer -> {
val scaleFactor = rotationScaleFactor(context.hasRotationAncestor[deformerIndex], context.canvasMapping)
// One bundled grid, then split into the pivot geometry, the render tracks that cascade
// down onto every drawable under this deformer, and the two reflection flags.
val fannedRotation =
gridOf(context, binding) { gridIndex ->
source.keyforms.getOrNull(gridIndex)?.let { keyform ->
val origin =
context.convertPoints(keyformSpace, floatArrayOf(keyform.originX, keyform.originY))
RotationForm(
originX = origin[0],
originY = origin[1],
angle = keyform.angle,
scale = keyform.scale * scaleFactor,
flipX = keyform.reflectX,
flipY = keyform.reflectY,
opacity = keyform.opacity,
multiplyColor = colorRgbOf(keyform.multiplyColor) ?: ColorRgb.MultiplyIdentity,
screenColor = colorRgbOf(keyform.screenColor) ?: ColorRgb.ScreenIdentity,
)
}
}?.fanOutRotation()
val rotation =
Deformer.Rotation(
id = id,
name = deformerNameOf(deformerIndex, id),
parent = parent,
partId = context.partIds.getOrNull(source.parentPartIndex),
isVisible = source.isVisible,
isEnabled = source.isEnabled,
baseAngle = source.baseAngle,
geometryGrid = fannedRotation?.geometry,
channelGrids = fannedRotation?.channels ?: ChannelGrids.Empty,
)
val rotationRecords = context.blendRecordsByTarget[BlendShapeTarget.ROTATION to deformerIndex].orEmpty()
if (rotationRecords.isEmpty()) {
rotation
} else {
rotation.copy(
blendShapes =
rotationBlendShapesOf(
context,
rotation,
keyformSpace,
scaleFactor,
rotationRecords,
),
)
}
}
}
}
}
/**
* Infers each deformer's organizational part from the drawables it deforms. A FALLBACK only: MOC3
* §5.6 s15 carries real deformer→part membership, and this runs solely when that section placed
* nothing at all.
*
* A MOC3 whose s15 is absent or entirely -1 - a stripped or synthesized file, or one that
* genuinely puts every deformer at the root - converts to a flat org tree with an unusable
* parts panel. The two cases are indistinguishable in a bake, and inference is the better
* outcome for both, so this reconstructs the grouping from the one signal that is still
* present: a deformer's drawables almost always live in the deformer's own part. The rule is
* the plurality part of the DIRECTLY deformed drawables, falling back to the whole descendant
* subtree for a deformer that only deforms other deformers.
*
* This is INFERENCE, not recovery. Measured against the corpus twins (each model's
* editor-written CMO3 against its own bake) it reproduced 81-93% of the original placements,
* and a deformer whose drawables span several parts can land in any of them - which is why it
* never overrides s15. A CMO3-origin document never reaches here: it carries the real
* membership on ACParameterControllableSource.parentGuid.
*
* @param List deformers The imported deformers, none of which resolved a part.
* @param List drawables The imported drawables.
* @param Map partByDrawable Each drawable's org-tree part (null at the root).
* @return List The deformers with inferred [Deformer.partId] values.
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6 s15</a>
*/
internal fun inferDeformerParts(
deformers: List<Deformer>,
drawables: List<Drawable>,
partByDrawable: Map<DrawableId, PartId?>,
): List<Deformer> {
val parentById = deformers.associate { deformer -> deformer.id to deformer.parent }
val directParts = HashMap<DeformerId, MutableList<PartId>>()
val subtreeParts = HashMap<DeformerId, MutableList<PartId>>()
for (drawable in drawables) {
val partId = partByDrawable[drawable.id] ?: continue
val ownerId = drawable.parentDeformerId ?: continue
directParts.getOrPut(ownerId) { ArrayList() }.add(partId)
// Walk the deformer chain so an ancestor that deforms no drawable directly still sees the
// parts below it; the visited set guards a malformed cyclic chain.
var ancestorId: DeformerId? = ownerId
val visited = HashSet<DeformerId>()
while (ancestorId != null && visited.add(ancestorId)) {
subtreeParts.getOrPut(ancestorId) { ArrayList() }.add(partId)
ancestorId = parentById[ancestorId]
}
}
/**
* The plurality part id of a candidate list, or null when empty.
*
* @param List? candidates The observed part ids.
* @return PartId? The most frequent id.
*/
fun plurality(candidates: List<PartId>?): PartId? =
candidates?.groupingBy { partId -> partId }?.eachCount()?.maxByOrNull { entry -> entry.value }?.key
return deformers.map { deformer ->
val inferred = plurality(directParts[deformer.id]) ?: plurality(subtreeParts[deformer.id])
if (inferred == null) {
deformer
} else {
when (deformer) {
is Deformer.Warp -> deformer.copy(partId = inferred)
is Deformer.Rotation -> deformer.copy(partId = inferred)
}
}
}
}
/**
* The one drawable each deformer deforms, for the deformers where "the one" is unambiguous.
*
* Used only to label a deformer, whose authored name a bake drops. A deformer's own drawables
* decide it when it has any; otherwise its whole descendant subtree does, so a rotation that
* only drives a warp still names the mesh at the bottom of the chain. Either way the answer is
* a CARDINALITY, not a vote: a deformer over several drawables has no single answer and is left
* out, because drawables - unlike parts - are distinct entities rather than a category several
* of them can agree on, so picking a winner would just be naming the deformer after an arbitrary
* one of its meshes. Being an anchor rather than data, an absent entry costs a label, nothing more.
*
* @param MocDocument mocDocument The decoded document (file indices throughout).
* @return Map Deformer file index → its sole drawable's file index, for the unambiguous ones.
*/
private fun soleDrawableByDeformer(mocDocument: MocDocument): Map<Int, Int> {
val deformerCount = mocDocument.deformers.size
if (deformerCount == 0) {
return emptyMap()
}
val ambiguous = -1
val direct = HashMap<Int, Int>()
val subtree = HashMap<Int, Int>()
/**
* Records [drawableIndex] against [deformerIndex], marking the slot ambiguous on a second hit.
*
* @param HashMap into The tally to record into.
* @param Int deformerIndex The owning deformer's file index.
* @param Int drawableIndex The drawable's file index.
*/
fun record(
into: HashMap<Int, Int>,
deformerIndex: Int,
drawableIndex: Int,
) {
into[deformerIndex] = if (deformerIndex in into) ambiguous else drawableIndex
}
for ((drawableIndex, artMesh) in mocDocument.artMeshes.withIndex()) {
var ancestorIndex = artMesh.parentDeformerIndex
if (ancestorIndex !in 0 until deformerCount) {
continue
}
record(direct, ancestorIndex, drawableIndex)
// Walk to the root so an ancestor that deforms no drawable directly still sees the meshes
// below it; the visited set guards a malformed cyclic chain.
val visited = HashSet<Int>()
while (ancestorIndex in 0 until deformerCount && visited.add(ancestorIndex)) {
record(subtree, ancestorIndex, drawableIndex)
ancestorIndex = mocDocument.deformers[ancestorIndex].parentDeformerIndex
}
}
val resolved = HashMap<Int, Int>(deformerCount)
for (deformerIndex in 0 until deformerCount) {
val drawableIndex = direct[deformerIndex] ?: subtree[deformerIndex] ?: continue
if (drawableIndex != ambiguous) {
resolved[deformerIndex] = drawableIndex
}
}
return resolved
}
@@ -0,0 +1,146 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.moc.ConstantFlag
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.interop.alphaBlendOfPacked
import org.umamo.interop.colorBlendOfPacked
import org.umamo.runtime.keyform.fanOutMesh
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.MeshForm
/**
* Imports every art mesh, in file order.
*
* File order is preserved here and re-sorted into panel order only once the render tree has been read,
* because a MOC3 addresses drawables positionally - masks, glues, and render-order leaves are all file
* indices into this list.
*
* The rest mesh comes from the DEFAULT-POSE cell of the drawable's keyform grid, and every cell then
* re-expresses as a delta against it. Which cell is chosen changes `mesh.positions` and every delta
* while leaving evaluated geometry bit-identical - the multilinear blend is base-independent - so no
* evaluation oracle can see this go wrong. `Moc3Cmo3ParityTest` (rest vertices against the CMO3 twin)
* and the export round trip's MESH_POSITIONS are what actually pin it.
*
* @param Moc3ImportContext context The import's derived state.
* @return List<Drawable> The runtime drawables, in file order.
*/
internal fun importDrawables(context: Moc3ImportContext): List<Drawable> =
context.mocDocument.artMeshes.mapIndexed { drawableIndex, source ->
val space = context.pointSpaceOf(source.parentDeformerIndex)
val binding = context.bindingOf(source.keyformBindingIndex)
// MOC3 keyforms are absolute; the default-pose cell serves as the rest mesh and every cell
// re-expresses as a delta against it (the multilinear blend is base-independent, so evaluated
// geometry is unaffected by the choice).
val basePositions =
source.keyforms.getOrNull(defaultCellIndexOf(context, binding))?.let { keyform ->
context.convertPoints(space, keyform.vertexPositions)
}
val mesh =
basePositions?.let { positions ->
DrawableMesh(
positions = positions,
uvs = source.vertexUvs.copyOf(),
// MOC3 §5.6 INDEX_DATA is u16; widen unsigned so meshes past 32767 vertices survive.
indices = IntArray(source.triangleIndices.size) { indexIndex -> source.triangleIndices[indexIndex].toInt() and 0xFFFF },
)
}
// One bundled grid, then split into per-vertex deltas and the render channels.
val fannedMesh =
gridOf(context, binding) { gridIndex ->
source.keyforms.getOrNull(gridIndex)?.let { keyform ->
MeshForm(
positionDeltas =
deltaVsBase(
basePositions,
context.convertPoints(space, keyform.vertexPositions),
),
drawOrder = keyform.drawOrder,
opacity = keyform.opacity,
// MOC3 color-table rows 108-113: the 5.3 per-art-mesh multiply/screen color; null
// (pre-5.3, no color table) falls back to the tint identities.
multiplyColor = colorRgbOf(keyform.multiplyColor) ?: ColorRgb.MultiplyIdentity,
screenColor = colorRgbOf(keyform.screenColor) ?: ColorRgb.ScreenIdentity,
)
}
}?.fanOutMesh()
val drawable =
Drawable(
// Through the context's table, not from source.id: a file carrying the same id twice
// resolves the repeat to a synthesized id there, and building it here instead would
// re-merge the two - masks, part membership, and keyforms landing on one drawable.
id = context.drawableIdsByFileIndex[drawableIndex],
// The MOC3 itself carries no drawable names; only the cdi3 Meshes extension does, so a
// file the official editor wrote falls back to the format id.
name = context.drawableNameById[source.id] ?: source.id,
parentDeformerId = context.deformerIds.getOrNull(source.parentDeformerIndex),
// MOC3 v6 §5.6 s153: a nonzero packed extended blend overrides the legacy 2-bit
// constant-flags field (which then only carries the old-runtime approximation).
blendMode =
if (source.extendedBlend != 0) {
colorBlendOfPacked(source.extendedBlend)
} else {
blendModeOf(source.constantFlags)
},
alphaBlendMode = alphaBlendOfPacked(source.extendedBlend),
// MOC3 §5.6 MASK_INDEX_DATA: mask sources are drawable file indices.
maskedBy =
source.maskDrawableIndices.toList()
.mapNotNull { maskIndex -> context.drawableIdsByFileIndex.getOrNull(maskIndex) },
invertMask = source.constantFlags and ConstantFlag.IS_INVERTED_MASK != 0,
// MOC3 §5.5: constant-flags bit 2 is IS_DOUBLE_SIDED; culling is its inverse.
culling = source.constantFlags and ConstantFlag.IS_DOUBLE_SIDED == 0,
// MOC3 §5.6 s37: the editor's eye toggle. A bake normally deletes what is hidden, so
// this is true for almost every imported drawable - but a file exported with hidden
// meshes kept carries the flag, and Umamo's own export always does.
isVisible = source.isVisible,
// Lock IS editor-only authoring state the bake drops, so everything imports unlocked.
isSelectable = true,
// MOC3 §5.6 s41: the atlas page this mesh samples, so a detached model can still say.
texturePage = source.textureIndex,
mesh = mesh,
geometryGrid = fannedMesh?.geometry,
channelGrids = fannedMesh?.channels ?: ChannelGrids.Empty,
)
val meshRecords = context.blendRecordsByTarget[BlendShapeTarget.ART_MESH to drawableIndex].orEmpty()
if (meshRecords.isEmpty()) {
drawable
} else {
drawable.copy(blendShapes = meshBlendShapesOf(context, drawable, space, meshRecords))
}
}
/**
* Maps a moc drawable's constant-flag bitmask to the runtime [BlendMode].
*
* @param Int constantFlags The [ConstantFlag] bitmask (MOC3 §5.5).
* @return BlendMode The runtime blend mode (defaults to Normal).
*/
private fun blendModeOf(constantFlags: Int): BlendMode =
when {
constantFlags and ConstantFlag.BLEND_ADDITIVE != 0 -> BlendMode.AdditivePremultiplied
constantFlags and ConstantFlag.BLEND_MULTIPLICATIVE != 0 -> BlendMode.MultiplyPremultiplied
else -> BlendMode.Normal
}
/**
* Per-vertex deltas of [positions] vs [base] (`positions − base`), or a copy of positions when
* there is no size-matching base, so the form is kept absolute rather than dropped (matching
* `Cmo3Import`'s convention).
*
* @param FloatArray? base The rest-mesh positions.
* @param FloatArray positions The keyform's absolute positions.
* @return FloatArray The deltas, or a copy of positions.
*/
private fun deltaVsBase(
base: FloatArray?,
positions: FloatArray,
): FloatArray {
if (base == null || base.size != positions.size) {
return positions.copyOf()
}
return FloatArray(positions.size) { coordIndex -> positions[coordIndex] - base[coordIndex] }
}
@@ -0,0 +1,56 @@
package org.umamo.interop.moc3.import
import org.umamo.runtime.keyform.asChannelTrack
import org.umamo.runtime.keyform.channelGridsOf
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.Glue
import org.umamo.runtime.model.GlueForm
import org.umamo.runtime.model.GluePair
/**
* Imports every glue whose two meshes both resolve.
*
* @param Moc3ImportContext context The import's derived state.
* @return List<Glue> The runtime glues, in file order.
*/
internal fun importGlues(context: Moc3ImportContext): List<Glue> {
val mocDocument = context.mocDocument
return mocDocument.glues.mapNotNull { source ->
val meshA = context.drawableIdsByFileIndex.getOrNull(source.meshAIndex) ?: return@mapNotNull null
val meshB = context.drawableIdsByFileIndex.getOrNull(source.meshBIndex) ?: return@mapNotNull null
// MOC3 §5.6 glue: vertex indices are already mesh-local (no UID indirection, unlike CMO3).
// Pairs whose indices fall outside either mesh are dropped, mirroring Cmo3Import's
// UID-resolution behavior - the glue layout planner indexes vertex arrays directly, so an
// unvalidated index from a malformed moc would throw on the render thread after a
// nominally successful import.
val vertexCountA = mocDocument.artMeshes.getOrNull(source.meshAIndex)?.vertexCount ?: 0
val vertexCountB = mocDocument.artMeshes.getOrNull(source.meshBIndex)?.vertexCount ?: 0
val pairs =
source.pairs.mapNotNull { pair ->
if (pair.vertexA in 0 until vertexCountA && pair.vertexB in 0 until vertexCountB) {
GluePair(pair.vertexA, pair.vertexB, pair.weightA, pair.weightB)
} else {
null
}
}
val intensityTrack =
gridOf(context, context.bindingOf(source.keyformBindingIndex)) { gridIndex ->
GlueForm(
source.intensityKeyforms.getOrElse(gridIndex) {
source.intensityKeyforms.lastOrNull() ?: 1f
},
)
}?.asChannelTrack { form -> ChannelValue.Scalar(form.intensity) }
// A glue with no keyed intensity welds fully, which is the runtime's long-standing fallback.
Glue(
meshA,
meshB,
pairs,
channelGridsOf(FormChannel.GLUE_INTENSITY to intensityTrack),
intensity = 1f,
// MOC3 §5.6 s90: the authored name, so a round trip does not synthesize a new one.
id = source.id.takeIf { it.isNotEmpty() },
)
}
}
@@ -0,0 +1,149 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.json.Cdi3Json
import org.umamo.interop.runtimeTargetOfMocVersion
import org.umamo.runtime.keyform.withChannelsCompacted
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.deriveRenderRoot
import org.umamo.runtime.model.partByDrawable
/**
* Maps a decoded MOC3 document (`:format`) plus its optional cdi3 display info into the concrete
* [PuppetModel] (`:runtime`) - the baked-runtime counterpart of `Cmo3Import`.
*
* MOC3 references everything by index (list position), so the mapping is a single pass over each
* list with index → id tables built up front. Three format gaps shape the result:
*
* - Coordinate space. MOC3 keyform positions are absolute values in the OWNING OBJECT'S PARENT
* SPACE, and every parent space but the root matches the runtime's convention VERBATIM (verified
* value-for-value against the CMO3 corpus twin): normalized lattice (u, v) under a warp parent and
* the pixel-scale local frame under a rotation parent, angles in degrees with the same sign. Only
* the root space differs - the MOC stores model units around CanvasInfo's origin, same Y-down
* orientation - so root-space values map through the affine canvas = origin + ppu·model (see
* [Moc3ImportContext.pointSpaceOf]). The one unit seam: a rotation parented to the root or a warp
* carries the px→model factor in its keyform scale, so those scales multiply by ppu to land in the
* runtime's pixel world; rotation-parented rotations keep their scale verbatim. One caveat: the
* runtime's rest mesh (Drawable.mesh.positions) is canvas-space EDITING geometry in the CMO3
* convention, which a MOC does not store - this import leaves the rest mesh in parent space (exact
* for evaluation, since the base cancels out of the keyform blend), and `:render`'s
* restMeshesToCanvasSpace finishes the job by evaluating the default pose (the document loader
* applies it).
* - Names. The binary stores ids (deformers included, §5.6 s11) but no display names; parameter/part
* names come from cdi3.json when present, and everything else falls back to the format id - the same
* rule `Cmo3Import` uses for an unnamed source. A deformer's authored label is lost for good (the
* bake drops it and cdi3 carries no deformer entries), so its name is the id, plus the drawable it
* deforms when exactly one is in reach: "Warp40 (ArtMesh5)".
* - Blend shapes. MOC3 records store per-key DELTAS relative to the object's grid form at the
* DEFAULT pose (MOC3.md §5.6), while the runtime `BlendShapeBinding` keeps grid-convention
* forms (MeshForm rest-relative; Warp/RotationForm absolute) and the evaluator re-subtracts
* that same grid-at-default reference. The mapping therefore ADDS the reference back when
* synthesizing each form - computed with the shared org.umamo.runtime.eval sampling helpers,
* the exact functions the evaluator later calls, so the round trip cancels to ULP. Delta
* geometry converts like the grid keyforms minus the origin term (a delta in root space scales
* by ppu only; lattice/rotation-local deltas pass through; the rotation-scale ppu seam applies
* to scale deltas too). Neutral form slots import as null (the stored neutral row is all-zero).
* PART-owned records carry only a draw-order delta (a part has no other blendable channel) and
* ingest onto [org.umamo.runtime.model.Part.blendShapes]. Offscreens ingest into
* [org.umamo.runtime.model.PartComposite] per owner part (packed blend int, flags, mask indices)
* - the part's group mode becomes Isolated - with the keyformed opacity/color channels merged
* into the part's `PartForm` grid (they ride the same cells, MOC3 §5.6).
*
* This object is only the orchestrator. The work sits in per-concern producers beside it -
* [importParameters], [importParameterLinks], [importParameterTree], [importDeformers],
* [importDrawables], [importGlues], [importRenderRoot], and [importParts] - over one immutable
* [Moc3ImportContext]. There is no mutable collaborator to pass alongside it, unlike the export's
* keyform pool and notice sink: an import reports nothing and interns nothing, so a producer's whole
* input is the context.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5</a>
*/
object Moc3Import {
/**
* Builds a [PuppetModel] from a decoded [MocDocument] (e.g. from `Moc3.read(bytes)`).
*
* @param MocDocument mocDocument The decoded semantic model.
* @param Cdi3Json? displayInfo The sibling cdi3.json (display names, parameter groups, combined
* parameters), or null to fall back to raw format ids everywhere.
* @param Boolean compactChannels Whether to run the post-import channel compaction (on by default);
* see Cmo3Import.fromModelSource.
* @return PuppetModel The concrete runtime puppet.
*/
fun fromMocDocument(
mocDocument: MocDocument,
displayInfo: Cdi3Json?,
compactChannels: Boolean = true,
): PuppetModel {
val context = Moc3ImportContext(mocDocument, displayInfo)
val parameters = importParameters(context)
val parameterLinks = importParameterLinks(context)
val parameterTree = importParameterTree(context)
val deformers = importDeformers(context)
val drawables = importDrawables(context)
val glues = importGlues(context)
// THE ordering contract of this import. Panel order - the parts panel's stacking - is not stored
// in a moc at all; it is RECONSTRUCTED from the render tree, and both the org tree's child sort
// and the flat drawable order below read that reconstruction. Running the org tree first throws
// nothing: every panel index would simply be absent, which yields a different and entirely
// plausible ordering. Moc3ImportOrderTest is what makes that visible.
val renderRoot = importRenderRoot(context)
val panelIndexByDrawable = panelIndexesFrom(renderRoot)
val importedParts = importParts(context, panelIndexByDrawable)
// The flat drawables list is kept back-to-front (the storage/base order, mirroring Cmo3Import's
// panel-derived ordering); unplaced drawables keep file order at the back.
val orderedDrawables =
drawables.sortedByDescending { drawable -> panelIndexByDrawable[drawable.id] ?: Int.MAX_VALUE }
val model =
PuppetModel(
parameters = parameters,
parts = importedParts.records,
deformers = deformers,
drawables = orderedDrawables,
rootChildren = importedParts.rootChildren,
// MOC3 has no synthetic root part; entities at the root simply carry parentPartIndex -1.
rootPartId = null,
glues = glues,
parameterLinks = parameterLinks,
parameterTree = parameterTree,
// MOC3 §5.3 CanvasInfo: width/height are the canvas size in pixels; the world origin is the
// canvas-space origin with Y negated into world space (same convention as Cmo3Import).
canvasWidth = context.canvas?.width ?: 0f,
canvasHeight = context.canvas?.height ?: 0f,
worldOriginX = context.canvasOriginX,
worldOriginZ = -context.canvasOriginY,
// Retained purely so an export can invert this import's space conversions; the evaluator and
// the renderer never read it. The CANVAS's own value, not the 1f identity that
// Moc3ImportContext.canvasMapping substitutes for a canvas-less model - an export has to be
// able to tell "this moc baked at 1" from "this document never had a bake scale" and pick
// its own default for the second.
pixelsPerUnit = context.canvas?.pixelsPerUnit,
// MOC3 §3 Version Gating: the version byte is a hard fact of the baked file, so the import
// starts at the matching Cubism target rather than NoTarget.
runtimeTarget = runtimeTargetOfMocVersion(mocDocument.version),
)
// Three post-passes, and their order is load-bearing in one place: compaction runs LAST, after the
// render-root fallback, because deriveRenderRoot reads the channel tracks that compaction lifts
// into statics.
//
// Section 15 is authoritative when it places anything. When it places NOTHING - a stripped or
// synthesized MOC3 that omits or zeroes the section, which MocDecoder reads defensively for - the
// org tree would be a flat root, so fall back to inferring membership from the drawables.
val withDeformerParts =
if (deformers.isNotEmpty() && deformers.all { deformer -> deformer.partId == null }) {
model.copy(deformers = inferDeformerParts(deformers, orderedDrawables, model.partByDrawable()))
} else {
model
}
val withRenderRoot =
if (renderRoot != null) {
withDeformerParts.copy(renderRoot = renderRoot)
} else {
withDeformerParts.copy(renderRoot = withDeformerParts.deriveRenderRoot())
}
return if (compactChannels) withRenderRoot.withChannelsCompacted() else withRenderRoot
}
}
@@ -0,0 +1,281 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.json.Cdi3Json
import org.umamo.format.moc3.moc.CanvasInfo
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.format.moc3.model.KeyformBinding
import org.umamo.format.moc3.model.Offscreen
import org.umamo.format.moc3.model.Rgb
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
import org.umamo.interop.moc3.MocCanvasMapping
import org.umamo.interop.moc3.PointSpace
import org.umamo.interop.moc3.convertDeltasToRuntime
import org.umamo.interop.moc3.convertPointsToRuntime
import org.umamo.interop.moc3.rotationAncestorFlags
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PartId
import org.umamo.format.moc3.model.BlendShape as MocBlendShape
/**
* Everything the import producers derive from a document before any of them builds a runtime object.
*
* Immutable, and with no mutable collaborator alongside it - unlike the export, which passes a keyform
* pool and a notice sink beside its context because a producer mutates both. An import reports nothing
* and interns nothing, so a producer's only input is this.
*
* What lives here is what MORE THAN ONE producer needs and what they must not disagree about: the file
* index to runtime id tables that every cross-reference resolves through, the canvas mapping every
* coordinate conversion goes through, and the blend records keyed the way each target kind looks them up.
* Deriving any of it twice is how two producers come to hold different answers.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.6</a>
*/
internal class Moc3ImportContext(
val mocDocument: MocDocument,
val displayInfo: Cdi3Json?,
) {
/**
* The document's canvas record, or null on a canvas-less model.
*
* MOC3 §5.3 CanvasInfo: pixelsPerUnit + origin place stored model space onto the canvas as a plain
* affine, same Y-down orientation: canvasX = originX + ppu·modelX, canvasY = originY + ppu·modelY
* (corpus-verified against the CMO3 twin; the Umamo C++ runtime's Y-up presentation happens at eval
* time, not in the stored tables). A canvas-less model keeps the identity mapping so import still
* succeeds (degenerate, like CMO3's 0×0 default).
*/
val canvas: CanvasInfo? = mocDocument.canvas
/** The canvas origin's x in canvas space. */
val canvasOriginX: Float = canvas?.originX ?: 0f
/** The canvas origin's y in canvas space, before the negation into world space. */
val canvasOriginY: Float = canvas?.originY ?: 0f
/** The px↔model mapping every geometry conversion goes through. */
val canvasMapping: MocCanvasMapping = MocCanvasMapping(canvas?.pixelsPerUnit ?: 1f, canvasOriginX, canvasOriginY)
/** cdi3 parameter id → display label. */
val parameterNameById: Map<String, String> = displayInfo?.parameters?.associate { it.id to it.name } ?: emptyMap()
/** cdi3 part id → display label. */
val partNameById: Map<String, String> = displayInfo?.parts?.associate { it.id to it.name } ?: emptyMap()
/** cdi3 drawable id → display label; the Umamo extension, since a moc alone cannot carry these. */
val drawableNameById: Map<String, String> = displayInfo?.drawables?.associate { it.id to it.name } ?: emptyMap()
/**
* Parameter file index → runtime id, with blank and duplicate slots synthesized.
*
* This and the three tables below are all in FILE order, because every cross-reference in a MOC3 is
* a file-order index - and all four are DE-DUPLICATED, because the runtime addresses by id instead.
* A moc names nothing by id, so nothing in the format stops two records from carrying the same one;
* Umamo's own export can even mint the pair, since an id too wide for the 64-byte record is written
* shortened. Mapping both records onto one runtime id would merge the two objects - one drawable's
* masks, part membership, and keyforms landing on the other - so the first claimant keeps the file's
* id and every later one falls back to a synthesized id.
*/
val parameterIds: List<ParameterId> =
distinctIdsOf(mocDocument.parameters.map { parameter -> parameter.id }, "Parameter").map(::ParameterId)
/** Part file index → runtime id, with blank and duplicate slots synthesized. */
val partIds: List<PartId> =
distinctIdsOf(mocDocument.parts.map { part -> part.id }, "Part").map(::PartId)
/** Drawable file index → runtime id, with blank and duplicate slots synthesized. */
val drawableIdsByFileIndex: List<DrawableId> =
distinctIdsOf(mocDocument.artMeshes.map { artMesh -> artMesh.id }, "ArtMesh").map(::DrawableId)
/**
* Deformer file index → runtime id, with blank and duplicate slots synthesized.
*
* MOC3 §5.6 s11 carries the editor's own identifiers, the same ones the CMO3 side carries, so a
* MOC3-origin export writes back the ids the model was authored with. A blank slot - a hand-built
* document, or a MOC3 written without s11 - is the case this table reaches most often; the other
* three are blank only in a malformed file.
*/
val deformerIds: List<DeformerId> =
distinctIdsOf(mocDocument.deformers.map { deformer -> deformer.id }, "Deformer").map(::DeformerId)
/**
* Per deformer file index, whether a rotation ancestor already applied the px→model factor.
*
* The px→model unit seam; see `Moc3SpaceSeam` for why only the first rotation on a path carries it.
*/
val hasRotationAncestor: BooleanArray =
rotationAncestorFlags(
mocDocument.deformers.size,
{ index -> mocDocument.deformers[index].parentDeformerIndex },
{ index -> mocDocument.deformers[index] is RotationDeformer },
)
/**
* Blend records (MOC3 v4+ §5.6) pre-indexed per target object.
*
* `targetIndex` is a deformer index for WARP/ROTATION (already remapped by the decoder), a drawable
* file index for ART_MESH, and a part file index for PART - which is why the key carries the target
* kind alongside the number.
*/
val blendRecordsByTarget: Map<Pair<BlendShapeTarget, Int>, List<MocBlendShape>> =
mocDocument.blendShapes.groupBy { record -> record.target to record.targetIndex }
// Keyed by the DE-DUPLICATED id, never by the raw file id: on a document carrying the same parameter
// id twice, a raw-keyed map keeps only the last, so the first parameter's blend records would read
// the second's default. Keying by parameterIds makes this lookup and the index-addressed one below
// two views of the same table rather than two answers.
private val defaultValueById: Map<ParameterId, Float> =
parameterIds.withIndex().associate { (parameterIndex, parameterId) ->
parameterId to mocDocument.parameters[parameterIndex].defaultValue
}
/**
* The default value of the parameter at [parameterIndex], as a keyform axis names it.
*
* @param Int parameterIndex The parameter's file index.
* @return Float The default, or 0 when the index names nothing.
*/
fun defaultValueAt(parameterIndex: Int): Float = mocDocument.parameters.getOrNull(parameterIndex)?.defaultValue ?: 0f
/**
* The default value of [parameterId], as a blend record's driving parameter names it.
*
* @param ParameterId parameterId The parameter's runtime id.
* @return Float The default, or 0 when the id names nothing.
*/
fun defaultValueOf(parameterId: ParameterId): Float = defaultValueById[parameterId] ?: 0f
/**
* Offscreen records by their owner part's FILE INDEX.
*
* MOC3 v6 §5.6 s155: each offscreen names its owner part by index, and both the part import and the
* render-order import need to look one up from a part they already hold - so the relation is
* inverted once here rather than scanned per part. Keyed by the index the record itself stores,
* not by the owner's id: two parts carrying the same id would otherwise both read whichever
* offscreen came last, isolating a part the file never isolated.
*/
val offscreenByPartIndex: Map<Int, Offscreen> =
mocDocument.offscreens
.filter { offscreen -> offscreen.ownerPartIndex in mocDocument.parts.indices }
.associateBy { offscreen -> offscreen.ownerPartIndex }
/**
* Resolves the keyform binding for [bindingIndex], or null when the document carries none.
*
* @param Int bindingIndex A `keyformBindingIndex` from a moc object.
* @return KeyformBinding? The binding (a static object resolves to a zero-axis binding).
*/
fun bindingOf(bindingIndex: Int): KeyformBinding? = mocDocument.keyformBinding(bindingIndex)
/**
* The coordinate space a child object of [parentDeformerIndex] stores its positions in. Any
* unresolvable index (negative OR out of range) is root space - the same normalization the id
* mapping applies via deformerIds.getOrNull, so a malformed parent index cannot leave an object
* treated as root-parented but converted as rotation-local.
*
* @param Int parentDeformerIndex The owning object's parent deformer index (-1 at the root).
* @return PointSpace The stored space.
*/
fun pointSpaceOf(parentDeformerIndex: Int): PointSpace =
when (mocDocument.deformers.getOrNull(parentDeformerIndex)) {
is WarpDeformer -> PointSpace.WarpLattice
is RotationDeformer -> PointSpace.RotationLocal
null -> PointSpace.ModelRoot
}
/**
* Converts interleaved x,y [points] from the moc's stored [space] to the runtime's convention
* (CMO3 canvas pixels at the root; parent-local elsewhere). Warp-lattice and rotation-local
* values are stored in the runtime's own convention already (corpus-verified) and pass through
* untouched; only root-space values map through CanvasInfo's affine.
*
* @param PointSpace space The stored space (from [pointSpaceOf]).
* @param FloatArray points Interleaved x,y positions as stored in the moc.
* @return FloatArray The converted positions (always a fresh array).
*/
fun convertPoints(
space: PointSpace,
points: FloatArray,
): FloatArray = convertPointsToRuntime(space, points, canvasMapping)
/**
* Converts interleaved delta components from the moc's stored [space] to the runtime's
* convention. Unlike [convertPoints] the canvas ORIGIN does not apply - it cancels out of a
* difference - so a root-space delta scales by ppu only; the other spaces pass through.
*
* @param PointSpace space The stored space (from [pointSpaceOf]).
* @param FloatArray deltas Interleaved x,y deltas as stored in the moc.
* @return FloatArray The converted deltas (always a fresh array).
*/
fun convertDeltas(
space: PointSpace,
deltas: FloatArray,
): FloatArray = convertDeltasToRuntime(space, deltas, canvasMapping)
}
/**
* Converts a decoded moc3 [Rgb] to the runtime [ColorRgb].
*
* Lives beside the context rather than with any one producer because the deformer, drawable, and part
* imports all read the same two color rows off their keyforms, and a second conversion is how one of
* them would come to disagree about what an absent row means.
*
* @param Rgb? color The decoded color row (MOC3 color tables 108-113), or null when absent.
* @return ColorRgb? The runtime color, or null so the caller can apply its own channel identity.
*/
internal fun colorRgbOf(color: Rgb?): ColorRgb? = color?.let { ColorRgb(it.r, it.g, it.b) }
/**
* Maps one section's file ids onto distinct runtime ids, in file order.
*
* The first record to carry a given id keeps it verbatim; a blank or repeated one falls back to a
* synthesized id. A file id always outranks a synthesized one, even when the synthesizer would have
* wanted it first - every file id is claimed before the walk starts - so what the file says survives
* and only what it leaves ambiguous is invented.
*
* @param List<String> fileIds The section's ids, in file order.
* @param String fallbackPrefix The stem a synthesized id is built from ("Deformer", "Part", …).
* @return List<String> One distinct id per file index.
*/
private fun distinctIdsOf(
fileIds: List<String>,
fallbackPrefix: String,
): List<String> {
val claimedIds = fileIds.filterTo(HashSet()) { fileId -> fileId.isNotEmpty() }
val usedIds = HashSet<String>()
return fileIds.mapIndexed { fileIndex, fileId ->
if (fileId.isNotEmpty() && usedIds.add(fileId)) {
fileId
} else {
synthesizedId(fallbackPrefix, fileIndex, claimedIds)
}
}
}
/**
* Synthesizes an id for a slot the file leaves blank (or duplicates).
*
* The result joins [claimedIds], so it collides neither with an id the file already uses nor with
* another synthesized one.
*
* @param String fallbackPrefix The stem to build from.
* @param Int fileIndex The record's file index.
* @param MutableSet claimedIds Every id already spoken for; the returned id is added to it.
* @return String The synthesized id.
*/
private fun synthesizedId(
fallbackPrefix: String,
fileIndex: Int,
claimedIds: MutableSet<String>,
): String {
var candidate = "$fallbackPrefix$fileIndex"
var disambiguator = 2
while (!claimedIds.add(candidate)) {
candidate = "$fallbackPrefix$fileIndex-$disambiguator"
disambiguator++
}
return candidate
}
@@ -0,0 +1,90 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.model.KeyformBinding
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.ParameterId
import kotlin.math.abs
/*
* The keyform grid seam, shared by every object kind the import builds: deformers, drawables, glues, and
* parts all resolve a binding index into a grid the same way, and a second implementation of the stride
* folding would put two objects on the same axes at different cell coordinates.
*/
/**
* Builds a runtime keyform grid over [binding], one cell per grid index.
*
* A static object (a zero-axis binding) becomes a zero-axis single-cell grid, which the evaluator
* resolves to a single full-weight corner - keeping the baked draw order/opacity that a null grid would
* lose.
*
* @param Moc3ImportContext context The import's derived state, for the parameter id table.
* @param KeyformBinding? binding The object's keyform binding.
* @param Function formAt The typed form payload at a grid index, or null to skip the cell.
* @return KeyformGrid<TForm>? The grid, or null when there is no binding.
*/
internal fun <TForm : Any> gridOf(
context: Moc3ImportContext,
binding: KeyformBinding?,
formAt: (gridIndex: Int) -> TForm?,
): KeyformGrid<TForm>? {
if (binding == null) {
return null
}
// MOC3 §5.6: axes are in stride order (first = fastest varying), matching the runtime grid's
// stride folding, so keyIndices(gridIndex) is the cell coordinate as-is.
val axes =
binding.axes.map { axis ->
KeyformAxis(
parameterId = context.parameterIds.getOrElse(axis.parameterIndex) { ParameterId("") },
keys = axis.keyPositions.copyOf(),
)
}
val cells =
(0 until binding.gridSize).mapNotNull { gridIndex ->
formAt(gridIndex)?.let { form -> KeyformCell(binding.keyIndices(gridIndex), form) }
}
return KeyformGrid(axes, cells)
}
/**
* The grid index of the default-pose cell of [binding]: per axis, the key nearest the driving
* parameter's default value, stride-folded.
*
* This cell's baked values serve as the editor's rest state (rest mesh, static draw order); the
* multilinear blend is base-independent, so the choice never changes evaluated output - which is also
* why no evaluation oracle can see it go wrong.
*
* Resolves the default by parameter INDEX, not by id. [Moc3ImportContext.defaultValueOf] answers the
* same question keyed by id for the blend-shape pass, and on a document carrying one parameter id twice
* the two disagree; an axis names its parameter positionally, so this is the accessor that matches what
* the file said.
*
* @param Moc3ImportContext context The import's derived state, for the parameter defaults.
* @param KeyformBinding? binding The object's keyform binding, or null for a static object.
* @return Int The default-pose grid index (0 when static or axis data is degenerate).
*/
internal fun defaultCellIndexOf(
context: Moc3ImportContext,
binding: KeyformBinding?,
): Int {
if (binding == null) {
return 0
}
var linearIndex = 0
var stride = 1
for (axis in binding.axes) {
val defaultValue = context.defaultValueAt(axis.parameterIndex)
var nearestKey = 0
for (keyIndex in axis.keyPositions.indices) {
if (abs(axis.keyPositions[keyIndex] - defaultValue) < abs(axis.keyPositions[nearestKey] - defaultValue)) {
nearestKey = keyIndex
}
}
linearIndex += nearestKey * stride
stride *= axis.keyCount
}
return linearIndex
}
@@ -0,0 +1,121 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.moc.ParameterType
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.ParameterLink
import org.umamo.runtime.model.ParameterNode
/**
* Imports the parameter axes, in file order.
*
* File order is the addressing every keyform axis and every blend record uses to name its driving
* parameter, so this list is not reordered.
*
* @param Moc3ImportContext context The import's derived state.
* @return List<Parameter> The runtime parameters, in file order.
*/
internal fun importParameters(context: Moc3ImportContext): List<Parameter> =
context.mocDocument.parameters.mapIndexed { parameterIndex, source ->
Parameter(
// Through the context's table, not from source.id: a file carrying the same id twice resolves
// the repeat to a synthesized id there, and building it here instead would re-merge the two.
id = context.parameterIds[parameterIndex],
// cdi3: DisplayParameter.name is the display label; fall back to the id (ParamAngleX).
name = context.parameterNameById[source.id] ?: source.id,
min = source.minimumValue,
max = source.maximumValue,
default = source.defaultValue,
// MOC3 v4+ section 114 Parameter types (null on moc < 4 = all normal).
kind = if (source.type == ParameterType.BLEND_SHAPE) ParameterKind.BLEND_SHAPE else ParameterKind.NORMAL,
// MOC3 §5.5 s54: wrap rather than clamp at the limits.
repeat = source.repeats,
)
}
/**
* Imports the LINKED ("combined") parameter pairs that cdi3 records - the editor's 2D pads.
*
* @param Moc3ImportContext context The import's derived state.
* @return List<ParameterLink> The pairs, empty without cdi3.
*/
internal fun importParameterLinks(context: Moc3ImportContext): List<ParameterLink> {
val knownParameterIds = context.parameterIds.toSet()
// cdi3: CombinedParameters is an array of [horizontal, vertical] id pairs - the editor's LINKED
// parameter pads. Entries that are not a 2-pair or name an unknown parameter are skipped.
return context.displayInfo?.combinedParameters.orEmpty().mapNotNull { pair ->
val horizontalId = pair.getOrNull(0)?.let(::ParameterId) ?: return@mapNotNull null
val verticalId = pair.getOrNull(1)?.let(::ParameterId) ?: return@mapNotNull null
if (pair.size == 2 && horizontalId in knownParameterIds && verticalId in knownParameterIds) {
ParameterLink(horizontalId, verticalId)
} else {
null
}
}
}
/**
* Builds the parameter-panel group tree from cdi3 display info.
*
* cdi3 stores two flat lists (parameters and groups, each naming an owning groupId; "" = root), so
* within each group the leaf parameters come first (cdi3 order) followed by sub-groups (cdi3 order) -
* the original interleaving is not recorded in a baked export. Parameters cdi3 never places (or
* placed under an unknown group) are appended at the root so every axis stays reachable in the panel.
*
* @param Moc3ImportContext context The import's derived state.
* @return List<ParameterNode> The root children (empty when cdi3 is absent).
*/
internal fun importParameterTree(context: Moc3ImportContext): List<ParameterNode> {
val displayInfo = context.displayInfo ?: return emptyList()
val parameterIds = context.parameterIds
val knownParameterIds = parameterIds.toSet()
val groupsByParent = displayInfo.parameterGroups.groupBy { group -> group.groupId }
val groupIds = displayInfo.parameterGroups.mapTo(HashSet()) { group -> group.id }
val parametersByGroup =
displayInfo.parameters
.filter { parameter -> ParameterId(parameter.id) in knownParameterIds }
.groupBy { parameter -> if (parameter.groupId in groupIds) parameter.groupId else "" }
val visited = HashSet<String>()
fun childrenOf(ownerGroupId: String): List<ParameterNode> =
buildList {
for (parameter in parametersByGroup[ownerGroupId].orEmpty()) {
add(ParameterNode.Param(ParameterId(parameter.id)))
}
for (group in groupsByParent[ownerGroupId].orEmpty()) {
if (!visited.add(group.id)) {
continue
}
add(
ParameterNode.Group(
id = ParameterGroupId(group.id),
name = group.name,
// cdi3 records no fold state; open reads better than a wall of collapsed rows.
initiallyOpen = true,
children = childrenOf(group.id),
),
)
}
}
val tree = childrenOf("")
// Safety net: any moc parameter cdi3 never mentions still gets a root leaf, so the panel tree
// covers every axis (the tree replaces the flat list when non-empty).
val placedParameterIds =
buildSet {
fun walk(nodes: List<ParameterNode>) {
for (node in nodes) {
when (node) {
is ParameterNode.Param -> add(node.id)
is ParameterNode.Group -> walk(node.children)
}
}
}
walk(tree)
}
val unplaced = parameterIds.filter { parameterId -> parameterId !in placedParameterIds }
return tree + unplaced.map { parameterId -> ParameterNode.Param(parameterId) }
}
@@ -0,0 +1,328 @@
package org.umamo.interop.moc3.import
import org.umamo.format.moc3.moc.ConstantFlag
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.interop.alphaBlendOfPacked
import org.umamo.interop.colorBlendOfPacked
import org.umamo.runtime.keyform.asChannelTrack
import org.umamo.runtime.keyform.channelGridsOf
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartForm
import org.umamo.runtime.model.PartGroupMode
import org.umamo.format.moc3.model.Part as MocPart
/**
* The runtime parts and the org tree's top level, which are one result because they are one traversal.
*
* @property List<Part> records The runtime parts, in FILE order (the addressing every moc index uses).
* @property List<OrgChild> rootChildren The org tree's top level, in panel order.
*/
internal class Moc3ImportedParts(
val records: List<Part>,
val rootChildren: List<OrgChild>,
)
/**
* Imports the parts list and the org tree's root children.
*
* Runs AFTER [importRenderRoot] and the panel-index reconstruction it feeds, because MOC3 stores parent
* indices but no interleaved panel order: each parent's sub-parts and drawables are sorted by the panel
* index recovered from the render tree, a part taking the minimum over its descendants, with ties
* keeping file order. Handed an empty [panelIndexByDrawable] this still succeeds and simply produces a
* different, plausible ordering - which is why `Moc3ImportOrderTest` pins the sequence rather than
* leaving it to be noticed.
*
* Malformed parent links are normalized so nothing is dropped from the outliner: an out-of-range parent
* index goes to the root, and every member of a parent cycle is re-parented to the root (breaking the
* cycle's edges keeps the forest acyclic and every part reachable).
*
* @param Moc3ImportContext context The import's derived state.
* @param Map panelIndexByDrawable Reconstructed panel index per drawable.
* @return Moc3ImportedParts The parts (file order) and the root children (panel order).
*/
internal fun importParts(
context: Moc3ImportContext,
panelIndexByDrawable: Map<DrawableId, Int>,
): Moc3ImportedParts {
val mocDocument = context.mocDocument
val partIds = context.partIds
val drawableIdsByFileIndex = context.drawableIdsByFileIndex
val partCount = mocDocument.parts.size
val drawOrderGroupPartIndices = drawOrderGroupPartIndices(context)
// Normalize part parents in two steps: an out-of-range index goes to the root, and any part
// whose ancestor chain never reaches the root (a malformed parent CYCLE - every member
// in-range, so the range check alone misses it) is re-parented to the root too. Without this
// the whole cycle cluster is unreachable from childrenOf(-1), and since both the outliner and
// the renderer's visibility gate walk the org tree from the root, its parts AND drawables
// silently vanish. Re-parenting every cycle member breaks all cycle edges, so the resulting
// forest is acyclic and complete.
val rangedParentIndices =
IntArray(partCount) { partIndex ->
val parentIndex = mocDocument.parts[partIndex].parentPartIndex
if (parentIndex in 0 until partCount && parentIndex != partIndex) parentIndex else -1
}
fun reachesRoot(startIndex: Int): Boolean {
var currentIndex = rangedParentIndices[startIndex]
var steps = 0
while (currentIndex != -1) {
if (steps > partCount) {
return false
}
steps++
currentIndex = rangedParentIndices[currentIndex]
}
return true
}
val normalizedParentIndices =
IntArray(partCount) { partIndex ->
if (reachesRoot(partIndex)) rangedParentIndices[partIndex] else -1
}
val childPartIndices = HashMap<Int, MutableList<Int>>()
val childDrawableIndices = HashMap<Int, MutableList<Int>>()
mocDocument.parts.forEachIndexed { partIndex, _ ->
childPartIndices.getOrPut(normalizedParentIndices[partIndex], ::mutableListOf).add(partIndex)
}
mocDocument.artMeshes.forEachIndexed { drawableIndex, artMesh ->
val parentIndex = if (artMesh.parentPartIndex in 0 until partCount) artMesh.parentPartIndex else -1
childDrawableIndices.getOrPut(parentIndex, ::mutableListOf).add(drawableIndex)
}
// A part's panel index is the minimum over its descendants' reconstructed indices, memoized over
// the parent-index tree. The cache is seeded before recursing so a malformed parent cycle
// terminates instead of overflowing the stack.
val partPanelIndexCache = HashMap<Int, Int>()
fun partPanelIndex(partIndex: Int): Int {
partPanelIndexCache[partIndex]?.let { cachedIndex ->
return cachedIndex
}
partPanelIndexCache[partIndex] = Int.MAX_VALUE
var minimumIndex = Int.MAX_VALUE
for (drawableIndex in childDrawableIndices[partIndex].orEmpty()) {
val panelIndex = panelIndexByDrawable[drawableIdsByFileIndex[drawableIndex]] ?: Int.MAX_VALUE
if (panelIndex < minimumIndex) {
minimumIndex = panelIndex
}
}
for (childPartIndex in childPartIndices[partIndex].orEmpty()) {
val panelIndex = partPanelIndex(childPartIndex)
if (panelIndex < minimumIndex) {
minimumIndex = panelIndex
}
}
partPanelIndexCache[partIndex] = minimumIndex
return minimumIndex
}
fun childrenOf(parentIndex: Int): List<OrgChild> {
data class ChildEntry(val child: OrgChild, val panelIndex: Int)
val entries = ArrayList<ChildEntry>()
for (childPartIndex in childPartIndices[parentIndex].orEmpty()) {
entries.add(ChildEntry(OrgChild.Part(partIds[childPartIndex]), partPanelIndex(childPartIndex)))
}
for (drawableIndex in childDrawableIndices[parentIndex].orEmpty()) {
val drawableId = drawableIdsByFileIndex[drawableIndex]
entries.add(
ChildEntry(
OrgChild.Drawable(drawableId),
panelIndexByDrawable[drawableId] ?: Int.MAX_VALUE,
),
)
}
return entries.sortedBy { entry -> entry.panelIndex }.map { entry -> entry.child }
}
val parts =
mocDocument.parts.mapIndexed { partIndex, source ->
// MOC3 (runtime format) only records composite data for offscreen parts, so this is null for
// the rest; the composite is stored latently and applied only while the part is Isolated.
val offscreenComposite = partCompositeOf(context, source, partIndex)
val partChannels = partChannelsOf(context, source, partIndex)
Part(
id = partIds[partIndex],
// cdi3: DisplayPart.name is the display label; fall back to the id.
name = context.partNameById[source.id] ?: source.id,
children = childrenOf(partIndex),
// MOC3 §5.6 s7/s8 carry the part's visibility (both flags, split unpinned). Sketch and
// lock ARE editor-only state the bake drops, so those still default to shown/unlocked.
isVisible = source.isVisible,
isSketch = false,
isSelectable = true,
// An owned offscreen wins over render-order-group membership (an isolated part is
// always grouped; the bake records both).
groupMode =
when {
offscreenComposite != null -> PartGroupMode.Isolated
partIndex in drawOrderGroupPartIndices -> PartGroupMode.Grouped
else -> PartGroupMode.PassThrough
},
drawOrder = partStaticDrawOrder(context, source),
channelGrids = partChannels,
composite = offscreenComposite ?: PartComposite(),
// MOC3 v5+ §5.6: a part-target blend record, whose only channel is the draw order.
blendShapes = partBlendShapesOfBound(context, source, partIndex, partChannels),
)
}
return Moc3ImportedParts(parts, childrenOf(-1))
}
/**
* The static (default-pose) draw order of a moc part - the sort key of its render-order slot.
*
* @param Moc3ImportContext context The import's derived state.
* @param MocPart source The moc part.
* @return Int The quantized draw order (Cubism default 500 when the part carries no keyforms).
*/
internal fun partStaticDrawOrder(
context: Moc3ImportContext,
source: MocPart,
): Int {
// MOC3: PART_KEYFORM_BINDING 0 means static for parts (a single draw-order value), unlike
// meshes/deformers where 0 is a real binding.
val binding = if (source.keyformBindingIndex > 0) context.bindingOf(source.keyformBindingIndex) else null
val defaultCell = defaultCellIndexOf(context, binding)
val drawOrder =
source.drawOrderKeyforms.getOrElse(defaultCell) {
source.drawOrderKeyforms.firstOrNull() ?: DEFAULT_DRAW_ORDER.toFloat()
}
return (drawOrder + 0.001f).toInt()
}
/**
* The compositing settings of a moc part, or null when the part owns no offscreen (i.e. its
* group mode is not Isolated).
*
* Takes the part's file index rather than looking the offscreen up by the part's id, for the same
* reason [partBlendShapesOfBound] does: a moc addresses its offscreens by index and nothing guarantees
* the id strings are unique, so two same-named parts would both read whichever record came last.
*
* @param Moc3ImportContext context The import's derived state.
* @param MocPart source The moc part.
* @param Int partIndex The part's file index.
* @return PartComposite? The runtime compositing settings, or null.
*/
internal fun partCompositeOf(
context: Moc3ImportContext,
source: MocPart,
partIndex: Int,
): PartComposite? {
val offscreen = context.offscreenByPartIndex[partIndex] ?: return null
// The first keyform doubles as the static fallback (a static part stores exactly one row).
val staticKeyform = offscreen.keyforms.firstOrNull()
return PartComposite(
// MOC3 v6 §5.6 s157: packed colorMode | (alphaMode shl 8).
blendMode = colorBlendOfPacked(offscreen.blendMode),
alphaBlendMode = alphaBlendOfPacked(offscreen.blendMode),
// MOC3 §5.6: offscreen mask sources are drawable file indices (the MASK_INDEX_DATA prefix).
maskedBy =
offscreen.maskIndices.toList()
.mapNotNull { maskIndex -> context.drawableIdsByFileIndex.getOrNull(maskIndex) },
// MOC3 v6 §5.6 s156 bit 3: invert clipping mask (same bit position as the drawable flag).
invertMask = offscreen.constantFlags and ConstantFlag.IS_INVERTED_MASK != 0,
opacity = staticKeyform?.opacity ?: 1f,
multiplyColor = colorRgbOf(staticKeyform?.multiplyColor) ?: ColorRgb.MultiplyIdentity,
screenColor = colorRgbOf(staticKeyform?.screenColor) ?: ColorRgb.ScreenIdentity,
)
}
/**
* The parameter-driven per-channel tracks of a moc part, empty when the part is static. Carries
* the draw order always; for an isolated part the offscreen's keyformed opacity/color
* channels merge in, riding the same grid cells (MOC3 §5.6: Σ owner grid == CountInfo 36).
*
* @param Moc3ImportContext context The import's derived state.
* @param MocPart source The moc part.
* @param Int partIndex The part's file index, which is how its offscreen names it.
* @return ChannelGrids The part's per-channel tracks, empty when it is unbound.
*/
internal fun partChannelsOf(
context: Moc3ImportContext,
source: MocPart,
partIndex: Int,
): ChannelGrids {
if (source.keyformBindingIndex <= 0) {
return ChannelGrids.Empty
}
val offscreenKeyforms = context.offscreenByPartIndex[partIndex]?.keyforms
val bundled =
gridOf(context, context.bindingOf(source.keyformBindingIndex)) { gridIndex ->
source.drawOrderKeyforms.getOrNull(gridIndex)?.let { drawOrder ->
val offscreenKeyform = offscreenKeyforms?.getOrNull(gridIndex)
PartForm(
drawOrder = drawOrder,
opacity = offscreenKeyform?.opacity ?: 1f,
multiplyColor = colorRgbOf(offscreenKeyform?.multiplyColor) ?: ColorRgb.MultiplyIdentity,
screenColor = colorRgbOf(offscreenKeyform?.screenColor) ?: ColorRgb.ScreenIdentity,
)
}
} ?: return ChannelGrids.Empty
// Fan the one bundled grid out into per-channel tracks sharing its axes: a pure re-shape, so the
// blended values are bit-identical to what the bundled cell produced.
return channelGridsOf(
FormChannel.DRAW_ORDER to bundled.asChannelTrack { form -> ChannelValue.Scalar(form.drawOrder) },
FormChannel.OPACITY to bundled.asChannelTrack { form -> ChannelValue.Scalar(form.opacity) },
FormChannel.MULTIPLY_COLOR to bundled.asChannelTrack { form -> ChannelValue.Color(form.multiplyColor) },
FormChannel.SCREEN_COLOR to bundled.asChannelTrack { form -> ChannelValue.Color(form.screenColor) },
)
}
/**
* [partBlendShapesOf] with this part's records looked up.
*
* Takes the part's file index rather than searching for it by id. A MOC3 addresses blend records
* by index and nothing guarantees the id strings are unique, so resolving the index from the id
* would give two same-named parts the SAME records - the first part's, applied twice, with the
* second part's own records never read. The caller is iterating by index already.
*
* @param Moc3ImportContext context The import's derived state.
* @param MocPart source The moc part.
* @param Int partIndex The part's file index.
* @param ChannelGrids channelGrids The part's tracks, already built by the caller.
* @return List<BlendShapeBinding<PartForm>> The runtime bindings, empty when the part has none.
*/
private fun partBlendShapesOfBound(
context: Moc3ImportContext,
source: MocPart,
partIndex: Int,
channelGrids: ChannelGrids,
): List<BlendShapeBinding<PartForm>> {
val records = context.blendRecordsByTarget[BlendShapeTarget.PART to partIndex].orEmpty()
if (records.isEmpty()) {
return emptyList()
}
return partBlendShapesOf(context, partStaticDrawOrder(context, source).toFloat(), channelGrids, records)
}
/**
* The part file indices the render-order tree names as "Group by Draw Order" groups.
*
* @param Moc3ImportContext context The import's derived state.
* @return Set<Int> The grouped parts' file indices.
*/
private fun drawOrderGroupPartIndices(context: Moc3ImportContext): Set<Int> =
buildSet {
// The draw-order tree: moc3 stores it explicitly (MOC3 §5.6 render-order groups, group 0 = root),
// so it is taken as the baked authority rather than re-derived from the reconstructed org tree.
// Parts referenced as kind-1 children are the "Group by Draw Order" parts.
for (group in context.mocDocument.renderOrderGroups) {
for (child in group.children) {
if (child.kind == 1) {
add(child.index)
}
}
}
}
@@ -0,0 +1,114 @@
package org.umamo.interop.moc3.import
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.RenderDrawable
import org.umamo.runtime.model.RenderGroup
import org.umamo.runtime.model.RenderNode
/**
* Builds the runtime render-order tree from the moc's explicit render-order groups (group 0 is the
* root), or null when the document carries none (degenerate; the caller derives from the org tree).
*
* A kind-0 child is a drawable leaf; a kind-1 child is a "Group by Draw Order" part whose sub-group
* record is [org.umamo.format.moc3.model.RenderOrderChild.groupIndex]. A visited set guards a
* malformed cyclic group reference, and drawables the stored tree never places are appended at the
* root (the renderer draws exclusively from this tree, so a missing leaf would never render).
*
* Runs BEFORE the part import, and reads the same part attributes it does - a grouped part's draw
* order, tracks, and composite appear on both its render group and its runtime `Part` - which is why
* those live in `Moc3PartImport` as plain functions over the context rather than being computed here.
*
* @param Moc3ImportContext context The import's derived state.
* @return RenderGroup? The render root, or null when the moc has no render-order groups.
*/
internal fun importRenderRoot(context: Moc3ImportContext): RenderGroup? {
val mocDocument = context.mocDocument
if (mocDocument.renderOrderGroups.isEmpty()) {
return null
}
val visitedGroups = HashSet<Int>()
fun childrenOf(groupIndex: Int): List<RenderNode> {
val group = mocDocument.renderOrderGroups.getOrNull(groupIndex) ?: return emptyList()
if (!visitedGroups.add(groupIndex)) {
return emptyList()
}
return group.children.mapNotNull { child ->
when (child.kind) {
// MOC3 §5.6 render-order child kind 0: a drawable leaf.
0 -> context.drawableIdsByFileIndex.getOrNull(child.index)?.let(::RenderDrawable)
// Kind 1: a draw-order group part; its members live in the referenced sub-group record.
1 -> {
val part = mocDocument.parts.getOrNull(child.index) ?: return@mapNotNull null
val partId = context.partIds.getOrNull(child.index) ?: return@mapNotNull null
RenderGroup(
partId = partId,
drawOrder = partStaticDrawOrder(context, part),
children = childrenOf(child.groupIndex),
channelGrids = partChannelsOf(context, part, child.index),
composite = partCompositeOf(context, part, child.index),
)
}
else -> null
}
}
}
val root = RenderGroup(null, DEFAULT_DRAW_ORDER, childrenOf(0))
// Safety net, mirroring deriveRenderRoot's: the renderer draws EXCLUSIVELY from this tree, so
// a drawable the stored groups never place (out-of-range child index, an unknown future child
// kind, or a truncated tree) would silently never render. Append the missing leaves at the
// root, where they sort by their own draw order like any other root-level drawable.
val placedLeaves = ArrayList<DrawableId>()
collectRenderLeaves(root, placedLeaves)
val placedDrawableIds = placedLeaves.toHashSet()
val missingLeaves =
context.drawableIdsByFileIndex.filter { drawableId -> drawableId !in placedDrawableIds }.map(::RenderDrawable)
return if (missingLeaves.isEmpty()) {
root
} else {
root.copy(children = root.children + missingLeaves)
}
}
/**
* Reconstructs each drawable's panel index from [renderRoot].
*
* Panel order (top = front) is not stored in moc3. Render order is back-to-front, so the REVERSED
* leaf sequence is the panel order. A null root - a document with no render-order groups - yields an
* empty map, and every reader then falls back to file order.
*
* @param RenderGroup? renderRoot The render tree, or null when the moc carried none.
* @return Map<DrawableId, Int> Panel index per placed drawable, front-most at 0.
*/
internal fun panelIndexesFrom(renderRoot: RenderGroup?): Map<DrawableId, Int> =
buildMap {
if (renderRoot != null) {
val leaves = ArrayList<DrawableId>()
collectRenderLeaves(renderRoot, leaves)
leaves.asReversed().forEachIndexed { panelIndex, drawableId ->
if (drawableId !in this) {
put(drawableId, panelIndex)
}
}
}
}
/**
* Collects a render tree's drawable leaves depth-first into [into] (back-to-front order).
*
* @param RenderNode node The subtree root.
* @param ArrayList<DrawableId> into The destination leaf list.
* @return Unit
*/
private fun collectRenderLeaves(
node: RenderNode,
into: ArrayList<DrawableId>,
) {
when (node) {
is RenderDrawable -> into.add(node.id)
is RenderGroup -> node.children.forEach { child -> collectRenderLeaves(child, into) }
}
}
@@ -0,0 +1,97 @@
package org.umamo.interop.uma
import org.umamo.format.uma.UmaEntryKind
import org.umamo.format.uma.UmaFormatException
import org.umamo.format.uma.UmaModel
import org.umamo.format.uma.UmaReadFailure
import org.umamo.format.uma.UmaWriteException
import org.umamo.format.uma.textures.UmaPixelSource
import org.umamo.format.uma.textures.UmaRenderPagePixels
import org.umamo.format.uma.textures.UmaTextures
import org.umamo.interop.AtlasPageSet
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
/**
* What a reopened document's renderer needs beside its model (docs/format/UMA.md §5.5): the page images its drawables
* sample, or null when the pages derive from the tiles, and every tile's PNG for the document's pixel store.
*
* @property AtlasPageSet? pageSet The imported page images with each drawable's image, or null when the loader
* composes the pages from the tiles (`deriveAtlasTextures`).
* @property Function tilePng Yields a tile's PNG by tile id, or null for a tile the document does not hold.
*/
class UmaDocumentPages(
val pageSet: AtlasPageSet?,
val tilePng: (AtlasTileId) -> ByteArray?,
)
/**
* The whole-document bridge: a [PuppetModel] with its atlas and linked source art saved into a UMA document's
* puppet, textures, and sources entries, and read back out.
*/
object UmaDocumentBridge {
/**
* [base] with its puppet, textures, and sources entries set from [model], each laid over the entry as read so
* every key this writer does not own survives.
*
* An entry too new for this reader occupies its kind and is carried byte for byte (UMA §3.3). Only an optional
* one leaves the document editable, so a save skips its kind while [model] has nothing to write there - no linked
* source art for the sources entry; no atlas and no stored render pages for the textures entry, whose thumbnail
* goes unwritten with it - and fails once it does.
*
* @param UmaModel base The document to save over: the one the model was opened from, or a new one.
* @param PuppetModel model The model.
* @param UmaPixelSource pixels The pixels the save writes: the tiles' PNGs, what the drawables sample, and the
* thumbnail.
* @return UmaModel The updated document.
* @throws UmaWriteException When the model holds a value the format cannot represent, a pixel entry is missing,
* or the model has content for a kind whose entry is too new to replace.
*/
fun documentOf(base: UmaModel, model: PuppetModel, pixels: UmaPixelSource): UmaModel {
var document = base.withPuppet(UmaPuppetExport.puppetOf(model))
val textures = UmaTexturesBridge.texturesOf(model)
val texturesHaveContent = textures != UmaTextures() || pixels.renderPages is UmaRenderPagePixels.Stored
if (!base.holdsTooNewEntry(UmaEntryKind.Textures) || texturesHaveContent) {
document = document.withTextures(textures, pixels)
}
if (!base.holdsTooNewEntry(UmaEntryKind.Sources) || model.sources.isNotEmpty()) {
document = document.withSources(UmaSourcesBridge.sourcesOf(model))
}
return document
}
/**
* The model [document] describes: the puppet with its atlas and linked source art.
*
* The editor entry is not read here, and that is the whole of the rule: a file with `editor/` stripped loads the
* same model because nothing in the model ever came from it (docs/format/UMA.md § 7).
*
* @param UmaModel document The document.
* @return PuppetModel The model.
* @throws UmaFormatException When the document has no puppet entry this reader can read.
*/
fun modelOf(document: UmaModel): PuppetModel {
val puppet = document.puppet ?: throw UmaFormatException(UmaReadFailure.MissingEntry(UmaEntryKind.Puppet.defaultPath))
return UmaPuppetImport.modelOf(puppet).copy(atlas = UmaTexturesBridge.atlasOf(document.textures), sources = UmaSourcesBridge.sourcesOf(document.sources))
}
/**
* The page images a reopened [document]'s drawables sample, and its tiles' PNGs (UMA §5.5): the stored render
* pages with their map when the document was saved with its imported pages, or no page set when its pages derive
* from the tiles.
*
* @param UmaModel document The document.
* @return UmaDocumentPages The page set and the tile PNGs.
*/
fun pagesOf(document: UmaModel): UmaDocumentPages {
val textures = document.textures
val tilePathById = textures?.tiles.orEmpty().mapNotNull { tile -> tile.path?.let { path -> tile.id to path } }.toMap()
val tilePng: (AtlasTileId) -> ByteArray? = { tileId -> tilePathById[tileId.raw]?.let(document::payloadBytes) }
val pageSet =
textures?.renderPages?.let { renderPages ->
// UMA §5.5: the format layer has already checked every render page's entry is there.
AtlasPageSet(renderPages.pages.map { page -> checkNotNull(document.payloadBytes(page.path)) }, renderPages.drawablePages.orEmpty())
}
return UmaDocumentPages(pageSet, tilePng)
}
}
@@ -0,0 +1,221 @@
package org.umamo.interop.uma
import org.umamo.format.uma.puppet.UmaAlphaBlendMode
import org.umamo.format.uma.puppet.UmaBlendMode
import org.umamo.format.uma.puppet.UmaFormChannel
import org.umamo.format.uma.puppet.UmaGroupMode
import org.umamo.format.uma.puppet.UmaParameterKind
import org.umamo.format.uma.puppet.UmaRuntimeTarget
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.RuntimeTarget
/*
* The runtime model's enums against the puppet entry's (docs/format/UMA.md §4.1). Every mapping is an
* exhaustive `when` in both directions, so a constant added on either side is a compile error here rather
* than a value that silently fails to round-trip.
*/
/**
* The file-side spelling of a blend mode.
*
* @return UmaBlendMode The file's value.
*/
internal fun BlendMode.toUma(): UmaBlendMode =
when (this) {
BlendMode.Normal -> UmaBlendMode.Normal
BlendMode.AdditivePremultiplied -> UmaBlendMode.AdditivePremultiplied
BlendMode.MultiplyPremultiplied -> UmaBlendMode.MultiplyPremultiplied
BlendMode.Additive -> UmaBlendMode.Additive
BlendMode.AdditiveGlow -> UmaBlendMode.AdditiveGlow
BlendMode.Darken -> UmaBlendMode.Darken
BlendMode.Multiply -> UmaBlendMode.Multiply
BlendMode.ColorBurn -> UmaBlendMode.ColorBurn
BlendMode.LinearBurn -> UmaBlendMode.LinearBurn
BlendMode.Lighten -> UmaBlendMode.Lighten
BlendMode.Screen -> UmaBlendMode.Screen
BlendMode.ColorDodge -> UmaBlendMode.ColorDodge
BlendMode.Overlay -> UmaBlendMode.Overlay
BlendMode.SoftLight -> UmaBlendMode.SoftLight
BlendMode.HardLight -> UmaBlendMode.HardLight
BlendMode.LinearLight -> UmaBlendMode.LinearLight
BlendMode.Hue -> UmaBlendMode.Hue
BlendMode.Color -> UmaBlendMode.Color
}
/**
* The runtime blend mode a file value names.
*
* @return BlendMode The runtime value.
*/
internal fun UmaBlendMode.toRuntime(): BlendMode =
when (this) {
UmaBlendMode.Normal -> BlendMode.Normal
UmaBlendMode.AdditivePremultiplied -> BlendMode.AdditivePremultiplied
UmaBlendMode.MultiplyPremultiplied -> BlendMode.MultiplyPremultiplied
UmaBlendMode.Additive -> BlendMode.Additive
UmaBlendMode.AdditiveGlow -> BlendMode.AdditiveGlow
UmaBlendMode.Darken -> BlendMode.Darken
UmaBlendMode.Multiply -> BlendMode.Multiply
UmaBlendMode.ColorBurn -> BlendMode.ColorBurn
UmaBlendMode.LinearBurn -> BlendMode.LinearBurn
UmaBlendMode.Lighten -> BlendMode.Lighten
UmaBlendMode.Screen -> BlendMode.Screen
UmaBlendMode.ColorDodge -> BlendMode.ColorDodge
UmaBlendMode.Overlay -> BlendMode.Overlay
UmaBlendMode.SoftLight -> BlendMode.SoftLight
UmaBlendMode.HardLight -> BlendMode.HardLight
UmaBlendMode.LinearLight -> BlendMode.LinearLight
UmaBlendMode.Hue -> BlendMode.Hue
UmaBlendMode.Color -> BlendMode.Color
}
/**
* The file-side spelling of an alpha blend mode.
*
* @return UmaAlphaBlendMode The file's value.
*/
internal fun AlphaBlendMode.toUma(): UmaAlphaBlendMode =
when (this) {
AlphaBlendMode.Over -> UmaAlphaBlendMode.Over
AlphaBlendMode.Atop -> UmaAlphaBlendMode.Atop
AlphaBlendMode.Out -> UmaAlphaBlendMode.Out
AlphaBlendMode.Conjoint -> UmaAlphaBlendMode.Conjoint
AlphaBlendMode.Disjoint -> UmaAlphaBlendMode.Disjoint
}
/**
* The runtime alpha blend mode a file value names.
*
* @return AlphaBlendMode The runtime value.
*/
internal fun UmaAlphaBlendMode.toRuntime(): AlphaBlendMode =
when (this) {
UmaAlphaBlendMode.Over -> AlphaBlendMode.Over
UmaAlphaBlendMode.Atop -> AlphaBlendMode.Atop
UmaAlphaBlendMode.Out -> AlphaBlendMode.Out
UmaAlphaBlendMode.Conjoint -> AlphaBlendMode.Conjoint
UmaAlphaBlendMode.Disjoint -> AlphaBlendMode.Disjoint
}
/**
* The file-side spelling of a parameter kind.
*
* @return UmaParameterKind The file's value.
*/
internal fun ParameterKind.toUma(): UmaParameterKind =
when (this) {
ParameterKind.NORMAL -> UmaParameterKind.Normal
ParameterKind.BLEND_SHAPE -> UmaParameterKind.BlendShape
}
/**
* The runtime parameter kind a file value names.
*
* @return ParameterKind The runtime value.
*/
internal fun UmaParameterKind.toRuntime(): ParameterKind =
when (this) {
UmaParameterKind.Normal -> ParameterKind.NORMAL
UmaParameterKind.BlendShape -> ParameterKind.BLEND_SHAPE
}
/**
* The file-side spelling of a part group mode.
*
* @return UmaGroupMode The file's value.
*/
internal fun PartGroupMode.toUma(): UmaGroupMode =
when (this) {
PartGroupMode.PassThrough -> UmaGroupMode.PassThrough
PartGroupMode.Grouped -> UmaGroupMode.Grouped
PartGroupMode.Isolated -> UmaGroupMode.Isolated
}
/**
* The runtime part group mode a file value names.
*
* @return PartGroupMode The runtime value.
*/
internal fun UmaGroupMode.toRuntime(): PartGroupMode =
when (this) {
UmaGroupMode.PassThrough -> PartGroupMode.PassThrough
UmaGroupMode.Grouped -> PartGroupMode.Grouped
UmaGroupMode.Isolated -> PartGroupMode.Isolated
}
/**
* The file-side spelling of a runtime target.
*
* @return UmaRuntimeTarget The file's value.
*/
internal fun RuntimeTarget.toUma(): UmaRuntimeTarget =
when (this) {
RuntimeTarget.NoTarget -> UmaRuntimeTarget.NoTarget
RuntimeTarget.Ayagami -> UmaRuntimeTarget.Ayagami
RuntimeTarget.Cubism30 -> UmaRuntimeTarget.Cubism30
RuntimeTarget.Cubism33 -> UmaRuntimeTarget.Cubism33
RuntimeTarget.Cubism40 -> UmaRuntimeTarget.Cubism40
RuntimeTarget.Cubism42 -> UmaRuntimeTarget.Cubism42
RuntimeTarget.Cubism50 -> UmaRuntimeTarget.Cubism50
RuntimeTarget.Cubism53 -> UmaRuntimeTarget.Cubism53
}
/**
* The runtime target a file value names.
*
* @return RuntimeTarget The runtime value.
*/
internal fun UmaRuntimeTarget.toRuntime(): RuntimeTarget =
when (this) {
UmaRuntimeTarget.NoTarget -> RuntimeTarget.NoTarget
UmaRuntimeTarget.Ayagami -> RuntimeTarget.Ayagami
UmaRuntimeTarget.Cubism30 -> RuntimeTarget.Cubism30
UmaRuntimeTarget.Cubism33 -> RuntimeTarget.Cubism33
UmaRuntimeTarget.Cubism40 -> RuntimeTarget.Cubism40
UmaRuntimeTarget.Cubism42 -> RuntimeTarget.Cubism42
UmaRuntimeTarget.Cubism50 -> RuntimeTarget.Cubism50
UmaRuntimeTarget.Cubism53 -> RuntimeTarget.Cubism53
}
/**
* The file-side spelling of a keyform channel.
*
* @return UmaFormChannel The file's value.
*/
internal fun FormChannel.toUma(): UmaFormChannel =
when (this) {
FormChannel.DRAW_ORDER -> UmaFormChannel.DrawOrder
FormChannel.OPACITY -> UmaFormChannel.Opacity
FormChannel.MULTIPLY_COLOR -> UmaFormChannel.MultiplyColor
FormChannel.SCREEN_COLOR -> UmaFormChannel.ScreenColor
FormChannel.FLIP_X -> UmaFormChannel.FlipX
FormChannel.FLIP_Y -> UmaFormChannel.FlipY
FormChannel.GLUE_INTENSITY -> UmaFormChannel.GlueIntensity
}
/**
* The runtime keyform channel a file value names.
*
* @return FormChannel The runtime value.
*/
internal fun UmaFormChannel.toRuntime(): FormChannel =
when (this) {
UmaFormChannel.DrawOrder -> FormChannel.DRAW_ORDER
UmaFormChannel.Opacity -> FormChannel.OPACITY
UmaFormChannel.MultiplyColor -> FormChannel.MULTIPLY_COLOR
UmaFormChannel.ScreenColor -> FormChannel.SCREEN_COLOR
UmaFormChannel.FlipX -> FormChannel.FLIP_X
UmaFormChannel.FlipY -> FormChannel.FLIP_Y
UmaFormChannel.GlueIntensity -> FormChannel.GLUE_INTENSITY
}
/**
* The key a channel's track is written under, which failure paths name.
*
* @return String The key.
*/
internal fun UmaFormChannel.wireName(): String = UmaFormChannel.serializer().descriptor.getElementName(ordinal)
@@ -0,0 +1,25 @@
package org.umamo.interop.uma
import org.umamo.format.uma.sources.UMA_SHA256_PREFIX
/*
* The hash form the sources entry writes (docs/format/UMA.md §6.4): the model keeps a SHA-256 digest as bare
* lowercase hex, and the file names the algorithm in front of it.
*/
/**
* The file's form of a model hash.
*
* @param String? digest The digest as bare lowercase hex, or null.
* @return String? The prefixed hash, or null.
*/
internal fun prefixedHashOf(digest: String?): String? = digest?.let { hex -> "$UMA_SHA256_PREFIX$hex" }
/**
* The model's form of a file hash. The format layer has already refused any other algorithm, so the prefix is
* always there to strip.
*
* @param String? hash The prefixed hash, or null.
* @return String? The bare digest, or null.
*/
internal fun digestOf(hash: String?): String? = hash?.removePrefix(UMA_SHA256_PREFIX)
@@ -0,0 +1,24 @@
package org.umamo.interop.uma
import org.umamo.format.uma.UmaWriteException
/*
* The checks every domain entry's export shares for values written inline as JSON (docs/format/UMA.md §4.1).
*/
/**
* [value], refusing a NaN or an infinity, which JSON cannot hold.
*
* @param Float value The value.
* @param String entryPath The entry the value is written to, for the failure.
* @param String path Where the value sits in the entry, for the failure.
* @return Float The value.
* @throws UmaWriteException When the value is not finite.
*/
internal fun finiteInline(value: Float, entryPath: String, path: String): Float {
if (!value.isFinite()) {
// UMA §4.1: JSON has no NaN or infinity.
throw UmaWriteException("$entryPath: $path", "$value cannot be written as JSON")
}
return value
}
@@ -0,0 +1,596 @@
package org.umamo.interop.uma
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonPrimitive
import org.umamo.format.uma.UmaEntryKind
import org.umamo.format.uma.UmaWriteException
import org.umamo.format.uma.puppet.UmaAxis
import org.umamo.format.uma.puppet.UmaBlendLimit
import org.umamo.format.uma.puppet.UmaBlendLimitPoint
import org.umamo.format.uma.puppet.UmaChannelCell
import org.umamo.format.uma.puppet.UmaChannelGrid
import org.umamo.format.uma.puppet.UmaDeformer
import org.umamo.format.uma.puppet.UmaDeformerBlendShape
import org.umamo.format.uma.puppet.UmaDeformerCell
import org.umamo.format.uma.puppet.UmaDeformerForm
import org.umamo.format.uma.puppet.UmaDeformerGrid
import org.umamo.format.uma.puppet.UmaDeformerKind
import org.umamo.format.uma.puppet.UmaDrawable
import org.umamo.format.uma.puppet.UmaFormChannel
import org.umamo.format.uma.puppet.UmaGlue
import org.umamo.format.uma.puppet.UmaGluePairs
import org.umamo.format.uma.puppet.UmaMesh
import org.umamo.format.uma.puppet.UmaMeshBlendShape
import org.umamo.format.uma.puppet.UmaMeshCell
import org.umamo.format.uma.puppet.UmaMeshForm
import org.umamo.format.uma.puppet.UmaMeshGrid
import org.umamo.format.uma.puppet.UmaOrgRef
import org.umamo.format.uma.puppet.UmaParameter
import org.umamo.format.uma.puppet.UmaParameterLink
import org.umamo.format.uma.puppet.UmaParameterNode
import org.umamo.format.uma.puppet.UmaPart
import org.umamo.format.uma.puppet.UmaPartBlendShape
import org.umamo.format.uma.puppet.UmaPartComposite
import org.umamo.format.uma.puppet.UmaPartForm
import org.umamo.format.uma.puppet.UmaPuppet
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.BlendWeightLimit
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.Glue
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.ParameterNode
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartForm
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.RuntimeTarget
import org.umamo.runtime.model.WarpForm
import org.umamo.runtime.model.WarpLatticeForm
/**
* Lowers a [PuppetModel] onto the puppet entry's schema (docs/format/UMA.md §4).
*
* A value is left out of the file only when it is bit-for-bit the model's default, so `-0.0` and `0.0`
* stay distinct; every float is checked to be finite first, because JSON cannot hold anything else and a
* silently dropped value would be worse than a refused save.
*
* Bulk arrays (meshes, position deltas, lattice points, glue pairs) are handed over as they are; they travel
* in the entry's buffer, which holds any float bit for bit. Inline floats (axis keys, pivots, channel values,
* form scalars) must be finite.
*/
object UmaPuppetExport {
/**
* The puppet entry for [model].
*
* @param PuppetModel model The puppet.
* @return UmaPuppet The entry's content.
* @throws UmaWriteException When a float the entry holds is NaN or infinite.
*/
fun puppetOf(model: PuppetModel): UmaPuppet =
UmaPuppet(
canvasWidth = optionalFloat(model.canvasWidth, 0f, "canvasWidth"),
canvasHeight = optionalFloat(model.canvasHeight, 0f, "canvasHeight"),
worldOriginX = optionalFloat(model.worldOriginX, 0f, "worldOriginX"),
worldOriginZ = optionalFloat(model.worldOriginZ, 0f, "worldOriginZ"),
pixelsPerUnit = model.pixelsPerUnit?.let { scale -> finite(scale, "pixelsPerUnit") },
runtimeTarget = model.runtimeTarget.takeIf { target -> target != RuntimeTarget.NoTarget }?.toUma(),
rendersFromSourceLayers = optionalBoolean(model.rendersFromSourceLayers, false),
parameters = model.parameters.map(::parameterOf).ifEmpty { null },
parameterLinks = model.parameterLinks.map { link -> UmaParameterLink(link.horizontal.raw, link.vertical.raw) }.ifEmpty { null },
parameterTree = model.parameterTree.map(::parameterNodeOf).ifEmpty { null },
rootPart = model.rootPartId?.raw,
rootChildren = model.rootChildren.map(::orgRefOf).ifEmpty { null },
parts = model.parts.map(::partOf).ifEmpty { null },
deformers = model.deformers.map(::deformerOf).ifEmpty { null },
drawables = model.drawables.map(::drawableOf).ifEmpty { null },
glues = model.glues.map(::glueOf).ifEmpty { null },
)
/**
* UMA §4.3: one parameter.
*
* @param Parameter parameter The parameter.
* @return UmaParameter The record.
*/
private fun parameterOf(parameter: Parameter): UmaParameter {
val path = "parameters[${parameter.id.raw}]"
return UmaParameter(
id = parameter.id.raw,
name = parameter.name,
min = finite(parameter.min, "$path.min"),
max = finite(parameter.max, "$path.max"),
default = finite(parameter.default, "$path.default"),
kind = parameter.kind.takeIf { kind -> kind != ParameterKind.NORMAL }?.toUma(),
repeat = optionalBoolean(parameter.repeat, false),
)
}
/**
* UMA §4.3: one parameter-tree node.
*
* @param ParameterNode node The node.
* @return UmaParameterNode The record.
*/
private fun parameterNodeOf(node: ParameterNode): UmaParameterNode =
when (node) {
is ParameterNode.Param -> UmaParameterNode(parameter = node.id.raw)
is ParameterNode.Group ->
UmaParameterNode(
group = node.id.raw,
name = node.name,
initiallyOpen = optionalBoolean(node.initiallyOpen, false),
children = node.children.map(::parameterNodeOf).ifEmpty { null },
)
}
/**
* UMA §4.2: one organizational child.
*
* @param OrgChild child The child.
* @return UmaOrgRef The record.
*/
private fun orgRefOf(child: OrgChild): UmaOrgRef =
when (child) {
is OrgChild.Part -> UmaOrgRef(part = child.id.raw)
is OrgChild.Drawable -> UmaOrgRef(drawable = child.id.raw)
}
/**
* UMA §4.4: one part.
*
* @param Part part The part.
* @return UmaPart The record.
*/
private fun partOf(part: Part): UmaPart {
val path = "parts[${part.id.raw}]"
return UmaPart(
id = part.id.raw,
name = part.name,
children = part.children.map(::orgRefOf).ifEmpty { null },
isVisible = optionalBoolean(part.isVisible, true),
isSketch = optionalBoolean(part.isSketch, false),
isSelectable = optionalBoolean(part.isSelectable, true),
groupMode = part.groupMode.takeIf { mode -> mode != PartGroupMode.PassThrough }?.toUma(),
drawOrder = part.drawOrder.takeIf { order -> order != DEFAULT_DRAW_ORDER },
composite = compositeOf(part.composite, "$path.composite"),
channels = channelsOf(part.channelGrids, path),
blendShapes = part.blendShapes.mapIndexed { bindingIndex, binding -> partBlendShapeOf(binding, "$path.blendShapes[$bindingIndex]") }.ifEmpty { null },
)
}
/**
* UMA §4.4: a part's composite, or null when every setting is at its default.
*
* @param PartComposite composite The composite.
* @param String path The composite's position, for a failure.
* @return UmaPartComposite? The record.
*/
private fun compositeOf(composite: PartComposite, path: String): UmaPartComposite? {
val record =
UmaPartComposite(
blendMode = composite.blendMode.takeIf { mode -> mode != BlendMode.Normal }?.toUma(),
alphaBlendMode = composite.alphaBlendMode.takeIf { mode -> mode != AlphaBlendMode.Over }?.toUma(),
maskedBy = composite.maskedBy.map { id -> id.raw }.ifEmpty { null },
maskedByParts = composite.maskedByParts.map { id -> id.raw }.ifEmpty { null },
invertMask = optionalBoolean(composite.invertMask, false),
opacity = optionalFloat(composite.opacity, 1f, "$path.opacity"),
multiplyColor = optionalColor(composite.multiplyColor, ColorRgb.MultiplyIdentity, "$path.multiplyColor"),
screenColor = optionalColor(composite.screenColor, ColorRgb.ScreenIdentity, "$path.screenColor"),
)
return record.takeIf { candidate -> candidate != UmaPartComposite() }
}
/**
* UMA §4.5: one deformer.
*
* @param Deformer deformer The deformer.
* @return UmaDeformer The record.
*/
private fun deformerOf(deformer: Deformer): UmaDeformer {
val path = "deformers[${deformer.id.raw}]"
return when (deformer) {
is Deformer.Warp ->
UmaDeformer(
id = deformer.id.raw,
kind = UmaDeformerKind.Warp,
name = deformer.name,
parent = deformer.parent?.raw,
part = deformer.partId?.raw,
isVisible = optionalBoolean(deformer.isVisible, true),
isEnabled = optionalBoolean(deformer.isEnabled, true),
isSelectable = optionalBoolean(deformer.isSelectable, true),
opacity = optionalFloat(deformer.opacity, 1f, "$path.opacity"),
multiplyColor = optionalColor(deformer.multiplyColor, ColorRgb.MultiplyIdentity, "$path.multiplyColor"),
screenColor = optionalColor(deformer.screenColor, ColorRgb.ScreenIdentity, "$path.screenColor"),
rows = deformer.rows,
columns = deformer.columns,
isQuadTransform = deformer.isQuadTransform,
geometry = deformer.geometryGrid?.let { grid -> warpGridOf(grid, "$path.geometry") },
channels = channelsOf(deformer.channelGrids, path),
blendShapes = deformer.blendShapes.mapIndexed { bindingIndex, binding -> warpBlendShapeOf(binding, "$path.blendShapes[$bindingIndex]") }.ifEmpty { null },
)
is Deformer.Rotation ->
UmaDeformer(
id = deformer.id.raw,
kind = UmaDeformerKind.Rotation,
name = deformer.name,
parent = deformer.parent?.raw,
part = deformer.partId?.raw,
isVisible = optionalBoolean(deformer.isVisible, true),
isEnabled = optionalBoolean(deformer.isEnabled, true),
isSelectable = optionalBoolean(deformer.isSelectable, true),
opacity = optionalFloat(deformer.opacity, 1f, "$path.opacity"),
multiplyColor = optionalColor(deformer.multiplyColor, ColorRgb.MultiplyIdentity, "$path.multiplyColor"),
screenColor = optionalColor(deformer.screenColor, ColorRgb.ScreenIdentity, "$path.screenColor"),
baseAngle = finite(deformer.baseAngle, "$path.baseAngle"),
flipX = optionalBoolean(deformer.flipX, false),
flipY = optionalBoolean(deformer.flipY, false),
geometry = deformer.geometryGrid?.let { grid -> rotationGridOf(grid, "$path.geometry") },
channels = channelsOf(deformer.channelGrids, path),
blendShapes = deformer.blendShapes.mapIndexed { bindingIndex, binding -> rotationBlendShapeOf(binding, "$path.blendShapes[$bindingIndex]") }.ifEmpty { null },
)
}
}
/**
* UMA §4.6: one drawable's structure.
*
* @param Drawable drawable The drawable.
* @return UmaDrawable The record.
*/
private fun drawableOf(drawable: Drawable): UmaDrawable {
val path = "drawables[${drawable.id.raw}]"
return UmaDrawable(
id = drawable.id.raw,
name = drawable.name,
parentDeformer = drawable.parentDeformerId?.raw,
blendMode = drawable.blendMode.takeIf { mode -> mode != BlendMode.Normal }?.toUma(),
maskedBy = drawable.maskedBy.map { id -> id.raw }.ifEmpty { null },
invertMask = optionalBoolean(drawable.invertMask, false),
drawOrder = optionalFloat(drawable.drawOrder, DEFAULT_DRAW_ORDER.toFloat(), "$path.drawOrder"),
opacity = optionalFloat(drawable.opacity, 1f, "$path.opacity"),
multiplyColor = optionalColor(drawable.multiplyColor, ColorRgb.MultiplyIdentity, "$path.multiplyColor"),
screenColor = optionalColor(drawable.screenColor, ColorRgb.ScreenIdentity, "$path.screenColor"),
alphaBlendMode = drawable.alphaBlendMode.takeIf { mode -> mode != AlphaBlendMode.Over }?.toUma(),
culling = optionalBoolean(drawable.culling, false),
isVisible = optionalBoolean(drawable.isVisible, true),
isSelectable = optionalBoolean(drawable.isSelectable, true),
textureSource = drawable.textureSourceId?.raw,
texturePage = drawable.texturePage.takeIf { page -> page != -1 },
atlasTile = drawable.atlasTileId?.raw,
mesh = drawable.mesh?.let { mesh -> UmaMesh(mesh.positions, mesh.uvs, mesh.indices) },
geometry = drawable.geometryGrid?.let { grid -> meshGridOf(grid, "$path.geometry") },
channels = channelsOf(drawable.channelGrids, path),
blendShapes = drawable.blendShapes.mapIndexed { bindingIndex, binding -> meshBlendShapeOf(binding, "$path.blendShapes[$bindingIndex]") }.ifEmpty { null },
)
}
/**
* UMA §4.14: one glue affecter.
*
* @param Glue glue The glue.
* @return UmaGlue The record.
*/
private fun glueOf(glue: Glue): UmaGlue {
val path = "glues[${glue.meshA.raw},${glue.meshB.raw}]"
return UmaGlue(
meshA = glue.meshA.raw,
meshB = glue.meshB.raw,
pairs =
UmaGluePairs(
indicesA = IntArray(glue.pairs.size) { pairIndex -> glue.pairs[pairIndex].indexA },
indicesB = IntArray(glue.pairs.size) { pairIndex -> glue.pairs[pairIndex].indexB },
weightsA = FloatArray(glue.pairs.size) { pairIndex -> glue.pairs[pairIndex].weightA },
weightsB = FloatArray(glue.pairs.size) { pairIndex -> glue.pairs[pairIndex].weightB },
),
channels = channelsOf(glue.channelGrids, path),
intensity = optionalFloat(glue.intensity, 1f, "$path.intensity"),
id = glue.id,
)
}
/**
* UMA §4.11: a grid's axes.
*
* @param List<KeyformAxis> axes The axes.
* @param String path The grid's position, for a failure.
* @return List<UmaAxis> The records.
*/
private fun axesOf(axes: List<KeyformAxis>, path: String): List<UmaAxis> =
axes.mapIndexed { axisIndex, axis -> UmaAxis(axis.parameterId.raw, keysOf(axis.keys, "$path.axes[$axisIndex].keys")) }
/**
* Inline key values, each checked to be finite.
*
* @param FloatArray keys The keys.
* @param String path Where they sit, for a failure.
* @return List<Float> The keys.
*/
private fun keysOf(keys: FloatArray, path: String): List<Float> = keys.mapIndexed { keyIndex, key -> finite(key, "$path[$keyIndex]") }
/**
* UMA §4.11: a drawable's geometry grid.
*
* @param KeyformGrid grid The grid.
* @param String path The grid's position, for a failure.
* @return UmaMeshGrid The record.
*/
private fun meshGridOf(grid: KeyformGrid<MeshDeltaForm>, path: String): UmaMeshGrid =
UmaMeshGrid(axesOf(grid.axes, path), grid.cells.map { cell -> UmaMeshCell(cell.coordinate.toList(), cell.form.positionDeltas) })
/**
* UMA §4.11: a warp's geometry grid.
*
* @param KeyformGrid grid The grid.
* @param String path The grid's position, for a failure.
* @return UmaDeformerGrid The record.
*/
private fun warpGridOf(grid: KeyformGrid<WarpLatticeForm>, path: String): UmaDeformerGrid =
UmaDeformerGrid(axesOf(grid.axes, path), grid.cells.map { cell -> UmaDeformerCell(cell.coordinate.toList(), controlPoints = cell.form.controlPoints) })
/**
* UMA §4.11: a rotation's geometry grid.
*
* @param KeyformGrid grid The grid.
* @param String path The grid's position, for a failure.
* @return UmaDeformerGrid The record.
*/
private fun rotationGridOf(grid: KeyformGrid<RotationPivotForm>, path: String): UmaDeformerGrid =
UmaDeformerGrid(
axesOf(grid.axes, path),
grid.cells.mapIndexed { cellIndex, cell ->
val cellPath = "$path.cells[$cellIndex]"
UmaDeformerCell(
coordinate = cell.coordinate.toList(),
originX = finite(cell.form.originX, "$cellPath.originX"),
originY = finite(cell.form.originY, "$cellPath.originY"),
angle = finite(cell.form.angle, "$cellPath.angle"),
scale = finite(cell.form.scale, "$cellPath.scale"),
)
},
)
/**
* UMA §4.12: an owner's channel tracks, in channel order, or null when it keys none.
*
* @param ChannelGrids channelGrids The tracks.
* @param String path The owner's position, for a failure.
* @return Map? The records.
*/
private fun channelsOf(channelGrids: ChannelGrids, path: String): Map<UmaFormChannel, UmaChannelGrid>? {
if (channelGrids.isEmpty) {
return null
}
val tracks = LinkedHashMap<UmaFormChannel, UmaChannelGrid>()
for (channel in FormChannel.entries) {
val grid = channelGrids[channel] ?: continue
val trackPath = "$path.channels.${channel.toUma().wireName()}"
tracks[channel.toUma()] =
UmaChannelGrid(
axesOf(grid.axes, trackPath),
grid.cells.mapIndexed { cellIndex, cell -> UmaChannelCell(cell.coordinate.toList(), channelValueOf(cell.form, "$trackPath.cells[$cellIndex].value")) },
)
}
return tracks
}
/**
* UMA §4.12: one channel value as JSON - a number, a color, or a boolean.
*
* @param ChannelValue value The value.
* @param String path Where it sits, for a failure.
* @return JsonElement The JSON.
*/
private fun channelValueOf(value: ChannelValue, path: String): JsonElement =
when (value) {
is ChannelValue.Scalar -> JsonPrimitive(finite(value.value, path))
is ChannelValue.Color ->
JsonArray(
listOf(
JsonPrimitive(finite(value.color.red, "$path[0]")),
JsonPrimitive(finite(value.color.green, "$path[1]")),
JsonPrimitive(finite(value.color.blue, "$path[2]")),
),
)
is ChannelValue.Flag -> JsonPrimitive(value.flag)
}
/**
* UMA §4.13: a binding's limits, or null when it has none.
*
* @param List<BlendWeightLimit> limits The limits.
* @param String path The binding's position, for a failure.
* @return List<UmaBlendLimit>? The records.
*/
private fun limitsOf(limits: List<BlendWeightLimit>, path: String): List<UmaBlendLimit>? =
limits.mapIndexed { limitIndex, limit ->
UmaBlendLimit(
limit.parameterId.raw,
limit.points.mapIndexed { pointIndex, point ->
val pointPath = "$path.limits[$limitIndex].points[$pointIndex]"
UmaBlendLimitPoint(finite(point.value, "$pointPath.value"), finite(point.weight, "$pointPath.weight"))
},
)
}.ifEmpty { null }
/**
* UMA §4.13: a drawable's blend-shape binding.
*
* @param BlendShapeBinding binding The binding.
* @param String path Its position, for a failure.
* @return UmaMeshBlendShape The record.
*/
private fun meshBlendShapeOf(binding: BlendShapeBinding<MeshForm>, path: String): UmaMeshBlendShape =
UmaMeshBlendShape(
parameter = binding.parameterId.raw,
keys = keysOf(binding.keys, "$path.keys"),
neutralIndex = binding.neutralIndex,
forms =
binding.forms.mapIndexed { formIndex, form ->
form?.let {
val formPath = "$path.forms[$formIndex]"
UmaMeshForm(
positionDeltas = form.positionDeltas,
drawOrder = optionalFloat(form.drawOrder, DEFAULT_DRAW_ORDER.toFloat(), "$formPath.drawOrder"),
opacity = optionalFloat(form.opacity, 1f, "$formPath.opacity"),
multiplyColor = optionalColor(form.multiplyColor, ColorRgb.MultiplyIdentity, "$formPath.multiplyColor"),
screenColor = optionalColor(form.screenColor, ColorRgb.ScreenIdentity, "$formPath.screenColor"),
)
}
},
limits = limitsOf(binding.limits, path),
)
/**
* UMA §4.13: a warp's blend-shape binding.
*
* @param BlendShapeBinding binding The binding.
* @param String path Its position, for a failure.
* @return UmaDeformerBlendShape The record.
*/
private fun warpBlendShapeOf(binding: BlendShapeBinding<WarpForm>, path: String): UmaDeformerBlendShape =
UmaDeformerBlendShape(
parameter = binding.parameterId.raw,
keys = keysOf(binding.keys, "$path.keys"),
neutralIndex = binding.neutralIndex,
forms =
binding.forms.mapIndexed { formIndex, form ->
form?.let {
val formPath = "$path.forms[$formIndex]"
UmaDeformerForm(
controlPoints = form.controlPoints,
opacity = optionalFloat(form.opacity, 1f, "$formPath.opacity"),
multiplyColor = optionalColor(form.multiplyColor, ColorRgb.MultiplyIdentity, "$formPath.multiplyColor"),
screenColor = optionalColor(form.screenColor, ColorRgb.ScreenIdentity, "$formPath.screenColor"),
)
}
},
limits = limitsOf(binding.limits, path),
)
/**
* UMA §4.13: a rotation's blend-shape binding.
*
* @param BlendShapeBinding binding The binding.
* @param String path Its position, for a failure.
* @return UmaDeformerBlendShape The record.
*/
private fun rotationBlendShapeOf(binding: BlendShapeBinding<RotationForm>, path: String): UmaDeformerBlendShape =
UmaDeformerBlendShape(
parameter = binding.parameterId.raw,
keys = keysOf(binding.keys, "$path.keys"),
neutralIndex = binding.neutralIndex,
forms =
binding.forms.mapIndexed { formIndex, form ->
form?.let {
val formPath = "$path.forms[$formIndex]"
UmaDeformerForm(
originX = finite(form.originX, "$formPath.originX"),
originY = finite(form.originY, "$formPath.originY"),
angle = finite(form.angle, "$formPath.angle"),
scale = finite(form.scale, "$formPath.scale"),
flipX = optionalBoolean(form.flipX, false),
flipY = optionalBoolean(form.flipY, false),
opacity = optionalFloat(form.opacity, 1f, "$formPath.opacity"),
multiplyColor = optionalColor(form.multiplyColor, ColorRgb.MultiplyIdentity, "$formPath.multiplyColor"),
screenColor = optionalColor(form.screenColor, ColorRgb.ScreenIdentity, "$formPath.screenColor"),
)
}
},
limits = limitsOf(binding.limits, path),
)
/**
* UMA §4.13: a part's blend-shape binding.
*
* @param BlendShapeBinding binding The binding.
* @param String path Its position, for a failure.
* @return UmaPartBlendShape The record.
*/
private fun partBlendShapeOf(binding: BlendShapeBinding<PartForm>, path: String): UmaPartBlendShape =
UmaPartBlendShape(
parameter = binding.parameterId.raw,
keys = keysOf(binding.keys, "$path.keys"),
neutralIndex = binding.neutralIndex,
forms =
binding.forms.mapIndexed { formIndex, form ->
form?.let {
val formPath = "$path.forms[$formIndex]"
UmaPartForm(
drawOrder = finite(form.drawOrder, "$formPath.drawOrder"),
opacity = optionalFloat(form.opacity, 1f, "$formPath.opacity"),
multiplyColor = optionalColor(form.multiplyColor, ColorRgb.MultiplyIdentity, "$formPath.multiplyColor"),
screenColor = optionalColor(form.screenColor, ColorRgb.ScreenIdentity, "$formPath.screenColor"),
)
}
},
limits = limitsOf(binding.limits, path),
)
/**
* [value], refusing a NaN or infinity.
*
* @param Float value The value.
* @param String path Where the value sits in the entry, for the failure.
* @return Float The value.
* @throws UmaWriteException When the value is not finite.
*/
private fun finite(value: Float, path: String): Float = finiteInline(value, UmaEntryKind.Puppet.defaultPath, path)
/**
* [value], or null when it is bit-for-bit [default].
*
* @param Float value The value.
* @param Float default The model's default.
* @param String path Where the value sits, for a failure.
* @return Float? The value to write.
* @throws UmaWriteException When the value is not finite.
*/
private fun optionalFloat(value: Float, default: Float, path: String): Float? =
finite(value, path).takeIf { candidate -> candidate.toRawBits() != default.toRawBits() }
/**
* [color] as red, green, blue, or null when every channel is bit-for-bit [identity]'s.
*
* @param ColorRgb color The color.
* @param ColorRgb identity The channel's identity color.
* @param String path Where the color sits, for a failure.
* @return List<Float>? The channels to write.
* @throws UmaWriteException When a channel is not finite.
*/
private fun optionalColor(color: ColorRgb, identity: ColorRgb, path: String): List<Float>? {
val channels = listOf(finite(color.red, "$path[0]"), finite(color.green, "$path[1]"), finite(color.blue, "$path[2]"))
val identityChannels = listOf(identity.red, identity.green, identity.blue)
val isIdentity = channels.indices.all { channelIndex -> channels[channelIndex].toRawBits() == identityChannels[channelIndex].toRawBits() }
return if (isIdentity) null else channels
}
/**
* [value], or null when it is [default].
*
* @param Boolean value The value.
* @param Boolean default The model's default.
* @return Boolean? The value to write.
*/
private fun optionalBoolean(value: Boolean, default: Boolean): Boolean? = value.takeIf { candidate -> candidate != default }
}
@@ -0,0 +1,523 @@
package org.umamo.interop.uma
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.booleanOrNull
import kotlinx.serialization.json.floatOrNull
import org.umamo.format.uma.puppet.UmaAxis
import org.umamo.format.uma.puppet.UmaBlendLimit
import org.umamo.format.uma.puppet.UmaChannelGrid
import org.umamo.format.uma.puppet.UmaDeformer
import org.umamo.format.uma.puppet.UmaDeformerBlendShape
import org.umamo.format.uma.puppet.UmaDeformerGrid
import org.umamo.format.uma.puppet.UmaDeformerKind
import org.umamo.format.uma.puppet.UmaDrawable
import org.umamo.format.uma.puppet.UmaFormChannel
import org.umamo.format.uma.puppet.UmaGlue
import org.umamo.format.uma.puppet.UmaMeshBlendShape
import org.umamo.format.uma.puppet.UmaMeshGrid
import org.umamo.format.uma.puppet.UmaOrgRef
import org.umamo.format.uma.puppet.UmaParameter
import org.umamo.format.uma.puppet.UmaParameterNode
import org.umamo.format.uma.puppet.UmaPart
import org.umamo.format.uma.puppet.UmaPartBlendShape
import org.umamo.format.uma.puppet.UmaPartComposite
import org.umamo.format.uma.puppet.UmaPuppet
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.BlendWeightLimit
import org.umamo.runtime.model.BlendWeightLimitPoint
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ChannelValueKind
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.DEFAULT_DRAW_ORDER
import org.umamo.runtime.model.Deformer
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.GluePair
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.ParameterLink
import org.umamo.runtime.model.ParameterNode
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartForm
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.RuntimeTarget
import org.umamo.runtime.model.WarpForm
import org.umamo.runtime.model.WarpLatticeForm
import org.umamo.runtime.model.withDerivedRenderRoot
/**
* Builds a [PuppetModel] from the puppet entry (docs/format/UMA.md §4): restores each absent value to the
* model's default and derives the render root from the organizational tree (UMA §4.2).
*
* The entry comes from the codec, which has already refused every shape the model cannot hold (UMA §4.8): a field
* that belongs to another kind of object, arrays that disagree in size, and indices or keys out of range or order.
* Ids are taken verbatim and references are not resolved: a reference to an object the entry does not hold is
* carried as it is, never dropped.
*/
object UmaPuppetImport {
/**
* The model [puppet] describes.
*
* @param UmaPuppet puppet The puppet entry's content, as the codec decoded it (`UmaModel.puppet`).
* @return PuppetModel The model.
*/
fun modelOf(puppet: UmaPuppet): PuppetModel {
val model =
PuppetModel(
parameters = puppet.parameters.orEmpty().map(::parameterOf),
parts = puppet.parts.orEmpty().map(::partOf),
deformers = puppet.deformers.orEmpty().map(::deformerOf),
drawables = puppet.drawables.orEmpty().map(::drawableOf),
glues = puppet.glues.orEmpty().map(::glueOf),
rootChildren = puppet.rootChildren.orEmpty().map(::orgChildOf),
rootPartId = puppet.rootPart?.let(::PartId),
parameterLinks = puppet.parameterLinks.orEmpty().map { link -> ParameterLink(ParameterId(link.horizontal), ParameterId(link.vertical)) },
parameterTree = puppet.parameterTree.orEmpty().map(::parameterNodeOf),
canvasWidth = puppet.canvasWidth ?: 0f,
canvasHeight = puppet.canvasHeight ?: 0f,
worldOriginX = puppet.worldOriginX ?: 0f,
worldOriginZ = puppet.worldOriginZ ?: 0f,
pixelsPerUnit = puppet.pixelsPerUnit,
runtimeTarget = puppet.runtimeTarget?.toRuntime() ?: RuntimeTarget.NoTarget,
rendersFromSourceLayers = puppet.rendersFromSourceLayers ?: false,
)
// UMA §4.2: the render root is never written; it is always the organizational tree's derivation.
return model.withDerivedRenderRoot()
}
/**
* UMA §4.3: one parameter.
*
* @param UmaParameter record The record.
* @return Parameter The parameter.
*/
private fun parameterOf(record: UmaParameter): Parameter =
Parameter(
id = ParameterId(record.id),
name = record.name,
min = record.min,
max = record.max,
default = record.default,
kind = record.kind?.toRuntime() ?: ParameterKind.NORMAL,
repeat = record.repeat ?: false,
)
/**
* UMA §4.3: one parameter-tree node, which the codec has checked is exactly one of a leaf and a named group.
*
* @param UmaParameterNode record The record.
* @return ParameterNode The node.
*/
private fun parameterNodeOf(record: UmaParameterNode): ParameterNode {
val leaf = record.parameter
if (leaf != null) {
return ParameterNode.Param(ParameterId(leaf))
}
return ParameterNode.Group(
id = ParameterGroupId(checkNotNull(record.group) { "the codec checked a tree node names a parameter or a group" }),
name = checkNotNull(record.name) { "the codec checked a group has a name" },
initiallyOpen = record.initiallyOpen ?: false,
children = record.children.orEmpty().map(::parameterNodeOf),
)
}
/**
* UMA §4.2: one organizational child, which the codec has checked is exactly one of a part and a drawable.
*
* @param UmaOrgRef record The record.
* @return OrgChild The child.
*/
private fun orgChildOf(record: UmaOrgRef): OrgChild {
val part = record.part
if (part != null) {
return OrgChild.Part(PartId(part))
}
return OrgChild.Drawable(DrawableId(checkNotNull(record.drawable) { "the codec checked an org reference names a part or a drawable" }))
}
/**
* UMA §4.4: one part.
*
* @param UmaPart record The record.
* @return Part The part.
*/
private fun partOf(record: UmaPart): Part =
Part(
id = PartId(record.id),
name = record.name,
children = record.children.orEmpty().map(::orgChildOf),
isVisible = record.isVisible ?: true,
isSketch = record.isSketch ?: false,
isSelectable = record.isSelectable ?: true,
groupMode = record.groupMode?.toRuntime() ?: PartGroupMode.PassThrough,
drawOrder = record.drawOrder ?: DEFAULT_DRAW_ORDER,
composite = compositeOf(record.composite ?: UmaPartComposite()),
channelGrids = channelsOf(record.channels),
blendShapes = record.blendShapes.orEmpty().map(::partBlendShapeOf),
)
/**
* UMA §4.4: a part's composite.
*
* @param UmaPartComposite record The record.
* @return PartComposite The composite.
*/
private fun compositeOf(record: UmaPartComposite): PartComposite =
PartComposite(
blendMode = record.blendMode?.toRuntime() ?: BlendMode.Normal,
alphaBlendMode = record.alphaBlendMode?.toRuntime() ?: AlphaBlendMode.Over,
maskedBy = record.maskedBy.orEmpty().map(::DrawableId),
maskedByParts = record.maskedByParts.orEmpty().map(::PartId),
invertMask = record.invertMask ?: false,
opacity = record.opacity ?: 1f,
multiplyColor = colorOf(record.multiplyColor, ColorRgb.MultiplyIdentity),
screenColor = colorOf(record.screenColor, ColorRgb.ScreenIdentity),
)
/**
* UMA §4.5: one deformer, whose kind decides which kind-specific fields it carries.
*
* @param UmaDeformer record The record.
* @return Deformer The deformer.
*/
private fun deformerOf(record: UmaDeformer): Deformer {
val multiplyColor = colorOf(record.multiplyColor, ColorRgb.MultiplyIdentity)
val screenColor = colorOf(record.screenColor, ColorRgb.ScreenIdentity)
return when (record.kind) {
UmaDeformerKind.Warp ->
Deformer.Warp(
id = DeformerId(record.id),
name = record.name,
parent = record.parent?.let(::DeformerId),
partId = record.part?.let(::PartId),
rows = checkNotNull(record.rows) { "the codec checked a warp has rows" },
columns = checkNotNull(record.columns) { "the codec checked a warp has columns" },
isQuadTransform = checkNotNull(record.isQuadTransform) { "the codec checked a warp has isQuadTransform" },
geometryGrid = record.geometry?.let(::warpGridOf),
channelGrids = channelsOf(record.channels),
blendShapes = record.blendShapes.orEmpty().map(::warpBlendShapeOf),
opacity = record.opacity ?: 1f,
multiplyColor = multiplyColor,
screenColor = screenColor,
isSelectable = record.isSelectable ?: true,
isVisible = record.isVisible ?: true,
isEnabled = record.isEnabled ?: true,
)
UmaDeformerKind.Rotation ->
Deformer.Rotation(
id = DeformerId(record.id),
name = record.name,
parent = record.parent?.let(::DeformerId),
partId = record.part?.let(::PartId),
baseAngle = checkNotNull(record.baseAngle) { "the codec checked a rotation has baseAngle" },
geometryGrid = record.geometry?.let(::rotationGridOf),
channelGrids = channelsOf(record.channels),
blendShapes = record.blendShapes.orEmpty().map(::rotationBlendShapeOf),
opacity = record.opacity ?: 1f,
multiplyColor = multiplyColor,
screenColor = screenColor,
flipX = record.flipX ?: false,
flipY = record.flipY ?: false,
isSelectable = record.isSelectable ?: true,
isVisible = record.isVisible ?: true,
isEnabled = record.isEnabled ?: true,
)
}
}
/**
* UMA §4.6: one drawable.
*
* @param UmaDrawable record The record.
* @return Drawable The drawable.
*/
private fun drawableOf(record: UmaDrawable): Drawable =
Drawable(
id = DrawableId(record.id),
name = record.name,
parentDeformerId = record.parentDeformer?.let(::DeformerId),
blendMode = record.blendMode?.toRuntime() ?: BlendMode.Normal,
maskedBy = record.maskedBy.orEmpty().map(::DrawableId),
mesh = record.mesh?.let { mesh -> DrawableMesh(mesh.positions, mesh.uvs, mesh.indices) },
geometryGrid = record.geometry?.let(::meshGridOf),
channelGrids = channelsOf(record.channels),
drawOrder = record.drawOrder ?: DEFAULT_DRAW_ORDER.toFloat(),
opacity = record.opacity ?: 1f,
multiplyColor = colorOf(record.multiplyColor, ColorRgb.MultiplyIdentity),
screenColor = colorOf(record.screenColor, ColorRgb.ScreenIdentity),
invertMask = record.invertMask ?: false,
alphaBlendMode = record.alphaBlendMode?.toRuntime() ?: AlphaBlendMode.Over,
culling = record.culling ?: false,
isVisible = record.isVisible ?: true,
isSelectable = record.isSelectable ?: true,
textureSourceId = record.textureSource?.let(::DrawableId),
texturePage = record.texturePage ?: -1,
atlasTileId = record.atlasTile?.let(::AtlasTileId),
blendShapes = record.blendShapes.orEmpty().map(::meshBlendShapeOf),
)
/**
* UMA §4.14: one glue affecter.
*
* @param UmaGlue record The record.
* @return Glue The glue.
*/
private fun glueOf(record: UmaGlue): Glue {
val pairs = record.pairs
return Glue(
meshA = DrawableId(record.meshA),
meshB = DrawableId(record.meshB),
pairs = List(pairs.indicesA.size) { pairIndex -> GluePair(pairs.indicesA[pairIndex], pairs.indicesB[pairIndex], pairs.weightsA[pairIndex], pairs.weightsB[pairIndex]) },
channelGrids = channelsOf(record.channels),
intensity = record.intensity ?: 1f,
id = record.id,
)
}
/**
* UMA §4.11: a grid's axes.
*
* @param List<UmaAxis> records The records.
* @return List<KeyformAxis> The axes.
*/
private fun axesOf(records: List<UmaAxis>): List<KeyformAxis> = records.map { axis -> KeyformAxis(ParameterId(axis.parameter), axis.keys.toFloatArray()) }
/**
* UMA §4.11: a drawable's geometry grid.
*
* @param UmaMeshGrid record The record.
* @return KeyformGrid The grid.
*/
private fun meshGridOf(record: UmaMeshGrid): KeyformGrid<MeshDeltaForm> =
KeyformGrid(axesOf(record.axes), record.cells.map { cell -> KeyformCell(cell.coordinate.toIntArray(), MeshDeltaForm(cell.positionDeltas)) })
/**
* UMA §4.11: a warp's geometry grid, whose cells carry a whole lattice.
*
* @param UmaDeformerGrid record The record.
* @return KeyformGrid The grid.
*/
private fun warpGridOf(record: UmaDeformerGrid): KeyformGrid<WarpLatticeForm> =
KeyformGrid(
axesOf(record.axes),
record.cells.map { cell -> KeyformCell(cell.coordinate.toIntArray(), WarpLatticeForm(checkNotNull(cell.controlPoints) { "the codec checked a warp cell has controlPoints" })) },
)
/**
* UMA §4.11: a rotation's geometry grid, whose cells carry a whole pivot.
*
* @param UmaDeformerGrid record The record.
* @return KeyformGrid The grid.
*/
private fun rotationGridOf(record: UmaDeformerGrid): KeyformGrid<RotationPivotForm> =
KeyformGrid(
axesOf(record.axes),
record.cells.map { cell ->
KeyformCell(
cell.coordinate.toIntArray(),
RotationPivotForm(
originX = checkNotNull(cell.originX) { PIVOT_CHECKED },
originY = checkNotNull(cell.originY) { PIVOT_CHECKED },
angle = checkNotNull(cell.angle) { PIVOT_CHECKED },
scale = checkNotNull(cell.scale) { PIVOT_CHECKED },
),
)
},
)
/**
* UMA §4.12: an owner's channel tracks.
*
* @param Map? records The records, or null when the owner keys none.
* @return ChannelGrids The tracks.
*/
private fun channelsOf(records: Map<UmaFormChannel, UmaChannelGrid>?): ChannelGrids {
if (records.isNullOrEmpty()) {
return ChannelGrids.Empty
}
val tracks = LinkedHashMap<FormChannel, KeyformGrid<ChannelValue>>()
for ((umaChannel, record) in records) {
val channel = umaChannel.toRuntime()
tracks[channel] = KeyformGrid(axesOf(record.axes), record.cells.map { cell -> KeyformCell(cell.coordinate.toIntArray(), channelValueOf(cell.value, channel.valueKind)) })
}
return ChannelGrids(tracks)
}
/**
* UMA §4.12: one channel value - a number, a color, or a boolean, as the channel's kind requires, which the codec
* has checked.
*
* @param JsonElement value The JSON.
* @param ChannelValueKind kind The channel's kind.
* @return ChannelValue The value.
*/
private fun channelValueOf(value: JsonElement, kind: ChannelValueKind): ChannelValue =
when (kind) {
ChannelValueKind.SCALAR -> ChannelValue.Scalar(numberOf(value))
ChannelValueKind.COLOR -> {
val channels = (value as JsonArray).map(::numberOf)
ChannelValue.Color(ColorRgb(channels[0], channels[1], channels[2]))
}
ChannelValueKind.FLAG -> ChannelValue.Flag(checkNotNull((value as JsonPrimitive).booleanOrNull) { "the codec checked a flag value is a boolean" })
}
/**
* [value] as the float the codec has checked it holds.
*
* @param JsonElement value The JSON.
* @return Float The number.
*/
private fun numberOf(value: JsonElement): Float = checkNotNull((value as JsonPrimitive).floatOrNull) { "the codec checked a channel value is a number" }
/**
* UMA §4.13: a binding's limits.
*
* @param List<UmaBlendLimit>? records The records.
* @return List<BlendWeightLimit> The limits.
*/
private fun limitsOf(records: List<UmaBlendLimit>?): List<BlendWeightLimit> =
records.orEmpty().map { limit -> BlendWeightLimit(ParameterId(limit.parameter), limit.points.map { point -> BlendWeightLimitPoint(point.value, point.weight) }) }
/**
* UMA §4.13: a drawable's blend-shape binding.
*
* @param UmaMeshBlendShape record The record.
* @return BlendShapeBinding The binding.
*/
private fun meshBlendShapeOf(record: UmaMeshBlendShape): BlendShapeBinding<MeshForm> =
BlendShapeBinding(
parameterId = ParameterId(record.parameter),
keys = record.keys.toFloatArray(),
neutralIndex = record.neutralIndex,
forms =
record.forms.map { form ->
form?.let {
MeshForm(
positionDeltas = form.positionDeltas,
drawOrder = form.drawOrder ?: DEFAULT_DRAW_ORDER.toFloat(),
opacity = form.opacity ?: 1f,
multiplyColor = colorOf(form.multiplyColor, ColorRgb.MultiplyIdentity),
screenColor = colorOf(form.screenColor, ColorRgb.ScreenIdentity),
)
}
},
limits = limitsOf(record.limits),
)
/**
* UMA §4.13: a warp's blend-shape binding, whose forms carry a whole lattice.
*
* @param UmaDeformerBlendShape record The record.
* @return BlendShapeBinding The binding.
*/
private fun warpBlendShapeOf(record: UmaDeformerBlendShape): BlendShapeBinding<WarpForm> =
BlendShapeBinding(
parameterId = ParameterId(record.parameter),
keys = record.keys.toFloatArray(),
neutralIndex = record.neutralIndex,
forms =
record.forms.map { form ->
form?.let {
WarpForm(
controlPoints = checkNotNull(form.controlPoints) { "the codec checked a warp form has controlPoints" },
opacity = form.opacity ?: 1f,
multiplyColor = colorOf(form.multiplyColor, ColorRgb.MultiplyIdentity),
screenColor = colorOf(form.screenColor, ColorRgb.ScreenIdentity),
)
}
},
limits = limitsOf(record.limits),
)
/**
* UMA §4.13: a rotation's blend-shape binding, whose forms carry a whole pivot.
*
* @param UmaDeformerBlendShape record The record.
* @return BlendShapeBinding The binding.
*/
private fun rotationBlendShapeOf(record: UmaDeformerBlendShape): BlendShapeBinding<RotationForm> =
BlendShapeBinding(
parameterId = ParameterId(record.parameter),
keys = record.keys.toFloatArray(),
neutralIndex = record.neutralIndex,
forms =
record.forms.map { form ->
form?.let {
RotationForm(
originX = checkNotNull(form.originX) { PIVOT_CHECKED },
originY = checkNotNull(form.originY) { PIVOT_CHECKED },
angle = checkNotNull(form.angle) { PIVOT_CHECKED },
scale = checkNotNull(form.scale) { PIVOT_CHECKED },
flipX = form.flipX ?: false,
flipY = form.flipY ?: false,
opacity = form.opacity ?: 1f,
multiplyColor = colorOf(form.multiplyColor, ColorRgb.MultiplyIdentity),
screenColor = colorOf(form.screenColor, ColorRgb.ScreenIdentity),
)
}
},
limits = limitsOf(record.limits),
)
/**
* UMA §4.13: a part's blend-shape binding.
*
* @param UmaPartBlendShape record The record.
* @return BlendShapeBinding The binding.
*/
private fun partBlendShapeOf(record: UmaPartBlendShape): BlendShapeBinding<PartForm> =
BlendShapeBinding(
parameterId = ParameterId(record.parameter),
keys = record.keys.toFloatArray(),
neutralIndex = record.neutralIndex,
forms =
record.forms.map { form ->
form?.let {
PartForm(
drawOrder = form.drawOrder,
opacity = form.opacity ?: 1f,
multiplyColor = colorOf(form.multiplyColor, ColorRgb.MultiplyIdentity),
screenColor = colorOf(form.screenColor, ColorRgb.ScreenIdentity),
)
}
},
limits = limitsOf(record.limits),
)
/**
* UMA §4.1: a color, which the codec has checked is exactly three channels, or [identity] when absent.
*
* @param List<Float>? channels The record's channels.
* @param ColorRgb identity The channel's identity color.
* @return ColorRgb The color.
*/
private fun colorOf(channels: List<Float>?, identity: ColorRgb): ColorRgb = channels?.let { ColorRgb(channels[0], channels[1], channels[2]) } ?: identity
/** The failure a rotation form without its whole pivot reports, which the codec has already refused. */
private const val PIVOT_CHECKED = "the codec checked a rotation form carries its whole pivot"
}
@@ -0,0 +1,93 @@
package org.umamo.interop.uma
import org.umamo.format.uma.sources.UmaSource
import org.umamo.format.uma.sources.UmaSourceLayer
import org.umamo.format.uma.sources.UmaSources
import org.umamo.runtime.model.ArtSource
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.PuppetModel
/**
* Lowers a [PuppetModel]'s linked source art onto the sources entry's schema (docs/format/UMA.md §6), and back:
* every inventory row with every flag, and the hashes in the file's prefixed form (UMA §6.4).
*/
object UmaSourcesBridge {
/**
* The sources entry's content for [model].
*
* @param PuppetModel model The model.
* @return UmaSources The content; an empty object when the document links no source art.
*/
fun sourcesOf(model: PuppetModel): UmaSources =
UmaSources(
model.sources.map { source ->
UmaSource(
id = source.id.raw,
name = source.name,
format = source.format,
path = source.path,
contentHash = prefixedHashOf(source.contentHash),
lastModified = source.lastModified,
layers =
source.layers.map { layer ->
UmaSourceLayer(
key = layer.key,
name = layer.name,
groupPath = layer.groupPath,
left = layer.left,
top = layer.top,
width = layer.width,
height = layer.height,
visible = layer.visible,
present = layer.present.takeIf { present -> !present },
contentHash = prefixedHashOf(layer.contentHash),
empty = layer.empty.takeIf { empty -> empty },
replaced = layer.replaced.takeIf { replaced -> replaced },
ignored = layer.ignored.takeIf { ignored -> ignored },
)
}.ifEmpty { null },
offsetX = source.offsetX.takeIf { offset -> offset != 0 },
offsetZ = source.offsetZ.takeIf { offset -> offset != 0 },
)
}.ifEmpty { null },
)
/**
* The linked source art the sources entry describes.
*
* @param UmaSources? sources The entry's content, or null when the document has none.
* @return List<ArtSource> The sources, in document order.
*/
fun sourcesOf(sources: UmaSources?): List<ArtSource> =
sources?.sources.orEmpty().map { source ->
ArtSource(
id = ArtSourceId(source.id),
name = source.name,
path = source.path,
format = source.format,
layers =
source.layers.orEmpty().map { layer ->
ArtSourceLayer(
key = layer.key,
name = layer.name,
groupPath = layer.groupPath,
left = layer.left,
top = layer.top,
width = layer.width,
height = layer.height,
visible = layer.visible,
present = layer.present ?: true,
contentHash = digestOf(layer.contentHash),
empty = layer.empty ?: false,
replaced = layer.replaced ?: false,
ignored = layer.ignored ?: false,
)
},
contentHash = digestOf(source.contentHash),
lastModified = source.lastModified,
offsetX = source.offsetX ?: 0,
offsetZ = source.offsetZ ?: 0,
)
}
}
@@ -0,0 +1,126 @@
package org.umamo.interop.uma
import org.umamo.format.uma.UmaEntryKind
import org.umamo.format.uma.UmaWriteException
import org.umamo.format.uma.textures.UmaComposition
import org.umamo.format.uma.textures.UmaPage
import org.umamo.format.uma.textures.UmaPlacement
import org.umamo.format.uma.textures.UmaSourceRef
import org.umamo.format.uma.textures.UmaTextures
import org.umamo.format.uma.textures.UmaTile
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.AtlasComposition
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.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.SourceLayerRef
/**
* Lowers a [PuppetModel]'s atlas onto the textures entry's schema (docs/format/UMA.md §5), and back.
*
* The atlas records only; the images the drawables sample (the render pages) and every path are the format layer's
* to lay out from the pixels a save hands it. A value is left out only when it is the model's default.
*/
object UmaTexturesBridge {
/**
* The textures entry's records for [model].
*
* @param PuppetModel model The model.
* @return UmaTextures The records, without paths.
* @throws UmaWriteException When a placement holds a value JSON cannot.
*/
fun texturesOf(model: PuppetModel): UmaTextures {
val atlas = model.atlas
val composition = atlas.composition
val default = AtlasComposition.Default
return UmaTextures(
storedUvsAddressPages = atlas.storedUvsAddressPages.takeIf { addressesPages -> !addressesPages },
composition =
UmaComposition(
alphaThreshold = composition.alphaThreshold.takeIf { threshold -> threshold != default.alphaThreshold },
extrude = composition.extrude.takeIf { extrude -> extrude != default.extrude },
).takeIf { record -> record != UmaComposition() },
pages = atlas.pages.map { page -> UmaPage(page.width, page.height) }.ifEmpty { null },
tiles = atlas.tiles.map(::tileOf).ifEmpty { null },
)
}
/**
* UMA §5.4: one tile's record.
*
* @param AtlasTile tile The tile.
* @return UmaTile The record.
* @throws UmaWriteException When its placement holds a value JSON cannot.
*/
private fun tileOf(tile: AtlasTile): UmaTile {
val path = "tiles[${tile.id.raw}].placement"
/**
* [value], refused when it is not finite.
*
* @param Float value The value.
* @param String key The placement key, for the failure.
* @return Float The value.
*/
fun finite(value: Float, key: String): Float = finiteInline(value, UmaEntryKind.Textures.defaultPath, "$path.$key")
return UmaTile(
id = tile.id.raw,
name = tile.name,
width = tile.width,
height = tile.height,
placement =
tile.placement?.let { placement ->
UmaPlacement(
page = placement.pageIndex,
positionX = finite(placement.positionX, "positionX"),
positionY = finite(placement.positionY, "positionY"),
scaleX = finite(placement.scaleX, "scaleX"),
scaleY = finite(placement.scaleY, "scaleY"),
rotationDegrees = finite(placement.rotationDegrees, "rotationDegrees"),
)
},
source = tile.source?.let { source -> UmaSourceRef(source.sourceId.raw, source.layerKey, source.stableKey) },
pinned = tile.pinned.takeIf { pinned -> pinned },
replaces = tile.replaces?.raw,
)
}
/**
* The atlas the textures entry describes.
*
* @param UmaTextures? textures The entry's content, or null when the document has none.
* @return PuppetAtlas The atlas.
*/
fun atlasOf(textures: UmaTextures?): PuppetAtlas {
if (textures == null) {
return PuppetAtlas.Empty
}
val tiles =
textures.tiles.orEmpty().map { record ->
AtlasTile(
id = AtlasTileId(record.id),
name = record.name,
width = record.width,
height = record.height,
placement =
record.placement?.let { placement ->
AtlasPlacement(placement.page, placement.positionX, placement.positionY, placement.scaleX, placement.scaleY, placement.rotationDegrees)
},
source = record.source?.let { source -> SourceLayerRef(ArtSourceId(source.art), source.layerKey, source.stableKey) },
pinned = record.pinned ?: false,
replaces = record.replaces?.let(::AtlasTileId),
)
}
val default = AtlasComposition.Default
return PuppetAtlas(
pages = textures.pages.orEmpty().map { page -> AtlasPage(page.width, page.height) },
tiles = tiles,
storedUvsAddressPages = textures.storedUvsAddressPages ?: true,
// UMA §5.2: the format layer has already refused a composition outside the ranges the model allows.
composition = AtlasComposition(textures.composition?.alphaThreshold ?: default.alphaThreshold, textures.composition?.extrude ?: default.extrude),
)
}
}
@@ -0,0 +1,108 @@
package org.umamo.interop
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Pins the blend-mode bijections against the extraction tables in docs/plan/offscreen-support.md:
* every CMO3 token and every MOC3 packed int maps to its distinct runtime mode, the two encodings
* agree pairwise, and unknown values fall back to Normal/Over.
*/
class BlendModeMappingTest {
/** One row of the extraction table: CMO3 token, MOC3 colorMode int, runtime mode. */
private data class ColorRow(val token: String, val packedColor: Int, val mode: BlendMode)
private val colorRows =
listOf(
ColorRow("NORMAL", 0, BlendMode.Normal),
ColorRow("ADD", 1, BlendMode.AdditivePremultiplied),
ColorRow("MULTIPLY", 2, BlendMode.MultiplyPremultiplied),
ColorRow("ADD_R2_TSL", 3, BlendMode.Additive),
ColorRow("ADD_R2", 4, BlendMode.AdditiveGlow),
ColorRow("DARKEN", 5, BlendMode.Darken),
ColorRow("MULTIPLY_R2", 6, BlendMode.Multiply),
ColorRow("COLORBURN_TSL", 7, BlendMode.ColorBurn),
ColorRow("LINEARBURN_TSL", 8, BlendMode.LinearBurn),
ColorRow("LIGHTEN", 9, BlendMode.Lighten),
ColorRow("SCREEN", 10, BlendMode.Screen),
ColorRow("COLORDODGE_TSL", 11, BlendMode.ColorDodge),
ColorRow("OVERLAY", 12, BlendMode.Overlay),
ColorRow("SOFTLIGHT", 13, BlendMode.SoftLight),
ColorRow("HARDLIGHT", 14, BlendMode.HardLight),
ColorRow("LINEARLIGHT_TSL", 15, BlendMode.LinearLight),
ColorRow("HSL_HUE", 16, BlendMode.Hue),
ColorRow("HSL_COLOR", 17, BlendMode.Color),
)
/** One row of the alpha table: CMO3 token, MOC3 alphaMode int, runtime mode. */
private data class AlphaRow(val token: String, val packedAlpha: Int, val mode: AlphaBlendMode)
private val alphaRows =
listOf(
AlphaRow("OVER", 0, AlphaBlendMode.Over),
AlphaRow("ATOP", 1, AlphaBlendMode.Atop),
AlphaRow("OUT", 2, AlphaBlendMode.Out),
AlphaRow("CONJOINT", 3, AlphaBlendMode.Conjoint),
AlphaRow("DISJOINT", 4, AlphaBlendMode.Disjoint),
)
@Test
fun colorTableIsACompleteBijection() {
assertEquals(BlendMode.entries.size, colorRows.size, "one row per BlendMode constant")
assertEquals(colorRows.size, colorRows.map { it.mode }.toSet().size, "modes are distinct")
for (row in colorRows) {
assertEquals(row.mode, colorBlendOfToken(row.token), "token ${row.token}")
assertEquals(row.mode, colorBlendOfPacked(row.packedColor), "packed colorMode ${row.packedColor}")
}
}
@Test
fun alphaTableIsACompleteBijection() {
assertEquals(AlphaBlendMode.entries.size, alphaRows.size, "one row per AlphaBlendMode constant")
assertEquals(alphaRows.size, alphaRows.map { it.mode }.toSet().size, "modes are distinct")
for (row in alphaRows) {
assertEquals(row.mode, alphaBlendOfToken(row.token), "token ${row.token}")
assertEquals(row.mode, alphaBlendOfPacked(row.packedAlpha shl 8), "packed alphaMode ${row.packedAlpha}")
}
}
@Test
fun packedHalvesAreIndependent() {
// The corpus-observed combinations: 522 = Screen or (Out shl 8) (the PartClipping drawable),
// 262 = Multiply or (Atop shl 8), 256 = Normal or (Atop shl 8) (Model A offscreens).
assertEquals(BlendMode.Screen, colorBlendOfPacked(522))
assertEquals(AlphaBlendMode.Out, alphaBlendOfPacked(522))
assertEquals(BlendMode.Multiply, colorBlendOfPacked(262))
assertEquals(AlphaBlendMode.Atop, alphaBlendOfPacked(262))
assertEquals(BlendMode.Normal, colorBlendOfPacked(256))
assertEquals(AlphaBlendMode.Atop, alphaBlendOfPacked(256))
assertEquals(BlendMode.Normal, colorBlendOfPacked(0))
assertEquals(AlphaBlendMode.Over, alphaBlendOfPacked(0))
}
@Test
fun unknownValuesFallBackToDefaults() {
assertEquals(BlendMode.Normal, colorBlendOfToken(null))
assertEquals(BlendMode.Normal, colorBlendOfToken("SOME_FUTURE_MODE"))
assertEquals(AlphaBlendMode.Over, alphaBlendOfToken(null))
assertEquals(AlphaBlendMode.Over, alphaBlendOfToken("SOME_FUTURE_MODE"))
assertEquals(BlendMode.Normal, colorBlendOfPacked(99))
assertEquals(AlphaBlendMode.Over, alphaBlendOfPacked(99 shl 8))
}
@Test
fun legacyPredicateCoversExactlyThePreFiveThreeModes() {
val legacyModes = BlendMode.entries.filter { it.isLegacy }
assertEquals(listOf(BlendMode.Normal, BlendMode.AdditivePremultiplied, BlendMode.MultiplyPremultiplied), legacyModes)
assertTrue(BlendMode.entries.filterNot { it.isLegacy }.size == 15, "fifteen 5.3 modes")
}
@Test
fun ignoresAlphaBlendCoversExactlyTheTwoPremultipliedModes() {
val ignoringModes = BlendMode.entries.filter { it.ignoresAlphaBlend }
assertEquals(listOf(BlendMode.AdditivePremultiplied, BlendMode.MultiplyPremultiplied), ignoringModes)
}
}
@@ -0,0 +1,46 @@
package org.umamo.interop
import org.umamo.runtime.model.RuntimeFeature
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Pins the one log line per export notice that the editor's log and the command-line tool's report share.
*
* The line is a diagnostic surface read off a bug report, so it has to name what it is about and stay
* short: a finding over a whole rig can list hundreds of drawables, and the line names the first few and
* counts the rest instead of burying every other line of the log.
*/
class ExportNoticeDescriptionTest {
@Test
fun anUnsupportedChangeNamesItsCategoryItsSubjectAndItsReason() {
val onAnEntity = ExportNotice.UnsupportedChange(ExportEntityCategory.Drawable, "ArtMesh12", ExportNoticeReason.DrawableHasNoMesh)
val onTheDocument = ExportNotice.UnsupportedChange(ExportEntityCategory.Document, null, ExportNoticeReason.NoAuthoredWorldOrigin)
assertEquals("[Drawable] ArtMesh12: DrawableHasNoMesh", describeExportNotice(onAnEntity))
assertEquals("[Document] NoAuthoredWorldOrigin", describeExportNotice(onTheDocument), "a document-level finding has no subject to name")
}
@Test
fun aLongSubjectListNamesTheFirstEightAndCountsTheRest() {
val names = (1..11).map { index -> "Mesh$index" }
val stripped = describeExportNotice(ExportNotice.FeatureStripped(RuntimeFeature.ReversedMask, names))
val twins = describeExportNotice(ExportNotice.SharedAtlasSlotKept(names))
for (line in listOf(stripped, twins)) {
assertTrue(line.contains("Mesh8"), line)
assertTrue(!line.contains("Mesh9"), line)
assertTrue(line.contains("(+3 more)"), line)
}
assertTrue(stripped.startsWith("ReversedMask "), stripped)
}
@Test
fun aShortSubjectListIsNamedInFull() {
val line = describeExportNotice(ExportNotice.WeldDivergence(listOf("Hair", "Brow")))
assertEquals("weld divergence on Hair, Brow", line)
}
}
@@ -0,0 +1,54 @@
package org.umamo.interop
import org.umamo.runtime.model.FormChannel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* Pins the structural rendering [ExportNoticeReason] promises its log mirror.
*
* The app logs each notice with the reason's own `toString()` rather than a hand-written English
* sentence, so that the diagnostic surface cannot drift from the case list the way a second copy of
* the prose would. That only works while every case is a `data object` or `data class` - a bare
* `object` would print an identity hash - and while no field's own `toString()` is an identity one.
* These tests fail the moment either holds false.
*/
class ExportNoticeReasonTest {
@Test
fun anArgumentFreeReasonPrintsItsCaseName() {
assertEquals(
"NoMatchingSourceToReconcile",
ExportNoticeReason.NoMatchingSourceToReconcile.toString(),
)
assertEquals("DrawableHasNoMesh", ExportNoticeReason.DrawableHasNoMesh.toString())
assertEquals("NoAuthoredWorldOrigin", ExportNoticeReason.NoAuthoredWorldOrigin.toString())
}
@Test
fun aParameterizedReasonPrintsItsFieldsByName() {
val truncated = ExportNoticeReason.IdTruncated(recordByteWidth = 64, writtenId = "Param01")
assertTrue(truncated.toString().contains("writtenId=Param01"), truncated.toString())
assertTrue(truncated.toString().contains("recordByteWidth=64"), truncated.toString())
val reordered = ExportNoticeReason.CombinedPairReordered("ParamAngleX", "ParamAngleY")
assertTrue(reordered.toString().contains("ParamAngleX"), reordered.toString())
assertTrue(reordered.toString().contains("ParamAngleY"), reordered.toString())
}
@Test
fun aNestedRejectionPrintsThroughItsWrapper() {
// KeyformCannotBundle is the one case carrying another sealed type, so its log line depends on
// KeyformBundleRejection honoring the same data-class rule.
val nested =
ExportNoticeReason.KeyformCannotBundle(
KeyformBundleRejection.KeysOutsideChannelSpan(FormChannel.OPACITY),
)
assertTrue(nested.toString().contains("OPACITY"), nested.toString())
assertTrue(nested.toString().contains("KeysOutsideChannelSpan"), nested.toString())
assertEquals(
"KeysOutsideGeometrySpan",
KeyformBundleRejection.KeysOutsideGeometrySpan.toString(),
)
}
}
@@ -0,0 +1,218 @@
package org.umamo.interop
import org.umamo.runtime.keyform.ChannelValueInterpolator
import org.umamo.runtime.keyform.FormInterpolator
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.ParameterId
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* The shared re-bundler's contract, and in particular the two [OutOfSpanPolicy] branches.
*
* The out-of-span case is the one worth pinning: a channel keyed over a NARROWER span than the union
* cannot be placed in the bundled grid without inventing values at the keys it never covered. CMO3
* declines the whole owner; MOC3 cannot, because a MOC3 object with no keyform produces a file the
* runtime will not load, so it drops that one channel to its static instead. Both branches are
* exercised here because each caller only ever reaches its own - `Cmo3KeyformLowering` never passes
* DemoteChannel and `Moc3KeyformLowering` never passes RejectOwner - so neither format's own gates
* can catch a regression in the other's policy.
*/
class KeyformBundleTest {
private val angleX = ParameterId("ParamAngleX")
/**
* A single-axis channel track over [keys] with a distinct scalar per key.
*
* @param FloatArray keys The axis key positions.
* @return KeyformGrid<ChannelValue> The track.
*/
private fun track(keys: FloatArray): KeyformGrid<ChannelValue> =
KeyformGrid(
listOf(KeyformAxis(angleX, keys)),
keys.indices.map { keyIndex ->
KeyformCell(intArrayOf(keyIndex), ChannelValue.Scalar(keyIndex.toFloat()))
},
)
/**
* A geometry grid over [keys], carrying the key index as its form so cells stay identifiable.
*
* @param FloatArray keys The axis key positions.
* @return KeyformGrid<Float> The grid.
*/
private fun geometry(keys: FloatArray): KeyformGrid<Float> =
KeyformGrid(
listOf(KeyformAxis(angleX, keys)),
keys.indices.map { keyIndex -> KeyformCell(intArrayOf(keyIndex), keyIndex.toFloat()) },
)
/** A float interpolator, so the geometry can be refined onto the union like a real payload. */
private val floatBlend =
object : FormInterpolator<Float> {
override fun interpolate(lower: Float, upper: Float, fraction: Float): Float =
lower + (upper - lower) * fraction
override fun isExactlyEqual(left: Float, right: Float): Boolean = left == right
}
private val statics = mapOf(FormChannel.OPACITY to ChannelValue.Scalar(1f))
/** Geometry spanning -30..30 with a channel keyed only over the NARROWER -10..10. */
private fun outOfSpanInputs(): Pair<KeyformGrid<Float>, ChannelGrids> =
geometry(floatArrayOf(-30f, 0f, 30f)) to
ChannelGrids(mapOf(FormChannel.OPACITY to track(floatArrayOf(-10f, 0f, 10f))))
@Test
fun rejectOwnerRefusesAChannelKeyedOutsideTheUnionSpan() {
val (geometryGrid, channels) = outOfSpanInputs()
val result =
buildKeyformBundle(
geometryGrid,
floatBlend,
channels,
statics,
requireGeometry = false,
outOfSpanPolicy = OutOfSpanPolicy.RejectOwner,
)
assertTrue(result is KeyformBundleResult.Unrepresentable, "an out-of-span channel rejects the owner")
val rejection = result.rejection
assertTrue(
rejection is KeyformBundleRejection.KeysOutsideChannelSpan &&
rejection.channel == FormChannel.OPACITY,
"the rejection names the offending channel: $rejection",
)
}
@Test
fun demoteChannelKeepsTheOwnerAndNamesWhatItDropped() {
val (geometryGrid, channels) = outOfSpanInputs()
val result =
buildKeyformBundle(
geometryGrid,
floatBlend,
channels,
statics,
requireGeometry = false,
outOfSpanPolicy = OutOfSpanPolicy.DemoteChannel,
)
assertTrue(result is KeyformBundleResult.Bundled, "the owner still bundles")
val bundle = result.bundle
assertEquals(listOf(FormChannel.OPACITY), bundle.demotedChannels, "the dropped channel is named")
// Every cell falls back to the static rather than to an invented interpolation.
assertTrue(bundle.cells.isNotEmpty(), "the bundle has cells")
assertTrue(
bundle.cells.all { cell -> cell.channels[FormChannel.OPACITY] == statics.getValue(FormChannel.OPACITY) },
"a demoted channel reads its static in every cell",
)
// The union is BOTH sets of keys (-30, -10, 0, 10, 30): the geometry refines onto all five
// because they fall inside its own span, which is precisely why the narrower channel cannot -
// it would have to invent values at -30 and 30. Demoting it does not shrink the grid.
assertEquals(5, bundle.cells.size, "the union keeps every key from both sides")
assertEquals(
listOf(-30f, -10f, 0f, 10f, 30f),
bundle.axes.single().keys.toList(),
"the union axis carries both key sets",
)
}
@Test
fun bothPoliciesAgreeWhenNothingIsOutOfSpan() {
val geometryGrid = geometry(floatArrayOf(-30f, 0f, 30f))
val channels = ChannelGrids(mapOf(FormChannel.OPACITY to track(floatArrayOf(-30f, 0f, 30f))))
val bundles =
listOf(OutOfSpanPolicy.RejectOwner, OutOfSpanPolicy.DemoteChannel).map { policy ->
val result =
buildKeyformBundle(geometryGrid, floatBlend, channels, statics, false, policy)
assertTrue(result is KeyformBundleResult.Bundled, "$policy bundles an in-span owner")
result.bundle
}
val (rejectBundle, demoteBundle) = bundles
assertEquals(emptyList(), rejectBundle.demotedChannels, "nothing is demoted when nothing is out of span")
assertEquals(emptyList(), demoteBundle.demotedChannels, "nothing is demoted when nothing is out of span")
assertEquals(rejectBundle.cells.size, demoteBundle.cells.size, "the policies produce the same grid")
for (cellIndex in rejectBundle.cells.indices) {
assertEquals(
rejectBundle.cells[cellIndex].channels,
demoteBundle.cells[cellIndex].channels,
"cell $cellIndex agrees across policies",
)
}
}
@Test
fun aFullyUnkeyedOwnerBundlesToNothing() {
val result =
buildKeyformBundle(
null as KeyformGrid<Float>?,
floatBlend,
ChannelGrids.Empty,
statics,
requireGeometry = false,
outOfSpanPolicy = OutOfSpanPolicy.RejectOwner,
)
assertTrue(result is KeyformBundleResult.Bundled, "an unkeyed owner is not an error")
assertEquals(emptyList(), result.bundle.axes, "no axes")
assertEquals(emptyList(), result.bundle.cells, "no cells")
}
@Test
fun geometryRequiredMeansAChannelOnlyOwnerIsUnrepresentable() {
val channels = ChannelGrids(mapOf(FormChannel.OPACITY to track(floatArrayOf(-10f, 10f))))
val result =
buildKeyformBundle(
null as KeyformGrid<Float>?,
floatBlend,
channels,
statics,
requireGeometry = true,
outOfSpanPolicy = OutOfSpanPolicy.DemoteChannel,
)
// Not demotable: a warp or rotation with keyed channels but no lattice has nothing to write.
assertTrue(result is KeyformBundleResult.Unrepresentable, "geometry-less is an error when required")
}
/**
* An AXIS-LESS channel track still carries its value, and that value beats the owner's static.
*
* A track can be a single cell with no axes - an authored constant that was never lifted into the
* static - and the static in that state still holds an untouched default. The early return for
* "no keys anywhere" used to fill channels straight from the statics, which silently replaced every
* such value; a MOC3 export of an uncompacted import wrote 1.0 opacity over an authored 0.66.
*/
@Test
fun anAxisLessChannelTrackBeatsTheStatic() {
val authored: ChannelValue = ChannelValue.Scalar(0.66f)
val axisLessTrack = KeyformGrid(emptyList<KeyformAxis>(), listOf(KeyformCell(IntArray(0), authored)))
val result =
buildKeyformBundle(
KeyformGrid(emptyList<KeyformAxis>(), listOf(KeyformCell(IntArray(0), 0f))),
floatBlend,
ChannelGrids(mapOf(FormChannel.OPACITY to axisLessTrack)),
// The static is the constructor default the import leaves behind when nothing lifted it.
mapOf(FormChannel.OPACITY to ChannelValue.Scalar(1f)),
requireGeometry = false,
outOfSpanPolicy = OutOfSpanPolicy.DemoteChannel,
)
assertTrue(result is KeyformBundleResult.Bundled, "an axis-less owner still bundles")
assertEquals(1, result.bundle.cells.size, "one static cell")
assertEquals(
authored,
result.bundle.cells.single().channels[FormChannel.OPACITY],
"the track's authored value wins over the static",
)
}
/** Guards the interpolator the other cases lean on, so a failure there reads as its own cause. */
@Test
fun channelValueInterpolatorBlendsScalars() {
val blended = ChannelValueInterpolator.interpolate(ChannelValue.Scalar(0f), ChannelValue.Scalar(10f), 0.25f)
assertEquals(ChannelValue.Scalar(2.5f), blended)
}
}
@@ -0,0 +1,447 @@
package org.umamo.interop
import org.umamo.runtime.model.ArtSource
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.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.Deformer
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.GluePair
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.ParameterNode
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.RuntimeTarget
import org.umamo.runtime.model.SourceLayerRef
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
import kotlin.test.fail
/**
* Pins diffPuppetModels' contract directly - the reconcile backbone every CMO3 export round-trip
* test exercises only end to end. Covers each category's Created/Deleted set-difference, the exact
* Changed field sets (ParameterField and GlueField exhaustively; representative shallow/deep/
* reference fields for parts, deformers, and drawables), the glue ordered-pair + ordinal keying,
* bit-exact float comparison, and baseline-order emission.
*/
class PuppetModelDiffTest {
private val angleX = ParameterId("ParamAngleX")
private fun parameter(id: String, min: Float = -1f, max: Float = 1f, default: Float = 0f): Parameter =
Parameter(ParameterId(id), id, min = min, max = max, default = default)
/** A one-triangle drawable with no keyforms and no deformer parent. */
private fun drawable(id: String): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh =
DrawableMesh(
positions = floatArrayOf(0f, 0f, 10f, 0f, 0f, 10f),
uvs = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f),
indices = intArrayOf(0, 1, 2),
),
geometryGrid = null,
)
private fun part(id: String): Part = Part(id = PartId(id), name = id, children = emptyList())
/** A one-axis mesh-delta grid on angleX whose single interesting delta is [firstDelta]. */
private fun deltaGrid(firstDelta: Float): KeyformGrid<MeshDeltaForm> =
KeyformGrid(
listOf(KeyformAxis(angleX, floatArrayOf(0f, 1f))),
listOf(
KeyformCell(intArrayOf(0), MeshDeltaForm(floatArrayOf(0f, 0f, 0f, 0f, 0f, 0f))),
KeyformCell(intArrayOf(1), MeshDeltaForm(floatArrayOf(firstDelta, 0f, 0f, 0f, 0f, 0f))),
),
)
/** A one-axis opacity track on angleX ending at [lastValue]. */
private fun opacityTrack(lastValue: Float): ChannelGrids =
ChannelGrids(
mapOf(
FormChannel.OPACITY to
KeyformGrid(
listOf(KeyformAxis(angleX, floatArrayOf(0f, 1f))),
listOf(
KeyformCell(intArrayOf(0), ChannelValue.Scalar(1f) as ChannelValue),
KeyformCell(intArrayOf(1), ChannelValue.Scalar(lastValue)),
),
),
),
)
/**
* A minimal model over explicit entity lists. rootChildren stays empty on purpose, so mutating an
* entity list never doubles as a ROOT_CHILDREN document diff.
*/
private fun puppet(
parameters: List<Parameter> = emptyList(),
parts: List<Part> = emptyList(),
deformers: List<Deformer> = emptyList(),
drawables: List<Drawable> = emptyList(),
glues: List<Glue> = emptyList(),
parameterTree: List<ParameterNode> = emptyList(),
): PuppetModel =
PuppetModel(
parameters = parameters,
parts = parts,
deformers = deformers,
drawables = drawables,
rootChildren = emptyList(),
rootPartId = null,
glues = glues,
parameterTree = parameterTree,
canvasWidth = 100f,
canvasHeight = 100f,
)
/** The field set of a category's single Changed entry, asserting it is the only diff. */
private fun <TId, TField> onlyChangedFields(diffs: List<EntityDiff<TId, TField>>): Set<TField> {
assertEquals(1, diffs.size)
return when (val entry = diffs.single()) {
is EntityDiff.Changed -> entry.fields
else -> fail("expected a Changed entry, got $entry")
}
}
/** The same instance on both sides is semantically identical. */
@Test
fun identicalModelInstanceProducesEmptyDiff() {
val model = puppet(parameters = listOf(parameter("ParamA")), drawables = listOf(drawable("d1")))
assertTrue(diffPuppetModels(model, model).isEmpty)
}
/** Field-equal copies (fresh instances) still diff empty - equality is by value, not identity. */
@Test
fun fieldEqualCopyProducesEmptyDiff() {
val baseline = puppet(parameters = listOf(parameter("ParamA")), drawables = listOf(drawable("d1")))
val edited = baseline.copy(drawables = baseline.drawables.map { entity -> entity.copy() })
assertTrue(diffPuppetModels(baseline, edited).isEmpty)
}
/** Creation and deletion are id set-difference: one-sided ids yield Created/Deleted entries. */
@Test
fun parameterCreatedAndDeletedById() {
val kept = parameter("ParamKept")
val baseline = puppet(parameters = listOf(kept, parameter("ParamGone")))
val edited = puppet(parameters = listOf(kept, parameter("ParamNew")))
val diff = diffPuppetModels(baseline, edited)
assertEquals(
listOf(EntityDiff.Deleted(ParameterId("ParamGone")), EntityDiff.Created(ParameterId("ParamNew"))),
diff.parameters,
)
}
/** Each ParameterField flags exactly its own edit - the full enum, one field per case. */
@Test
fun parameterChangedFieldsAreExact() {
val baseline = puppet(parameters = listOf(parameter("ParamA")))
fun fieldsAfter(edit: (Parameter) -> Parameter): Set<ParameterField> =
onlyChangedFields(diffPuppetModels(baseline, puppet(parameters = listOf(edit(baseline.parameters.single())))).parameters)
assertEquals(setOf(ParameterField.NAME), fieldsAfter { entity -> entity.copy(name = "Renamed") })
assertEquals(setOf(ParameterField.RANGE), fieldsAfter { entity -> entity.copy(max = 2f) })
assertEquals(setOf(ParameterField.KIND), fieldsAfter { entity -> entity.copy(kind = ParameterKind.BLEND_SHAPE) })
}
/** A one-ULP float nudge is a reported change - the diff is bit-exact, never tolerance-based. */
@Test
fun oneUlpFloatDifferenceIsReported() {
val baseline = puppet(parameters = listOf(parameter("ParamA", min = 0.5f)))
val nudgedMin = Float.fromBits(0.5f.toRawBits() + 1)
val edited = puppet(parameters = listOf(baseline.parameters.single().copy(min = nudgedMin)))
assertEquals(setOf(ParameterField.RANGE), onlyChangedFields(diffPuppetModels(baseline, edited).parameters))
}
/** A group rename flags only that group; its unchanged identity keeps the document tree quiet. */
@Test
fun parameterGroupChangedFieldsAreExact() {
val groupId = ParameterGroupId("Group1")
fun treeOf(group: ParameterNode.Group): List<ParameterNode> = listOf(group)
val baselineGroup = ParameterNode.Group(groupId, "Face", initiallyOpen = true, children = listOf(ParameterNode.Param(angleX)))
val baseline = puppet(parameterTree = treeOf(baselineGroup))
fun diffAfter(edited: ParameterNode.Group): PuppetDiff = diffPuppetModels(baseline, puppet(parameterTree = treeOf(edited)))
val renamed = diffAfter(baselineGroup.copy(name = "Body"))
assertEquals(setOf(ParameterGroupField.NAME), onlyChangedFields(renamed.parameterGroups))
assertEquals(emptySet(), renamed.document, "a rename keeps the tree's identity sequence")
val collapsed = diffAfter(baselineGroup.copy(initiallyOpen = false))
assertEquals(setOf(ParameterGroupField.INITIALLY_OPEN), onlyChangedFields(collapsed.parameterGroups))
val emptied = diffAfter(baselineGroup.copy(children = emptyList()))
assertEquals(setOf(ParameterGroupField.CHILDREN), onlyChangedFields(emptied.parameterGroups))
assertEquals(emptySet(), emptied.document, "group content is reported per group, not as a tree change")
}
/** Adding a group is a Created entry AND a document tree change - the top level gained a node. */
@Test
fun parameterGroupCreatedFlagsTheDocumentTree() {
val baseline = puppet(parameterTree = listOf(ParameterNode.Param(angleX)))
val added = ParameterNode.Group(ParameterGroupId("Group1"), "Face", initiallyOpen = true, children = emptyList())
val diff = diffPuppetModels(baseline, puppet(parameterTree = listOf(ParameterNode.Param(angleX), added)))
assertEquals(listOf<EntityDiff<ParameterGroupId, ParameterGroupField>>(EntityDiff.Created(added.id)), diff.parameterGroups)
assertEquals(setOf(DocumentField.PARAMETER_TREE), diff.document)
}
/** Part diffs: a shallow scalar (NAME), a reference list (CHILDREN), plus Created and Deleted. */
@Test
fun partChangesAndSetDifference() {
val keptPart = part("PartKept")
val editablePart = part("PartEdited")
val baseline = puppet(parts = listOf(keptPart, editablePart, part("PartGone")))
val edited =
puppet(
parts =
listOf(
keptPart,
editablePart.copy(name = "Renamed", children = listOf(OrgChild.Drawable(DrawableId("d1")))),
part("PartNew"),
),
)
val diff = diffPuppetModels(baseline, edited)
assertEquals(
listOf(
EntityDiff.Changed(editablePart.id, setOf(PartField.NAME, PartField.CHILDREN)),
EntityDiff.Deleted(PartId("PartGone")),
EntityDiff.Created(PartId("PartNew")),
),
diff.parts,
)
}
/** Deformer diffs: warp lattice/geometry/statics fields, and a kind swap reports only KIND. */
@Test
fun deformerChangesAndKindSwap() {
val warp =
Deformer.Warp(
id = DeformerId("Warp1"),
name = "Warp1",
parent = null,
partId = null,
rows = 2,
columns = 2,
isQuadTransform = false,
geometryGrid = null,
)
val baseline = puppet(deformers = listOf(warp))
fun fieldsAfter(edited: Deformer): Set<DeformerField> =
onlyChangedFields(diffPuppetModels(baseline, puppet(deformers = listOf(edited))).deformers)
assertEquals(setOf(DeformerField.LATTICE), fieldsAfter(warp.copy(rows = 3)))
assertEquals(setOf(DeformerField.STATICS), fieldsAfter(warp.copy(opacity = 0.5f)))
assertEquals(setOf(DeformerField.PARENT), fieldsAfter(warp.copy(parent = DeformerId("Other"))))
val rotationUnderSameId =
Deformer.Rotation(
id = warp.id,
name = warp.name,
parent = null,
partId = null,
baseAngle = 0f,
geometryGrid = null,
)
assertEquals(setOf(DeformerField.KIND), fieldsAfter(rotationUnderSameId), "a kind swap short-circuits the field walk")
}
/** Drawable diffs: geometry grid, channel tracks, and the topology-vs-positions mesh split. */
@Test
fun drawableChangedFieldsAreExact() {
val gridded = drawable("d1").copy(geometryGrid = deltaGrid(1f), channelGrids = opacityTrack(0.5f))
val baseline = puppet(drawables = listOf(gridded))
fun fieldsAfter(edited: Drawable): Set<DrawableField> =
onlyChangedFields(diffPuppetModels(baseline, puppet(drawables = listOf(edited))).drawables)
assertEquals(setOf(DrawableField.BLEND_MODE), fieldsAfter(gridded.copy(blendMode = BlendMode.Multiply)))
assertEquals(setOf(DrawableField.GEOMETRY), fieldsAfter(gridded.copy(geometryGrid = deltaGrid(2f))))
assertEquals(setOf(DrawableField.CHANNELS), fieldsAfter(gridded.copy(channelGrids = opacityTrack(0.25f))))
val mesh = gridded.mesh!!
val movedVertex =
DrawableMesh(
positions = floatArrayOf(0f, 0f, 10f, 0f, 5f, 10f),
uvs = mesh.uvs,
indices = mesh.indices,
)
assertEquals(setOf(DrawableField.MESH_POSITIONS), fieldsAfter(gridded.copy(mesh = movedVertex)))
val rewound =
DrawableMesh(
positions = mesh.positions,
uvs = mesh.uvs,
indices = intArrayOf(2, 1, 0),
)
assertEquals(setOf(DrawableField.MESH_TOPOLOGY), fieldsAfter(gridded.copy(mesh = rewound)))
}
/** A glue is keyed by its ORDERED mesh pair - reversing the pair is a delete plus a create. */
@Test
fun glueKeyedByOrderedPairAndOrdinal() {
val meshA = DrawableId("a")
val meshB = DrawableId("b")
val weld = Glue(meshA, meshB, listOf(GluePair(0, 0, 0.5f, 0.5f)))
val baseline = puppet(drawables = listOf(drawable("a"), drawable("b")), glues = listOf(weld))
val reversed = puppet(drawables = baseline.drawables, glues = listOf(Glue(meshB, meshA, weld.pairs)))
assertEquals(
setOf(GlueDiff.Deleted(meshA, meshB, 0), GlueDiff.Created(meshB, meshA, 0)),
diffPuppetModels(baseline, reversed).glues.toSet(),
)
val doubled = puppet(drawables = baseline.drawables, glues = listOf(weld, Glue(meshA, meshB, weld.pairs)))
assertEquals(listOf(GlueDiff.Created(meshA, meshB, 1)), diffPuppetModels(baseline, doubled).glues)
}
/** Each GlueField flags exactly its own edit - the full enum, one field per case. */
@Test
fun glueChangedFieldsAreExact() {
val meshA = DrawableId("a")
val meshB = DrawableId("b")
val weld = Glue(meshA, meshB, listOf(GluePair(0, 0, 0.5f, 0.5f)))
val baseline = puppet(drawables = listOf(drawable("a"), drawable("b")), glues = listOf(weld))
fun fieldsAfter(edited: Glue): Set<GlueField> {
val diff = diffPuppetModels(baseline, puppet(drawables = baseline.drawables, glues = listOf(edited))).glues
return (diff.single() as GlueDiff.Changed).fields
}
assertEquals(setOf(GlueField.PAIRS), fieldsAfter(Glue(meshA, meshB, listOf(GluePair(0, 0, 0.9f, 0.5f)))))
assertEquals(setOf(GlueField.INTENSITY), fieldsAfter(Glue(meshA, meshB, weld.pairs, intensity = 0.5f)))
assertEquals(setOf(GlueField.CHANNELS), fieldsAfter(Glue(meshA, meshB, weld.pairs, channelGrids = opacityTrack(0.5f))))
}
/** Document-level edits flag their own field and nothing else. */
@Test
fun documentFieldChangesAreExact() {
val baseline = puppet(parameters = listOf(parameter("ParamA"), parameter("ParamB")))
val resized = diffPuppetModels(baseline, baseline.copy(canvasWidth = 200f))
assertEquals(setOf(DocumentField.CANVAS_SIZE), resized.document)
assertTrue(resized.parameters.isEmpty())
val retargeted = diffPuppetModels(baseline, baseline.copy(runtimeTarget = RuntimeTarget.entries.first { target -> target != RuntimeTarget.NoTarget }))
assertEquals(setOf(DocumentField.RUNTIME_TARGET), retargeted.document)
val reordered = diffPuppetModels(baseline, baseline.copy(parameters = baseline.parameters.reversed()))
assertEquals(setOf(DocumentField.PARAMETER_ORDER), reordered.document)
assertTrue(reordered.parameters.isEmpty(), "a pure reorder changes no parameter entity")
}
/**
* A moved placement surfaces as exactly that tile's PLACEMENT, and nothing else.
*
* The completeness rule bites hardest here: an atlas change the diff misses is an atlas change the
* export silently drops, and a placement the file keeps while the model moved on leaves every mesh
* over it sampling the wrong pixels.
*/
@Test
fun atlasTileChangesAreExact() {
val tileId = AtlasTileId("tile0")
val placed = AtlasPlacement(0, 4f, 8f, scaleX = 1f, scaleY = 1f, rotationDegrees = 0f)
val baseline =
puppet().copy(
atlas = PuppetAtlas(listOf(AtlasPage(64, 64)), listOf(AtlasTile(tileId, "Art", 16, 16, placed))),
)
val moved =
diffPuppetModels(
baseline,
baseline.copy(atlas = baseline.atlas.copy(tiles = listOf(baseline.atlas.tiles.single().copy(placement = placed.copy(positionX = 40f))))),
)
assertEquals(
listOf(EntityDiff.Changed(tileId, setOf(AtlasTileField.PLACEMENT))),
moved.atlasTiles,
)
assertTrue(moved.document.isEmpty(), "moving art on a page changes no document field")
assertTrue(moved.drawables.isEmpty(), "and no drawable, when none is bound to it")
val renamed =
diffPuppetModels(
baseline,
baseline.copy(atlas = baseline.atlas.copy(tiles = listOf(baseline.atlas.tiles.single().copy(name = "Other")))),
)
assertEquals(listOf(EntityDiff.Changed(tileId, setOf(AtlasTileField.METADATA))), renamed.atlasTiles)
// A source binding is what the art IS, so rebinding it reads as metadata like a rename does.
val rebound =
diffPuppetModels(
baseline,
baseline.copy(
atlas =
baseline.atlas.copy(
tiles = listOf(baseline.atlas.tiles.single().copy(source = SourceLayerRef(ArtSourceId("art-0"), "lyid:3", stableKey = true))),
),
),
)
assertEquals(listOf(EntityDiff.Changed(tileId, setOf(AtlasTileField.METADATA))), rebound.atlasTiles)
val repaged = diffPuppetModels(baseline, baseline.copy(atlas = baseline.atlas.copy(pages = listOf(AtlasPage(128, 128)))))
val record = ArtSource(ArtSourceId("art-0"), "a.psd", "/a.psd", "psd", listOf(ArtSourceLayer("lyid:3", "L", "", 0, 0, 4, 4, true)))
val listed = baseline.copy(sources = listOf(record))
val relinked = diffPuppetModels(listed, listed.copy(sources = listOf(record.copy(path = "/elsewhere/a.psd"))))
assertEquals(setOf(DocumentField.SOURCE_FILES), relinked.document, "a source record pointing at another file is a document change")
val reloaded = diffPuppetModels(listed, listed.copy(sources = listOf(record.copy(contentHash = "other", layers = emptyList()))))
assertTrue(DocumentField.SOURCE_FILES !in reloaded.document, "a reload's inventory and hash are not")
val touched = diffPuppetModels(listed, listed.copy(sources = listOf(record.copy(lastModified = 123L))))
assertEquals(setOf(DocumentField.SOURCE_FILES), touched.document, "the file's modification time is, since the CMO3 keeps it")
val foreign = diffPuppetModels(listed, listed.copy(sources = listOf(record.copy(id = ArtSourceId("page-0"), name = "page-0.png", path = null))))
assertTrue(DocumentField.SOURCE_FILES !in foreign.document, "a record only one side lists (a fresh synthesis's page slices, art added this session) is not a repointed file")
assertEquals(setOf(DocumentField.ATLAS_PAGES), repaged.document, "the page list is document-level")
assertTrue(repaged.atlasTiles.isEmpty(), "resizing a page moves no tile")
assertTrue(diffPuppetModels(baseline, baseline).isEmpty, "an untouched atlas is no difference at all")
}
/** Rebinding a drawable to different art is a drawable-level difference the export must see. */
@Test
fun aDrawableRetiedToDifferentArtSurfaces() {
val baseline = puppet(drawables = listOf(drawable("D1").copy(atlasTileId = AtlasTileId("tile0"))))
val rebound =
diffPuppetModels(
baseline,
baseline.copy(drawables = listOf(baseline.drawables.single().copy(atlasTileId = AtlasTileId("tile1")))),
)
assertEquals(
listOf(EntityDiff.Changed(DrawableId("D1"), setOf(DrawableField.ATLAS_TILE))),
rebound.drawables,
)
}
/** Diffs emit in BASELINE order regardless of the edited list's order, with creations appended. */
@Test
fun changedEntitiesEmitInBaselineOrder() {
val partA = part("PartA")
val partB = part("PartB")
val partC = part("PartC")
val baseline = puppet(parts = listOf(partA, partB, partC))
val edited =
puppet(
parts =
listOf(
part("PartNew"),
partC.copy(name = "RenamedC"),
partA,
partB.copy(name = "RenamedB"),
),
)
val diff = diffPuppetModels(baseline, edited)
assertEquals(listOf(PartId("PartB"), PartId("PartC"), PartId("PartNew")), diff.parts.map { entry -> entry.id })
}
}
@@ -0,0 +1,84 @@
package org.umamo.interop
import org.umamo.format.cmo3.Cmo3TargetVersion
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.runtime.model.RuntimeTarget
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNull
/**
* Pins the RuntimeTarget ↔ format-version mapping per version boundary: the moc version each
* target bakes, the CMO3 target version each target persists as, and the target each decoded
* version selects on ingest. (The capability matrix itself is pinned in :runtime's
* RuntimeTargetTest.)
*/
class RuntimeTargetMappingTest {
@Test
fun mocVersionsMatchEachTargetsLevel() {
assertEquals(MocVersion.V53, RuntimeTarget.NoTarget.mocVersion(), "nothing restricted, bake latest")
assertEquals(MocVersion.V50, RuntimeTarget.Ayagami.mocVersion(), "Ayagami's effective level")
assertEquals(MocVersion.V30, RuntimeTarget.Cubism30.mocVersion())
assertEquals(MocVersion.V33, RuntimeTarget.Cubism33.mocVersion())
assertEquals(MocVersion.V40, RuntimeTarget.Cubism40.mocVersion())
assertEquals(MocVersion.V42, RuntimeTarget.Cubism42.mocVersion())
assertEquals(MocVersion.V50, RuntimeTarget.Cubism50.mocVersion())
assertEquals(MocVersion.V53, RuntimeTarget.Cubism53.mocVersion())
}
@Test
fun cmo3TargetVersionsRoundTripPerTarget() {
assertNull(RuntimeTarget.NoTarget.cmo3TargetVersion(), "NoTarget has no target VERSION, only the sentinel")
assertEquals(
RuntimeTarget.Cubism50.cmo3TargetVersion(),
RuntimeTarget.Ayagami.cmo3TargetVersion(),
"Ayagami persists at its effective Cubism level",
)
val cubismTargets =
listOf(
RuntimeTarget.Cubism30,
RuntimeTarget.Cubism33,
RuntimeTarget.Cubism40,
RuntimeTarget.Cubism42,
RuntimeTarget.Cubism50,
RuntimeTarget.Cubism53,
)
cubismTargets.forEach { target ->
assertEquals(target, runtimeTargetOfCmo3Target(target.cmo3TargetVersion()), "round trip for $target")
}
// Ayagami's identity cannot survive CMO3 - it reopens as its effective Cubism level.
assertEquals(RuntimeTarget.Cubism50, runtimeTargetOfCmo3Target(RuntimeTarget.Ayagami.cmo3TargetVersion()))
}
@Test
fun persistedVersionNoCoversEveryTarget() {
assertEquals(
Cmo3TargetVersion.LATEST_VERSION_NO,
RuntimeTarget.NoTarget.cmo3TargetVersionNo(),
"NoTarget persists as the SDK(N/A)/Latest sentinel",
)
assertEquals(5_000_000, RuntimeTarget.Ayagami.cmo3TargetVersionNo(), "Ayagami persists as Cubism 5.0")
assertEquals(4_020_000, RuntimeTarget.Cubism42.cmo3TargetVersionNo(), "a Cubism target persists its literal")
// The sentinel round-trips through ingest: it decodes to no version, which maps to NoTarget.
assertEquals(
RuntimeTarget.NoTarget,
runtimeTargetOfCmo3Target(Cmo3TargetVersion.fromVersionNo(RuntimeTarget.NoTarget.cmo3TargetVersionNo())),
)
}
@Test
fun unknownCmo3TargetFallsBackToNoTarget() {
assertEquals(RuntimeTarget.NoTarget, runtimeTargetOfCmo3Target(null))
assertEquals(RuntimeTarget.Cubism42, runtimeTargetOfCmo3Target(Cmo3TargetVersion.V42))
}
@Test
fun mocVersionsMapToTheirCubismTargets() {
assertEquals(RuntimeTarget.Cubism30, runtimeTargetOfMocVersion(MocVersion.V30))
assertEquals(RuntimeTarget.Cubism33, runtimeTargetOfMocVersion(MocVersion.V33))
assertEquals(RuntimeTarget.Cubism40, runtimeTargetOfMocVersion(MocVersion.V40))
assertEquals(RuntimeTarget.Cubism42, runtimeTargetOfMocVersion(MocVersion.V42))
assertEquals(RuntimeTarget.Cubism50, runtimeTargetOfMocVersion(MocVersion.V50))
assertEquals(RuntimeTarget.Cubism53, runtimeTargetOfMocVersion(MocVersion.V53))
}
}
@@ -0,0 +1,492 @@
package org.umamo.interop.art
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
import org.umamo.runtime.model.ArtSource
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.OrgInsertion
import org.umamo.runtime.model.OrgSlot
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterNode
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.SourceLayerRef
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertSame
import kotlin.test.assertTrue
/**
* Pins what the bridge makes of a layered document: which layers become drawables and which are
* skipped with a note, the birth quad's geometry in both frames, the clipping and blend mappings, the
* folder-to-part tree with its order and its composites, the tiles and their source bindings, the
* source inventory, and the seeded parameters. Synthetic art throughout - the corpus twin is
* SourceArtImportCorpusTest.
*/
class SourceArtImportTest {
private class FixtureLayer(
override val id: LayerId,
override val idIsStable: Boolean,
override val name: String,
override val groupPath: String,
override val order: Int,
override val bounds: LayerBounds,
override val raster: LayerRaster,
override val kind: SourceLayerKind = SourceLayerKind.Raster,
override val visible: Boolean = true,
override val opacity: Float = 1f,
override val clipped: Boolean = false,
override val blend: LayerBlend = LayerBlend.Normal,
) : SourceLayer
private class FixtureGroup(
override val path: String,
override val name: String,
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,
) : SourceGroup
private class FixtureArt(
override val widthPx: Int,
override val heightPx: Int,
override val layers: List<SourceLayer>,
override val groups: List<SourceGroup> = emptyList(),
) : SourceArt
/** A raster opaque inside [opaque] (raster-local) and transparent elsewhere; fully transparent when null. */
private fun rasterOf(width: Int, height: Int, opaque: LayerBounds? = LayerBounds(0, 0, width, height)): LayerRaster {
val rgba = ByteArray(width * height * 4)
if (opaque != null) {
for (row in opaque.top until opaque.top + opaque.height) {
for (column in opaque.left until opaque.left + opaque.width) {
rgba[(row * width + column) * 4 + 3] = 0xFF.toByte()
}
}
}
return LayerRaster(width, height, rgba)
}
private fun layer(
id: String,
name: String,
order: Int,
left: Int,
top: Int,
raster: LayerRaster,
groupPath: String = "",
stable: Boolean = true,
kind: SourceLayerKind = SourceLayerKind.Raster,
visible: Boolean = true,
opacity: Float = 1f,
clipped: Boolean = false,
blend: LayerBlend = LayerBlend.Normal,
): FixtureLayer =
FixtureLayer(
id = LayerId(id),
idIsStable = stable,
name = name,
groupPath = groupPath,
order = order,
bounds = LayerBounds(left, top, raster.width, raster.height),
raster = raster,
kind = kind,
visible = visible,
opacity = opacity,
clipped = clipped,
blend = blend,
)
private val eyeRaster = rasterOf(10, 8, opaque = LayerBounds(2, 1, 4, 3))
/** The fixture, listed bottom-to-top the way the readers emit it; [SourceLayer.order] is what counts. */
private fun fixture(): SourceArt =
FixtureArt(
widthPx = 200,
heightPx = 100,
layers =
listOf(
layer("lyid:7", "Lonely", order = 7, left = 5, top = 5, raster = rasterOf(3, 3), groupPath = "Solo", clipped = true),
layer("lyid:6", "Hidden", order = 6, left = 20, top = 20, raster = rasterOf(5, 5), groupPath = "Body/Arm", visible = false, opacity = 0.5f),
layer("lyid:5", "Odd", order = 5, left = 10, top = 0, raster = rasterOf(6, 6), blend = LayerBlend.Difference),
layer("Glow#4", "Glow", order = 4, left = 0, top = 0, raster = rasterOf(6, 6), stable = false, blend = LayerBlend.AddGlow),
layer("lyid:3", "Empty", order = 3, left = 0, top = 0, raster = rasterOf(4, 4, opaque = null), groupPath = "Head"),
layer("lyid:2", "Face", order = 2, left = 90, top = 40, raster = rasterOf(20, 20), groupPath = "Head"),
layer("lyid:1", "Eye", order = 1, left = 100, top = 50, raster = eyeRaster, groupPath = "Head", clipped = true),
layer("lyid:0", "Title", order = 0, left = 0, top = 0, raster = rasterOf(1, 1, opaque = null), groupPath = "Head", kind = SourceLayerKind.Text),
),
groups =
listOf(
FixtureGroup("Head", "Head", visible = false),
FixtureGroup("Body", "Body", opacity = 0.5f, passThrough = false),
FixtureGroup("Body/Arm", "Arm"),
),
)
private val descriptor = ArtSourceDescriptor(name = "fixture.psd", path = "/art/fixture.psd", format = "psd")
@Test
fun rasterLayersWithArtBecomeDrawablesTopMostFirst() {
val result = SourceArtImport.fromSourceArt(fixture(), descriptor)
val puppet = result.puppet
assertEquals(listOf("Eye", "Face", "Glow", "Odd", "Hidden", "Lonely"), puppet.drawables.map { drawable -> drawable.name })
assertEquals((1..6).map { index -> DrawableId("ArtMesh$index") }, puppet.drawables.map { drawable -> drawable.id }, "ids follow the panel order")
assertEquals(
setOf(
SourceArtImportNotice.NonRasterLayer("Title", SourceLayerKind.Text),
SourceArtImportNotice.EmptyLayer("Empty"),
SourceArtImportNotice.BlendUnsupported("Odd", LayerBlend.Difference),
SourceArtImportNotice.ClipBaseMissing("Lonely"),
),
result.notices.toSet(),
"every skipped or altered layer is named, and nothing else is",
)
}
/** The quad spans the opaque bounds plus the margin, in canvas pixels and in the art's own frame. */
@Test
fun theBirthQuadIsTheOpaqueBoundsPlusTheMarginInBothFrames() {
val puppet = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val mesh = assertNotNull(puppet.drawables.first { drawable -> drawable.name == "Eye" }.mesh)
// Opaque (2, 1) 4x3 in a 10x8 raster at canvas (100, 50), margin 2: the quad is (0, -1)..(8, 6)
// raster-local, so canvas (100, 49)..(108, 56) and art-frame (0, -1/8)..(0.8, 0.75).
assertTrue(mesh.positions.contentEquals(floatArrayOf(100f, 49f, 108f, 49f, 108f, 56f, 100f, 56f)), "positions: ${mesh.positions.toList()}")
assertTrue(mesh.uvs.contentEquals(floatArrayOf(0f, -0.125f, 0.8f, -0.125f, 0.8f, 0.75f, 0f, 0.75f)), "uvs: ${mesh.uvs.toList()}")
assertTrue(mesh.indices.contentEquals(intArrayOf(0, 1, 2, 0, 2, 3)), "two triangles over the four corners")
}
@Test
fun aClippingLayerMasksByTheFirstUnclippedLayerBelowItInItsFolder() {
val puppet = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val byName = puppet.drawables.associateBy { drawable -> drawable.name }
assertEquals(listOf(byName.getValue("Face").id), byName.getValue("Eye").maskedBy, "Eye clips to Face, the layer below it in Head")
assertTrue(byName.getValue("Lonely").maskedBy.isEmpty(), "a clipping layer with no base imports unclipped")
}
@Test
fun blendVisibilityAndOpacityCarryOntoTheDrawable() {
val puppet = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val byName = puppet.drawables.associateBy { drawable -> drawable.name }
assertEquals(BlendMode.AdditiveGlow, byName.getValue("Glow").blendMode)
assertEquals(BlendMode.Normal, byName.getValue("Odd").blendMode, "an unsupported blend falls back to Normal")
assertTrue(!byName.getValue("Hidden").isVisible, "a hidden layer imports hidden, not dropped")
assertEquals(0.5f, byName.getValue("Hidden").opacity)
assertTrue(byName.getValue("Eye").isVisible)
}
/** Folders become parts nested by path, ordered where their top-most layer sits, composited when they must be. */
@Test
fun foldersBecomePartsInPanelOrderWithTheirComposites() {
val puppet = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val byName = puppet.drawables.associateBy { drawable -> drawable.name }
val partById = puppet.parts.associateBy { part -> part.id }
assertEquals(listOf("Head", "Body", "Arm", "Solo"), puppet.parts.map { part -> part.name }, "parts are minted in pre-order")
assertEquals((1..4).map { index -> PartId("Part$index") }, puppet.parts.map { part -> part.id })
assertEquals(
listOf(
OrgChild.Part(PartId("Part1")),
OrgChild.Drawable(byName.getValue("Glow").id),
OrgChild.Drawable(byName.getValue("Odd").id),
OrgChild.Part(PartId("Part2")),
OrgChild.Part(PartId("Part4")),
),
puppet.rootChildren,
"the root interleaves folders and layers in the file's own order",
)
val head = partById.getValue(PartId("Part1"))
assertEquals(listOf(OrgChild.Drawable(byName.getValue("Eye").id), OrgChild.Drawable(byName.getValue("Face").id)), head.children)
assertTrue(!head.isVisible, "a hidden folder imports as a hidden part")
assertEquals(PartGroupMode.PassThrough, head.groupMode, "a plain folder is pass-through")
val body = partById.getValue(PartId("Part2"))
assertEquals(listOf(OrgChild.Part(PartId("Part3"))), body.children)
assertEquals(PartGroupMode.Isolated, body.groupMode, "a translucent folder must composite as one layer")
assertEquals(0.5f, body.composite.opacity)
assertEquals(BlendMode.Normal, body.composite.blendMode)
assertEquals(listOf(OrgChild.Drawable(byName.getValue("Hidden").id)), partById.getValue(PartId("Part3")).children)
assertEquals("Solo", partById.getValue(PartId("Part4")).name, "a folder the reader did not describe is synthesized from the layer's path")
assertTrue(puppet.renderRoot.children.isNotEmpty(), "the render root is derived from the tree")
}
@Test
fun everyDrawableGetsAnUnplacedTileBoundToItsSourceLayer() {
val result = SourceArtImport.fromSourceArt(fixture(), descriptor)
val puppet = result.puppet
val atlas = puppet.atlas
assertTrue(atlas.pages.isEmpty(), "the bridge packs nothing")
assertTrue(atlas.storedUvsAddressPages, "but the coordinates are declared page-frame, so the pack at open re-derives them through the identity")
assertEquals(6, atlas.tiles.size)
assertTrue(atlas.tiles.all { tile -> tile.placement == null }, "every tile is unplaced")
val eye = puppet.drawables.first { drawable -> drawable.name == "Eye" }
val eyeTile = assertNotNull(atlas.tileById[assertNotNull(eye.atlasTileId)])
assertEquals(AtlasTileId("art-0/lyid:1"), eyeTile.id)
assertEquals(SourceLayerRef(ArtSourceId("art-0"), "lyid:1", stableKey = true), eyeTile.source)
assertEquals(10, eyeTile.width)
assertEquals(8, eyeTile.height)
assertSame(eyeRaster, result.rasterByTile[eyeTile.id], "the tile's pixels are the layer's own raster")
val glowTile = assertNotNull(atlas.tileById[assertNotNull(puppet.drawables.first { drawable -> drawable.name == "Glow" }.atlasTileId)])
assertEquals(false, assertNotNull(glowTile.source).stableKey, "a name-and-order key is recorded as unstable")
}
/** The inventory marks a raster layer with no alpha anywhere as empty; every other row is not. */
@Test
fun theInventoryMarksAnErasedLayerEmpty() {
val rows = SourceArtImport.inventoryOf(fixture()).associateBy { row -> row.key }
assertTrue(rows.getValue("lyid:3").empty, "the Empty layer has no alpha")
assertTrue(!rows.getValue("lyid:2").empty, "Face has art")
assertTrue(!rows.getValue("lyid:0").empty, "a text layer is not a raster erased to nothing")
}
@Test
fun theSourceListRecordsTheFileAndEveryLayerSkippedOnesIncluded() {
val puppet = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val source = puppet.sources.single()
assertEquals(ArtSourceId("art-0"), source.id)
assertEquals("fixture.psd", source.name)
assertEquals("/art/fixture.psd", source.path)
assertEquals("psd", source.format)
assertEquals(listOf("Title", "Eye", "Face", "Empty", "Glow", "Odd", "Hidden", "Lonely"), source.layers.map { entry -> entry.name }, "top-most first, nothing left out")
val eyeEntry = source.layers.first { entry -> entry.name == "Eye" }
assertEquals("lyid:1", eyeEntry.key)
assertEquals("Head", eyeEntry.groupPath)
assertEquals(listOf(100, 50, 10, 8), listOf(eyeEntry.left, eyeEntry.top, eyeEntry.width, eyeEntry.height))
}
@Test
fun theCanvasAndOriginAndDisplayModeMatchAFreshImport() {
val puppet = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
assertEquals(200f, puppet.canvasWidth)
assertEquals(100f, puppet.canvasHeight)
assertEquals(100f, puppet.worldOriginX)
assertEquals(-50f, puppet.worldOriginZ, "the origin is the canvas center, y negated into world space")
assertTrue(puppet.rendersFromSourceLayers, "a fresh import shows the layers as drawn")
assertNull(puppet.pixelsPerUnit)
assertTrue(puppet.deformers.isEmpty())
}
@Test
fun theSeedParametersLandVerbatimOrNothingIsSeeded() {
val seed =
listOf(
Parameter(id = ParameterId("ParamAngleX"), name = "Angle X", min = -30f, max = 30f, default = 0f),
Parameter(id = ParameterId("ParamEyeLOpen"), name = "Eye L Open", min = 0f, max = 1f, default = 1f),
)
val seeded = SourceArtImport.fromSourceArt(fixture(), descriptor, SourceArtImportOptions(parameters = seed)).puppet
val bare = SourceArtImport.fromSourceArt(fixture(), descriptor, SourceArtImportOptions()).puppet
assertEquals(seed, seeded.parameters, "the bridge seeds exactly what it is handed, in order")
assertEquals(
seed.map { parameter -> ParameterNode.Param(parameter.id) },
seeded.parameterTree,
"the tree is materialized flat, so an export places every parameter in the group hierarchy",
)
assertTrue(bare.parameters.isEmpty(), "the bridge's own default seeds nothing; the template is the caller's policy")
assertTrue(bare.parameterTree.isEmpty())
}
/**
* Added to an open document, a file's ids continue the document's own sequences and its root
* order lands after the existing children - so the additions can be appended without a rename.
* The same additions over a blank model are exactly what a fresh import assembles.
*/
@Test
fun additionsContinueTheExistingIdSequences() {
val fresh = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val existing =
fresh.copy(
drawables = fresh.drawables.take(1).map { drawable -> drawable.copy(id = DrawableId("ArtMesh3")) },
parts = fresh.parts.take(1).map { part -> part.copy(id = PartId("Part2"), children = emptyList()) },
rootChildren = listOf(OrgChild.Part(PartId("Part2")), OrgChild.Drawable(DrawableId("ArtMesh3"))),
atlas = fresh.atlas.copy(tiles = fresh.atlas.tiles.take(1)),
)
val added = SourceArtImport.additionsFor(fixture(), ArtSourceDescriptor("second.psd", null, "psd"), SourceArtImportOptions(), existing).additions
assertEquals(ArtSourceId("art-1"), added.source.id, "the source continues past art-0")
assertEquals((4..9).map { index -> DrawableId("ArtMesh$index") }, added.drawables.map { drawable -> drawable.id }, "drawables continue past ArtMesh3")
assertEquals((3..6).map { index -> PartId("Part$index") }, added.parts.map { part -> part.id }, "parts continue past Part2")
assertTrue(added.tiles.all { tile -> tile.id.raw.startsWith("art-1/") }, "tiles are keyed under the new source")
assertTrue(added.tiles.all { tile -> tile.source?.sourceId == ArtSourceId("art-1") })
assertEquals(5, added.rootChildren.size, "the file's own top-level order, to append after the existing children")
val overBlank = SourceArtImport.additionsFor(fixture(), descriptor, SourceArtImportOptions(), fresh.copy(drawables = emptyList(), parts = emptyList(), rootChildren = emptyList(), atlas = PuppetAtlas.Empty, sources = emptyList())).additions
assertEquals(fresh.drawables.map { drawable -> drawable.id }, overBlank.drawables.map { drawable -> drawable.id }, "over a blank model the additions are the fresh import's")
}
/**
* A reload's additions (under a listed source) mint only the folders the added layers live in; a
* folder the document already keeps as a part - found through the source's bindings, since a part
* carries no folder of its own - takes the layers as children instead of a second part of the same
* name; a new sub-folder inside such a part is minted as a new part under it; and every new child is
* placed among the existing children where the file puts it: after its nearest shown sibling above,
* else before its nearest below, so a layer added at the top of the file lands first.
*/
@Test
fun additionsUnderAListedSourceReuseTheDocumentsPartsAndPlaceByTheFilesOrder() {
val existing = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val existingByName = existing.drawables.associateBy { drawable -> drawable.name }
val headPart = existing.parts.first { part -> part.name == "Head" }
val bodyPart = existing.parts.first { part -> part.name == "Body" }
val armPart = existing.parts.first { part -> part.name == "Arm" }
val cap = layer("lyid:11", "Cap", order = -1, left = 0, top = 0, raster = rasterOf(2, 2))
val brow = layer("lyid:8", "Brow", order = 8, left = 90, top = 30, raster = rasterOf(4, 4), groupPath = "Head")
val lash = layer("lyid:9", "Lash", order = 9, left = 95, top = 45, raster = rasterOf(3, 3), groupPath = "Head/Lashes")
val tail = layer("lyid:10", "Tail", order = 10, left = 0, top = 80, raster = rasterOf(6, 6), groupPath = "Body/Tail")
val wholeFile =
FixtureArt(
widthPx = 200,
heightPx = 100,
layers = fixture().layers + cap + brow + lash + tail,
groups = fixture().groups + FixtureGroup("Head/Lashes", "Lashes") + FixtureGroup("Body/Tail", "Tail"),
)
val gained = setOf("lyid:11", "lyid:8", "lyid:9", "lyid:10")
val added = SourceArtImport.additionsFor(wholeFile, descriptor, SourceArtImportOptions(), existing, underSource = ArtSourceId("art-0"), layerKeys = gained).additions
val byName = added.drawables.associateBy { drawable -> drawable.name }
assertEquals(listOf("Cap", "Brow", "Lash", "Tail"), added.drawables.map { drawable -> drawable.name }, "only the named layers are minted, top-most first")
assertEquals(listOf("Lashes", "Tail"), added.parts.map { part -> part.name }, "only the folders the document has no part for are minted; Head, Body, Arm, and Solo are not")
assertEquals(listOf(PartId("Part5"), PartId("Part6")), added.parts.map { part -> part.id }, "past the document's four parts")
assertTrue(added.rootChildren.isEmpty(), "a listed file appends nothing after the root; its new children are placed")
val lashes = added.parts.first { part -> part.name == "Lashes" }
val tailPart = added.parts.first { part -> part.name == "Tail" }
assertEquals(listOf(OrgChild.Drawable(byName.getValue("Lash").id)), lashes.children)
assertEquals(
listOf(
OrgInsertion(null, OrgChild.Drawable(byName.getValue("Cap").id), OrgSlot.Before(OrgChild.Part(headPart.id))),
OrgInsertion(headPart.id, OrgChild.Drawable(byName.getValue("Brow").id), OrgSlot.After(OrgChild.Drawable(existingByName.getValue("Face").id))),
OrgInsertion(headPart.id, OrgChild.Part(lashes.id), OrgSlot.After(OrgChild.Drawable(byName.getValue("Brow").id))),
OrgInsertion(bodyPart.id, OrgChild.Part(tailPart.id), OrgSlot.After(OrgChild.Part(armPart.id))),
),
added.insertions,
"the top layer goes before the root's first folder; Brow after Face (the empty layer above it shows nothing); the new Lashes folder after Brow; the new Tail folder after Arm",
)
val fresh = SourceArtImport.additionsFor(wholeFile, ArtSourceDescriptor("other.psd", null, "psd"), SourceArtImportOptions(), existing).additions
assertEquals(listOf("Head", "Lashes", "Body", "Arm", "Tail", "Solo"), fresh.parts.map { part -> part.name }, "a NEW file still mints every folder it has, in pre-order")
assertTrue(fresh.insertions.isEmpty(), "and appends its whole tree after the root")
assertEquals(OrgChild.Drawable(fresh.drawables.first { drawable -> drawable.name == "Cap" }.id), fresh.rootChildren.first())
}
/** Two layers sharing a weak key still get distinct tiles, disambiguated by draw order. */
@Test
fun aDuplicateLayerKeyIsDisambiguatedByOrder() {
val art =
FixtureArt(
widthPx = 10,
heightPx = 10,
layers =
listOf(
layer("Same#0", "Same", order = 0, left = 0, top = 0, raster = rasterOf(2, 2), stable = false),
layer("Same#0", "Same", order = 1, left = 4, top = 4, raster = rasterOf(2, 2), stable = false),
),
)
val puppet = SourceArtImport.fromSourceArt(art, descriptor).puppet
assertEquals(listOf(AtlasTileId("art-0/Same#0"), AtlasTileId("art-0/Same#0#1")), puppet.atlas.tiles.map { tile -> tile.id })
assertEquals(2, puppet.drawables.map { drawable -> drawable.atlasTileId }.toSet().size, "each drawable samples its own tile")
}
/**
* Placing a file shifts every layer's bounds and nothing else: the rasters are the same instances
* (the decode memo and the texture cache key on them), the file's canvas and folders pass through,
* and a zero offset hands the art back untouched.
*/
@Test
fun placingAFileShiftsItsBoundsAndKeepsItsRasters() {
val art = fixture()
assertSame(art, art.placedBy(CanvasOffset.Zero), "a zero offset places nothing")
val placed = art.placedBy(CanvasOffset(30, -10))
assertEquals(art.widthPx to art.heightPx, placed.widthPx to placed.heightPx, "the file's own canvas passes through")
assertSame(art.groups, placed.groups)
for ((original, moved) in art.layers.zip(placed.layers)) {
assertSame(original.raster, moved.raster, "'${original.name}' keeps its raster instance")
assertEquals(LayerBounds(original.bounds.left + 30, original.bounds.top + 10, original.bounds.width, original.bounds.height), moved.bounds, "z is up, so a negative z lowers the layer")
assertEquals(original.id, moved.id)
assertEquals(original.groupPath, moved.groupPath)
assertEquals(original.clipped, moved.clipped)
}
val source = ArtSource(ArtSourceId("art-3"), "x.psd", null, "psd", offsetX = 4, offsetZ = 6)
assertEquals(LayerBounds(104, 44, 10, 8), art.placedFor(source).layers.first { layer -> layer.name == "Eye" }.bounds, "a record's offset places the same way")
}
/**
* The anchor splits the room between the document's canvas and the file's by its fraction, rounded
* down, and the nudge is added on top - in world axes, so a file placed below the document's top edge
* carries a negative z; a file larger than the canvas overhangs it; a rig's first artwork and a
* document with no canvas are never placed.
*/
@Test
fun theOffsetFollowsTheAnchorAndTheNudge() {
val host = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet.copy(canvasWidth = 300f, canvasHeight = 250f)
val small = FixtureArt(widthPx = 101, heightPx = 50, layers = listOf(layer("lyid:0", "Dot", order = 0, left = 0, top = 0, raster = rasterOf(2, 2))))
val large = FixtureArt(widthPx = 400, heightPx = 250, layers = small.layers)
fun offsetOf(art: SourceArt, anchor: ArtworkAnchor, nudgeX: Int = 0, nudgeZ: Int = 0): CanvasOffset =
SourceArtImport.offsetFor(host, art, SourceArtImportOptions(anchor = anchor, nudgeX = nudgeX, nudgeZ = nudgeZ))
assertEquals(CanvasOffset(99, -100), offsetOf(small, ArtworkAnchor.Center), "199 x 200 of room, halved and rounded down; 100 px down the canvas is z = -100")
assertEquals(CanvasOffset(0, 0), offsetOf(small, ArtworkAnchor.TopLeft))
assertEquals(CanvasOffset(199, -200), offsetOf(small, ArtworkAnchor.BottomRight))
assertEquals(CanvasOffset(99, 0), offsetOf(small, ArtworkAnchor.Top))
assertEquals(CanvasOffset(0, -100), offsetOf(small, ArtworkAnchor.Left))
assertEquals(CanvasOffset(199, -100), offsetOf(small, ArtworkAnchor.Right))
assertEquals(CanvasOffset(102, -104), offsetOf(small, ArtworkAnchor.Center, nudgeX = 3, nudgeZ = -4), "the nudge is added to the anchor's placement")
assertEquals(CanvasOffset(-50, 0), offsetOf(large, ArtworkAnchor.Center), "a wider file overhangs both sides by the same amount")
assertEquals(CanvasOffset(-100, 0), offsetOf(large, ArtworkAnchor.BottomRight))
val blank = host.copy(drawables = emptyList(), atlas = PuppetAtlas.Empty)
assertEquals(CanvasOffset.Zero, SourceArtImport.offsetFor(blank, small, SourceArtImportOptions(nudgeX = 7)), "a first artwork sets the canvas and is never placed")
assertTrue(SourceArtImport.isFirstArtwork(blank))
assertTrue(!SourceArtImport.isFirstArtwork(host))
assertEquals(CanvasOffset.Zero, SourceArtImport.offsetFor(host.copy(canvasWidth = 0f), small, SourceArtImportOptions()), "no canvas, nothing to place within")
}
/**
* A placed file's birth quads sit at the placed positions, its inventory rows are recorded in the
* document frame, and its record keeps the offset; a listed file's additions keep the offset its
* record already carries, whatever the caller passes.
*/
@Test
fun additionsRecordTheOffsetTheFileWasPlacedBy() {
val existing = SourceArtImport.fromSourceArt(fixture(), descriptor).puppet
val offset = CanvasOffset(50, 20)
val added = SourceArtImport.additionsFor(fixture().placedBy(offset), ArtSourceDescriptor("second.psd", null, "psd"), SourceArtImportOptions(), existing, offset = offset).additions
assertEquals(50 to 20, added.source.offsetX to added.source.offsetZ, "the new record keeps the offset")
val eye = assertNotNull(added.drawables.first { drawable -> drawable.name == "Eye" }.mesh)
assertTrue(eye.positions.contentEquals(floatArrayOf(150f, 29f, 158f, 29f, 158f, 36f, 150f, 36f)), "the quad is the fixture's, shifted right and UP: ${eye.positions.toList()}")
assertEquals(150 to 30, added.source.layers.first { row -> row.name == "Eye" }.let { row -> row.left to row.top }, "the inventory row is in the document frame")
val listed = existing.copy(sources = existing.sources.map { source -> source.copy(offsetX = 8, offsetZ = 9) })
val underListed = SourceArtImport.additionsFor(fixture(), descriptor, SourceArtImportOptions(), listed, underSource = ArtSourceId("art-0"), layerKeys = setOf("lyid:1"), offset = offset).additions
assertEquals(8 to 9, underListed.source.offsetX to underListed.source.offsetZ, "a listed file's record keeps its own offset")
}
}
@@ -0,0 +1,147 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.identity.Id
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Contract checks for [cmo3AtlasPages] over hand-built graphs. The walk takes a CModelSource plus an
* injected pixel lookup rather than a Cmo3Model, which is exactly what lets this run without a corpus
* `.cmo3` - and on every target, since the CMO3 node classes are commonMain.
*
* Only the WALK is covered here: which resources become pages and who samples them. Whether a page's
* bytes decode, and what a broken one costs, belongs to the renderer's shared builder and is covered by
* PuppetTexturesTest - this walk never decodes anything.
*/
class Cmo3AtlasPagesTest {
/**
* Builds an art mesh bound to [resource], mirroring the shape the CMO3 serializer produces.
*
* @param String drawableId The mesh's id string.
* @param CImageResource? resource The page it samples, or null for a texture with no source.
* @param Boolean premultiplied The page's GTexture2D.isPremultiplied flag.
* @return CArtMeshSource The assembled mesh.
*/
private fun artMesh(drawableId: String, resource: CImageResource?, premultiplied: Boolean = false): CArtMeshSource =
CArtMeshSource().apply {
id = Id("ArtMesh").apply { idstr = drawableId }
texture =
GTexture2D().apply {
srcImageResource = resource
isPremultiplied = premultiplied
}
}
/**
* Wraps [meshes] in the drawable-source-set container a CModelSource holds them in.
*
* @param CArtMeshSource meshes The meshes to mount.
* @return CModelSource The assembled root.
*/
private fun modelSourceOf(vararg meshes: CArtMeshSource): CModelSource =
CModelSource().apply {
drawableSourceSet = CDrawableSourceSet().apply { _sources = meshes.toList() }
}
@Test
fun sharedResourceIsFetchedOnceAndBothDrawablesPointAtIt() {
val page = CImageResource()
val root = modelSourceOf(artMesh("ArtMeshLeft", page), artMesh("ArtMeshRight", page))
var reads = 0
val pageSet =
cmo3AtlasPages(root) { requested ->
reads++
if (requested === page) byteArrayOf(1, 2, 3) else null
}
assertEquals(1, pageSet.pageBytes.size, "one distinct resource is one atlas page")
assertEquals(0, pageSet.atlasIndexByDrawableId["ArtMeshLeft"])
assertEquals(0, pageSet.atlasIndexByDrawableId["ArtMeshRight"])
assertEquals(1, reads, "the shared page's bytes are fetched once, not per drawable")
}
@Test
fun distinctResourcesBecomeDistinctPagesInEncounterOrder() {
val firstPage = CImageResource()
val secondPage = CImageResource()
val root = modelSourceOf(artMesh("ArtMeshFirst", firstPage), artMesh("ArtMeshSecond", secondPage))
val pageSet =
cmo3AtlasPages(root) { requested -> if (requested === firstPage) byteArrayOf(1) else byteArrayOf(2, 2) }
assertEquals(2, pageSet.pageBytes.size)
assertEquals(0, pageSet.atlasIndexByDrawableId["ArtMeshFirst"])
assertEquals(1, pageSet.atlasIndexByDrawableId["ArtMeshSecond"])
assertEquals(1, pageSet.pageBytes[0].size, "page order follows drawable encounter order")
assertEquals(2, pageSet.pageBytes[1].size)
}
@Test
fun aResourceCarryingNoBytesLeavesItsDrawablesUnbound() {
val goodPage = CImageResource()
val absentPage = CImageResource()
val root =
modelSourceOf(
artMesh("ArtMeshGood", goodPage),
artMesh("ArtMeshAbsent", absentPage),
artMesh("ArtMeshAbsentSibling", absentPage),
)
var reads = 0
val pageSet =
cmo3AtlasPages(root) { requested ->
reads++
if (requested === goodPage) byteArrayOf(1) else null
}
// A resource that yielded nothing is a remembered answer too, so its second drawable costs no
// second lookup - two distinct resources, two reads.
assertEquals(2, reads, "each distinct resource is resolved once, failures included")
assertEquals(1, pageSet.pageBytes.size, "only the resource with bytes becomes a page")
assertEquals(0, pageSet.atlasIndexByDrawableId["ArtMeshGood"])
assertNull(pageSet.atlasIndexByDrawableId["ArtMeshAbsent"], "a resource with no bytes is skipped")
assertNull(pageSet.atlasIndexByDrawableId["ArtMeshAbsentSibling"], "and so is everything else on it")
}
@Test
fun meshesWithoutAnIdOrATextureAreSkipped() {
val page = CImageResource()
val unnamed = artMesh("", page)
val textureless = CArtMeshSource().apply { id = Id("ArtMesh").apply { idstr = "ArtMeshTextureless" } }
val root = modelSourceOf(unnamed, textureless, artMesh("ArtMeshReal", page))
val pageSet = cmo3AtlasPages(root) { byteArrayOf(1) }
assertEquals(mapOf("ArtMeshReal" to 0), pageSet.atlasIndexByDrawableId)
}
@Test
fun premultipliedIsTheOrFoldAcrossTextures() {
val page = CImageResource()
val straight = modelSourceOf(artMesh("ArtMeshA", page, premultiplied = false))
val mixed =
modelSourceOf(
artMesh("ArtMeshA", page, premultiplied = false),
artMesh("ArtMeshB", page, premultiplied = true),
)
assertEquals(false, cmo3AtlasPages(straight) { byteArrayOf(1) }.premultipliedAlpha)
assertTrue(cmo3AtlasPages(mixed) { byteArrayOf(1) }.premultipliedAlpha, "any premultiplied texture sets it")
}
@Test
fun aRootWithNoDrawableSourceSetYieldsNoPages() {
val pageSet = cmo3AtlasPages(CModelSource()) { byteArrayOf(1) }
assertTrue(pageSet.pageBytes.isEmpty())
assertTrue(pageSet.atlasIndexByDrawableId.isEmpty())
}
}
@@ -0,0 +1,215 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CModelImage
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CCachedImage
import org.umamo.format.cmo3.model.gen.CCachedImageManager
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.CModelImageGroup
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureInputExtension
import org.umamo.format.cmo3.model.gen.CTextureInput_TextureAtlasRegion
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.identity.Id
import org.umamo.format.cmo3.model.type.CAffine
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertSame
import kotlin.test.assertTrue
/**
* The CMO3 texture-frame rules over a hand-built graph: one model image with its raster and a reduced
* cache copy, one atlas page, and a drawable over each kind of image.
*/
class Cmo3TextureFramesTest {
/** The raster-to-cache scale every texture here carries (an art size over its 64-aligned padding). */
private val cacheScaleU = 0.75f
private val cacheScaleV = 0.5f
private val page = CImageResource()
private val raster = CImageResource()
private val copy = CImageResource()
private val modelImage =
CModelImage().apply {
_filteredImage = raster
cachedImageManager =
CCachedImageManager().apply {
cachedImages =
listOf(
CCachedImage().apply { _cachedImageResource = raster },
CCachedImage().apply {
_cachedImageResource = copy
reductionRatio = 2
},
)
}
}
/**
* A drawable over [resource], packed (with an atlas-region input) or not.
*
* @param String drawableId The drawable's id string.
* @param CImageResource resource The image its texture names.
* @param Boolean packed Whether it carries an atlas-region input.
* @param Boolean scaled Whether its texture carries the cache scale rather than the identity.
* @return CArtMeshSource The drawable.
*/
private fun drawable(drawableId: String, resource: CImageResource, packed: Boolean, scaled: Boolean = true): CArtMeshSource =
CArtMeshSource().apply {
id = Id("ArtMesh").apply { idstr = drawableId }
texture =
GTexture2D().apply {
srcImageResource = resource
transformImageResource01toLogical01 =
CAffine().apply {
if (scaled) {
m00 = cacheScaleU
m11 = cacheScaleV
}
}
}
_extensions =
listOf(
CTextureInputExtension().apply {
_textureInputs = if (packed) listOf(CTextureInput_TextureAtlasRegion()) else emptyList()
},
)
}
private val onPage = drawable("ArtMeshPage", page, packed = true, scaled = false)
private val onRaster = drawable("ArtMeshRaster", raster, packed = true)
private val onCopy = drawable("ArtMeshCopy", copy, packed = true)
private val unpacked = drawable("ArtMeshUnpacked", raster, packed = false)
/**
* The graph holding every drawable, the page, and the model image.
*
* @return CModelSource The root.
*/
private fun modelSource(): CModelSource =
CModelSource().apply {
textureManager =
CTextureManager().apply {
_textureAtlases = listOf(CTextureAtlas().apply { cachedAtlasImage = page })
_modelImageGroups = listOf(CModelImageGroup().apply { _modelImages = listOf(modelImage) })
}
drawableSourceSet = CDrawableSourceSet().apply { _sources = listOf(onPage, onRaster, onCopy, unpacked) }
}
/**
* Asserts two coordinate arrays agree to within float rounding.
*
* @param FloatArray expected The expected coordinates.
* @param FloatArray actual The coordinates produced.
* @param String message What is being compared.
*/
private fun assertClose(expected: FloatArray, actual: FloatArray, message: String) {
assertEquals(expected.size, actual.size, message)
for (componentIndex in expected.indices) {
assertTrue(abs(expected[componentIndex] - actual[componentIndex]) < 1e-6f, "$message: component $componentIndex is ${actual[componentIndex]}, not ${expected[componentIndex]}")
}
}
@Test
fun eachDrawableStoresTheFrameOfWhatItsTextureNames() {
val frames = Cmo3TextureFrames(modelSource())
assertEquals(Cmo3StoredFrame.Page, frames.storedFrameOf(onPage), "a packed drawable over a page stores the page's frame")
assertEquals(Cmo3StoredFrame.Raster, frames.storedFrameOf(onRaster), "a packed drawable over its raster stores the raster's frame")
assertEquals(Cmo3StoredFrame.Cache, frames.storedFrameOf(onCopy), "a drawable over a reduced copy stores the cache frame")
assertEquals(Cmo3StoredFrame.Cache, frames.storedFrameOf(unpacked), "an unpacked drawable stores the cache frame")
assertTrue(frames.samplesReducedCopy(onCopy))
assertFalse(frames.samplesReducedCopy(onRaster))
assertFalse(frames.samplesReducedCopy(unpacked))
}
@Test
fun aReducedCopyIsShownFromItsModelImagesRaster() {
val frames = Cmo3TextureFrames(modelSource())
assertSame(raster, frames.renderedImageOf(onCopy), "the copy gives way to the raster it was reduced from")
assertSame(page, frames.renderedImageOf(onPage))
assertSame(raster, frames.renderedImageOf(onRaster))
assertTrue(frames.isShownFrom(onCopy, modelImage))
assertTrue(frames.isShownFrom(onRaster, modelImage))
assertFalse(frames.isShownFrom(onPage, modelImage))
}
@Test
fun cacheFrameCoordinatesInvertIntoTheRasterAndBack() {
val frames = Cmo3TextureFrames(modelSource())
val stored = floatArrayOf(cacheScaleU, cacheScaleV, 0.3f, 0.1f)
val model = frames.modelUvsOf(onCopy, stored)
assertClose(floatArrayOf(1f, 1f, 0.3f / cacheScaleU, 0.1f / cacheScaleV), model, "the cache frame's art edge is the raster's")
assertClose(stored, frames.storedUvsOf(onCopy, model), "the forward affine restores the stored coordinates")
assertSame(stored, frames.modelUvsOf(onRaster, stored), "a drawable storing its image's own frame is taken verbatim")
assertContentEquals(stored, frames.storedUvsOf(onRaster, stored), "and written back verbatim")
}
@Test
fun aPlacedTilesCoordinatesGoOntoItsPageAndBackOff() {
val frames = Cmo3TextureFrames(modelSource())
// The tile's model-to-art affine: its art occupies a quarter by a half of the page, from (0.25, 0.25).
val storedToArt = floatArrayOf(4f, 0f, -1f, 0f, 2f, -0.5f)
val stored = floatArrayOf(cacheScaleU * 0.5f, cacheScaleV * 0.5f, 0f, 0f)
// Over a copy: out of the cache frame to the art's center (0.5, 0.5), then onto the page.
val model = frames.modelUvsOf(onCopy, stored, storedToArt)
assertClose(floatArrayOf(0.375f, 0.5f, 0.25f, 0.25f), model, "the art's center and corner land on the page")
assertClose(stored, frames.storedUvsOf(onCopy, model, storedToArt), "and come back off it into the cache frame")
// Over the raster: no cache step, the same placement.
val rasterModel = frames.modelUvsOf(onRaster, floatArrayOf(0.5f, 0.5f), storedToArt)
assertClose(floatArrayOf(0.375f, 0.5f), rasterModel, "a raster pair lands on the page")
assertClose(floatArrayOf(0.5f, 0.5f), frames.storedUvsOf(onRaster, rasterModel, storedToArt), "and comes back in the raster's frame")
// Over the page: already there, whatever the placement.
assertSame(stored, frames.modelUvsOf(onPage, stored, storedToArt), "page coordinates are taken verbatim")
assertContentEquals(stored, frames.storedUvsOf(onPage, stored, storedToArt), "and stored verbatim")
// An unplaced tile's identity affine changes nothing past the cache step.
assertClose(floatArrayOf(0.5f, 0.5f, 0f, 0f), frames.modelUvsOf(onCopy, stored, floatArrayOf(1f, 0f, 0f, 0f, 1f, 0f)), "without a placement the raster frame is the model's")
}
@Test
fun anUnchangedPairKeepsItsStoredBits() {
val frames = Cmo3TextureFrames(modelSource())
val stored = floatArrayOf(0.3f, 0.7f, 0.1f, 0.2f)
val baseline = frames.modelUvsOf(onCopy, stored)
val edited = baseline.copyOf().also { uvs -> uvs[2] = 0.5f }
val written = frames.storedUvsOf(onCopy, edited, storedUvs = stored, baselineUvs = baseline)
assertEquals(stored[0].toRawBits(), written[0].toRawBits(), "the untouched pair keeps its stored u")
assertEquals(stored[1].toRawBits(), written[1].toRawBits(), "the untouched pair keeps its stored v")
assertClose(floatArrayOf(0.5f * cacheScaleU, baseline[3] * cacheScaleV), written.copyOfRange(2, 4), "the edited pair goes through the affine")
}
@Test
fun theCopySetIsTakenAsReadAndOnlyARetargetedTextureLeavesTheCacheFrame() {
val frames = Cmo3TextureFrames(modelSource())
// A rewrite rebuilds the image's cache without the copy; the drawable still samples it.
modelImage.cachedImageManager = CCachedImageManager().apply { cachedImages = listOf(CCachedImage().apply { _cachedImageResource = raster }) }
assertEquals(Cmo3StoredFrame.Cache, frames.storedFrameOf(onCopy), "a cache rebuild does not change what the drawable's coordinates mean")
// Retargeting the texture onto the raster does.
(onCopy.texture as GTexture2D).srcImageResource = raster
assertEquals(Cmo3StoredFrame.Raster, frames.storedFrameOf(onCopy), "a packed drawable moved onto its raster stores the raster's frame")
assertSame(raster, frames.renderedImageOf(onCopy))
}
@Test
fun anAtlasPageIsNeverAReducedCopy() {
modelImage.cachedImageManager = CCachedImageManager().apply { cachedImages = listOf(CCachedImage().apply { _cachedImageResource = page }) }
val frames = Cmo3TextureFrames(modelSource())
assertFalse(frames.isReducedCopy(page))
assertEquals(Cmo3StoredFrame.Page, frames.storedFrameOf(onPage))
assertSame(page, frames.renderedImageOf(onPage))
}
}
@@ -0,0 +1,164 @@
package org.umamo.interop.moc3
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.model.BlendShapeKeyform
import org.umamo.format.moc3.model.BlendShapeTarget
import org.umamo.interop.moc3.export.Moc3Export
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.Deformer
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.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
/**
* A blend-shape owner's positional deltas are un-converted from ITS OWN parent's space.
*
* The blend pass is the third caller of the context's `spaceOfParent`, alongside the art-mesh and
* deformer lowerings, and the three must agree. Root space is the only one carrying the px→model
* divide, so resolving a parented owner as root scales its whole blend shape by the pixels-per-unit -
* a rig-scale error rather than a rounding one, and invisible in a document whose ppu happens to be 1.
* This rig therefore uses a ppu of 4 so the two arms cannot produce the same numbers.
*/
class Moc3BlendShapeSpaceTest {
private val morphParameter = ParameterId("ParamMorph")
private val poseParameter = ParameterId("ParamPose")
private val pixelsPerUnit = 4f
/** The authored delta, chosen so dividing by [pixelsPerUnit] lands on exact binary fractions. */
private val authoredDeltas = floatArrayOf(8f, -16f, 32f, 64f)
/**
* A blend-shape binding carrying [authoredDeltas] at its non-neutral key.
*
* @return BlendShapeBinding The binding to hang on an owner.
*/
private fun morphBinding(): BlendShapeBinding<MeshForm> =
BlendShapeBinding(
parameterId = morphParameter,
keys = floatArrayOf(0f, 1f),
neutralIndex = 0,
forms = listOf(null, MeshForm(authoredDeltas.copyOf())),
)
/**
* A drawable with a two-vertex mesh and one blend shape, under [parentDeformerId].
*
* The mesh is present because the pass sizes its delta row from the vertex count. The geometry grid
* is all zeros rather than absent: a parented drawable with no grid has no parent-local form to
* write and export eligibility drops it, and zeros keep the subtracted default-pose reference at
* zero so the stored row is the authored delta converted, with nothing else folded in.
*
* @param String id The drawable id.
* @param DeformerId? parentDeformerId The owning deformer, null at the root.
* @return Drawable The drawable.
*/
private fun blendDrawable(id: String, parentDeformerId: DeformerId?): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = parentDeformerId,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh =
DrawableMesh(
positions = FloatArray(authoredDeltas.size),
uvs = FloatArray(authoredDeltas.size),
indices = intArrayOf(0, 1, 0),
),
geometryGrid =
KeyformGrid(
axes = listOf(KeyformAxis(poseParameter, floatArrayOf(0f, 1f))),
cells =
listOf(
KeyformCell(intArrayOf(0), MeshDeltaForm(FloatArray(authoredDeltas.size))),
KeyformCell(intArrayOf(1), MeshDeltaForm(FloatArray(authoredDeltas.size))),
),
),
blendShapes = listOf(morphBinding()),
)
/**
* The stored art-mesh delta row of the named drawable's single blend shape at its non-neutral key.
*
* @param PuppetModel puppet The rig to export.
* @param String id The owning drawable's id.
* @return FloatArray The stored vertex-position row.
*/
private fun storedMeshRow(puppet: PuppetModel, id: String): FloatArray {
val document = Moc3Export.toMocDocument(puppet, MocVersion.V50).document
val drawableIndex = document.artMeshes.indexOfFirst { artMesh -> artMesh.id == id }
val record =
document.blendShapes.single { blendShape ->
blendShape.target == BlendShapeTarget.ART_MESH && blendShape.targetIndex == drawableIndex
}
return (record.keyforms[1] as BlendShapeKeyform.Mesh).form.vertexPositions
}
@Test
fun aParentedOwnerStoresVerbatimWhileARootOwnerTakesThePpuDivide() {
val warp =
Deformer.Warp(
id = DeformerId("Warp1"),
name = "Warp1",
parent = null,
partId = PartId("Part1"),
rows = 1,
columns = 1,
isQuadTransform = false,
geometryGrid = null,
)
val underWarp = blendDrawable("UnderWarp", warp.id)
val atRoot = blendDrawable("AtRoot", null)
val part =
Part(
id = PartId("Part1"),
name = "Part1",
children = listOf(OrgChild.Drawable(underWarp.id), OrgChild.Drawable(atRoot.id)),
)
val puppet =
PuppetModel(
parameters =
listOf(
Parameter(morphParameter, "Morph", 0f, 1f, 0f, ParameterKind.BLEND_SHAPE),
Parameter(poseParameter, "Pose", 0f, 1f, 0f),
),
parts = listOf(part),
deformers = listOf(warp),
drawables = listOf(underWarp, atRoot),
rootChildren = listOf(OrgChild.Part(part.id)),
rootPartId = null,
canvasWidth = 100f,
canvasHeight = 100f,
pixelsPerUnit = pixelsPerUnit,
)
// A warp parent's lattice is the same in both conventions, so the authored delta survives as-is.
assertEquals(
authoredDeltas.toList(),
storedMeshRow(puppet, "UnderWarp").toList(),
"a warp-parented blend shape must store its deltas verbatim",
)
// Root space is the one that carries the affine, so the same delta divides by the ppu.
assertEquals(
authoredDeltas.map { delta -> delta / pixelsPerUnit },
storedMeshRow(puppet, "AtRoot").toList(),
"a root blend shape must store its deltas in model units",
)
}
}
@@ -0,0 +1,267 @@
package org.umamo.interop.moc3
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.moc.Sections
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportNotice
import org.umamo.interop.moc3.export.Moc3Export
import org.umamo.interop.moc3.import.Moc3Import
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.Part
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* An id too wide for a moc's id record is shortened to fit, and the shortening never mints a duplicate.
*
* MOC3 §5.4 makes every id a fixed 64-byte record while CMO3 places no width limit on the same string,
* so an over-wide id is a rig a rigger can really author - 22 CJK characters already exceed the record.
* Truncating it is the only way to write it, and truncation is what creates the collision this guards:
* two names differing only past the 63rd byte truncate to one. A MOC3 addresses nothing by id, so the
* file takes the duplicate silently and the loss surfaces on the way back, where the import merges the
* two objects into one.
*
* Synthetic rather than corpus-backed on purpose: the corpus is what the official editor wrote, and its
* own ids all fit.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.4</a>
*/
class Moc3ExportIdFitTest {
/** A name whose UTF-8 form runs well past the record, so every mesh below has to be shortened. */
private val overlongStem = "あ".repeat(40)
/**
* Builds a one-triangle drawable with no keyforms, parented to [partId].
*
* @param String id The drawable's model id.
* @param PartId partId Its owning part.
* @return Drawable The drawable.
*/
private fun drawable(
id: String,
partId: PartId,
): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
// Bound to a page, so the only notice a rig here can raise is about its ids.
texturePage = 0,
mesh =
DrawableMesh(
positions = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f),
uvs = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f),
indices = intArrayOf(0, 1, 2),
),
geometryGrid = null,
)
/**
* A rig whose drawables carry [ids], all under one part.
*
* @param List<String> ids The drawable ids, in model order.
* @return PuppetModel The rig.
*/
private fun puppetWithDrawableIds(ids: List<String>): PuppetModel {
val partId = PartId("Part1")
val drawables = ids.map { id -> drawable(id, partId) }
return PuppetModel(
parameters = emptyList(),
parts = listOf(Part(id = partId, name = "Part1", children = drawables.map { OrgChild.Drawable(it.id) })),
deformers = emptyList(),
drawables = drawables,
rootChildren = listOf(OrgChild.Part(partId)),
rootPartId = null,
canvasWidth = 100f,
canvasHeight = 100f,
)
}
/**
* Two ids that differ only past the record width must not be written as one name.
*
* The second is also checked for still FITTING: disambiguating by appending a suffix to an id
* already trimmed to the limit would push it back over, and the writer's own precondition would
* then reject the file the notice said it had written.
*/
@Test
fun idsTruncatingOntoEachOtherAreDisambiguated() {
val lowered =
Moc3Export.toMocDocument(
puppetWithDrawableIds(listOf(overlongStem + "左", overlongStem + "右")),
MocVersion.V50,
)
val writtenIds = lowered.document.artMeshes.map { artMesh -> artMesh.id }
assertEquals(2, writtenIds.toSet().size, "the two drawables were written under one id: $writtenIds")
for (writtenId in writtenIds) {
assertTrue(
writtenId.encodeToByteArray().size < Sections.ID_STRIDE,
"\"$writtenId\" does not fit a ${Sections.ID_STRIDE}-byte id record",
)
}
// Each shortening is reported against the id the RIG carries, so the rigger can find the object
// the notice is about; the written name is on the reason.
val subjects =
lowered.report.notices
.filterIsInstance<ExportNotice.UnsupportedChange>()
.filter { notice -> notice.category == ExportEntityCategory.Drawable }
.map { notice -> notice.subject }
assertEquals(listOf(overlongStem + "左", overlongStem + "右"), subjects, "both shortenings were reported")
}
/**
* A shortened id never takes a name another object holds outright.
*
* The short drawable here is exactly what the long one truncates to, and it is written LAST - so
* resolving collisions in lowering order, as they came, would hand its own id away to the long one
* and rename the object that never needed shortening at all.
*/
@Test
fun aShortenedIdNeverTakesAnIdSomethingElseHoldsOutright() {
val overlong = "A".repeat(Sections.ID_STRIDE + 20)
val truncated = "A".repeat(Sections.ID_STRIDE - 1)
val lowered = Moc3Export.toMocDocument(puppetWithDrawableIds(listOf(overlong, truncated)), MocVersion.V50)
val writtenIds = lowered.document.artMeshes.map { artMesh -> artMesh.id }
assertEquals(truncated, writtenIds[1], "the id that fits was written verbatim")
assertTrue(writtenIds[0] != truncated, "the shortened id took a name that was already spoken for")
}
/**
* The cdi3 beside the MOC3 names the objects by the ids the MOC got, not the ones the model carries.
*
* The two files are joined on that string by every runtime and by Umamo's own import: a cdi3 built
* from the model's ids would name an object the MOC3 does not contain under that name, so the display
* name - the one thing the MOC3 cannot carry, which is the entire reason the cdi3 is written - is lost
* on exactly the objects whose ids had to be shortened.
*/
@Test
fun theCdi3NamesTheIdsTheMocWasWrittenWith() {
val bundle =
Moc3Sidecars.bundle(
puppetWithDrawableIds(listOf(overlongStem + "左", overlongStem + "右")),
basename = "rig",
version = MocVersion.V50,
pages = emptyList(),
)
val mocFile = bundle.files.first { file -> file.name == bundle.mocFileName }
val displayInfoFile = bundle.files.first { file -> file.name == "rig.cdi3.json" }
val writtenIds = Moc3.read(mocFile.bytes).artMeshes.map { artMesh -> artMesh.id }
val displayInfo = Moc3.readCdi3(displayInfoFile.bytes.decodeToString())
assertEquals(
writtenIds,
displayInfo.drawables.orEmpty().map { drawable -> drawable.id },
"the cdi3 names drawables the moc does not contain",
)
// And the pairing survives a round trip: each mesh gets its own name back rather than falling
// back to the shortened id.
val reimported = Moc3Import.fromMocDocument(Moc3.read(mocFile.bytes), displayInfo)
assertEquals(
setOf(overlongStem + "左", overlongStem + "右"),
reimported.drawables.mapTo(HashSet()) { drawable -> drawable.name },
"a shortened drawable lost its display name",
)
}
/**
* The cdi3 names only the objects the moc contains - never one the export dropped.
*
* The mesh-less drawable here is dropped, and its id is exactly what the kept drawable's over-long id
* shortens to. A dropped object claims no id, so the shortening lands on that very string: naming
* the dropped one anyway would put TWO entries under a single id in the cdi3, and the import's join
* on that string would pick between them arbitrarily - handing a mesh a deleted object's name.
*/
@Test
fun theCdi3OmitsObjectsTheExportDropped() {
val overlong = "A".repeat(Sections.ID_STRIDE + 20)
val truncated = "A".repeat(Sections.ID_STRIDE - 1)
val partId = PartId("Part1")
val kept = drawable(overlong, partId)
// Mesh-less, so the eligibility pass drops it before the plan is built.
val dropped = drawable(truncated, partId).copy(mesh = null)
val sketchPartId = PartId("Sketch")
val puppet =
PuppetModel(
parameters = emptyList(),
parts =
listOf(
Part(id = partId, name = "Part1", children = listOf(OrgChild.Drawable(kept.id), OrgChild.Drawable(dropped.id))),
Part(id = sketchPartId, name = "Sketch", children = emptyList(), isSketch = true),
),
deformers = emptyList(),
drawables = listOf(kept, dropped),
rootChildren = listOf(OrgChild.Part(partId), OrgChild.Part(sketchPartId)),
rootPartId = null,
canvasWidth = 100f,
canvasHeight = 100f,
)
val bundle = Moc3Sidecars.bundle(puppet, basename = "rig", version = MocVersion.V50, pages = emptyList())
val displayInfo = Moc3.readCdi3(bundle.files.first { file -> file.name == "rig.cdi3.json" }.bytes.decodeToString())
assertEquals(
listOf(truncated),
displayInfo.drawables.orEmpty().map { drawable -> drawable.id },
"the cdi3 names a drawable the moc does not contain",
)
assertEquals(overlong, displayInfo.drawables.orEmpty().single().name, "the entry is the kept mesh's, not the dropped one's")
assertEquals(
listOf("Part1"),
displayInfo.parts.map { part -> part.id },
"the cdi3 names a sketch part the bake leaves out",
)
}
/** An id that fits is written verbatim and raises nothing. */
@Test
fun idsThatFitAreWrittenVerbatimAndReportNothing() {
val lowered = Moc3Export.toMocDocument(puppetWithDrawableIds(listOf("ArtMesh1", "ArtMesh2")), MocVersion.V50)
assertEquals(listOf("ArtMesh1", "ArtMesh2"), lowered.document.artMeshes.map { artMesh -> artMesh.id })
assertEquals(emptyList(), lowered.report.notices, "a rig within the record width has nothing to report")
}
/** Drawable moc ids come from sanitized display names, not Cubism ArtMeshN model ids. */
@Test
fun drawableIdsPreferSanitizedDisplayNames() {
val partId = PartId("Part1")
val teeth =
drawable("ArtMesh13", partId).copy(name = "TopTeeth")
val drawstring =
drawable("ArtMesh3", partId).copy(name = "Right Drawstring")
val puppet =
PuppetModel(
parameters = emptyList(),
parts =
listOf(
Part(
id = partId,
name = "Part1",
children = listOf(OrgChild.Drawable(teeth.id), OrgChild.Drawable(drawstring.id)),
),
),
deformers = emptyList(),
drawables = listOf(teeth, drawstring),
rootChildren = listOf(OrgChild.Part(partId)),
rootPartId = null,
canvasWidth = 100f,
canvasHeight = 100f,
)
val lowered = Moc3Export.toMocDocument(puppet, MocVersion.V50)
assertEquals(listOf("TopTeeth", "Right_Drawstring"), lowered.document.artMeshes.map { artMesh -> artMesh.id })
assertEquals(emptyList(), lowered.report.notices)
}
}
@@ -0,0 +1,318 @@
package org.umamo.interop.moc3
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.interop.ExportNotice
import org.umamo.interop.ExportNoticeReason
import org.umamo.interop.moc3.export.Moc3Export
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.Part
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* What [Moc3ExportOptions] includes and omits, and that the options-less default stays the carrying
* behavior the lowering always had.
*
* Synthetic rigs on purpose: the corpus is what the official editor wrote, and its bakes already had
* their hidden objects deleted or carried by the editor's own dialog - the option surface under test
* here is Umamo's.
*/
class Moc3ExportOptionsTest {
/**
* Builds a one-triangle drawable with no keyforms and no deformer parent.
*
* @param String id The drawable's model id.
* @param Boolean isVisible The drawable's own eyeball flag.
* @param List maskedBy The drawables whose alpha clips this one.
* @return Drawable The drawable.
*/
private fun drawable(
id: String,
isVisible: Boolean = true,
maskedBy: List<DrawableId> = emptyList(),
): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = maskedBy,
texturePage = 0,
isVisible = isVisible,
mesh =
DrawableMesh(
positions = floatArrayOf(0f, 0f, 10f, 0f, 0f, 10f),
uvs = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f),
indices = intArrayOf(0, 1, 2),
),
geometryGrid = null,
)
/**
* A rig of the given parts, each owning the drawables its children name.
*
* @param List parts The parts, in panel order; all become root children.
* @param List drawables Every drawable the parts reference.
* @return PuppetModel The rig.
*/
private fun puppetOf(
parts: List<Part>,
drawables: List<Drawable>,
): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = parts,
deformers = emptyList(),
drawables = drawables,
rootChildren = parts.map { part -> OrgChild.Part(part.id) },
rootPartId = null,
canvasWidth = 100f,
canvasHeight = 100f,
)
/**
* A rig with a hidden part whose subtree holds a visible child part, plus a visible part with
* one visible and one own-flag-hidden drawable.
*
* @return PuppetModel The rig.
*/
private fun puppetWithHiddenObjects(): PuppetModel {
val hiddenRootId = PartId("HiddenRoot")
val visibleChildId = PartId("VisibleChild")
val visiblePartId = PartId("VisiblePart")
val underHiddenRoot = drawable("UnderHiddenRoot")
val underVisibleChild = drawable("UnderVisibleChild")
val shown = drawable("Shown")
val ownFlagHidden = drawable("OwnFlagHidden", isVisible = false)
return puppetOf(
parts =
listOf(
Part(
id = hiddenRootId,
name = "HiddenRoot",
children = listOf(OrgChild.Drawable(underHiddenRoot.id), OrgChild.Part(visibleChildId)),
isVisible = false,
),
Part(id = visibleChildId, name = "VisibleChild", children = listOf(OrgChild.Drawable(underVisibleChild.id))),
Part(
id = visiblePartId,
name = "VisiblePart",
children = listOf(OrgChild.Drawable(shown.id), OrgChild.Drawable(ownFlagHidden.id)),
),
),
drawables = listOf(underHiddenRoot, underVisibleChild, shown, ownFlagHidden),
).copy(
// The child part sits under the hidden root, not at the model root.
rootChildren = listOf(OrgChild.Part(hiddenRootId), OrgChild.Part(visiblePartId)),
)
}
/** The reasons of every drop notice in [report], keyed by the dropped drawable's id. */
private fun dropReasonsBySubject(report: List<ExportNotice>): Map<String?, ExportNoticeReason> =
report
.filterIsInstance<ExportNotice.UnsupportedChange>()
.associate { notice -> notice.subject to notice.reason }
/** The options-less export carries every hidden object with its flag clear, exactly as before. */
@Test
fun defaultOptionsCarryHiddenObjectsWithTheFlagClear() {
val lowered = Moc3Export.toMocDocument(puppetWithHiddenObjects(), MocVersion.V50)
assertEquals(
listOf("HiddenRoot", "VisibleChild", "VisiblePart"),
lowered.document.parts.map { part -> part.id },
"a hidden part was dropped without the option asking for it",
)
assertFalse(
lowered.document.parts.first { part -> part.id == "HiddenRoot" }.isVisible,
"the hidden part lost its cleared flag",
)
assertEquals(
listOf("UnderHiddenRoot", "UnderVisibleChild", "Shown", "OwnFlagHidden"),
lowered.document.artMeshes.map { artMesh -> artMesh.id },
)
assertFalse(
lowered.document.artMeshes.first { artMesh -> artMesh.id == "OwnFlagHidden" }.isVisible,
"the hidden art mesh lost its cleared flag",
)
assertEquals(emptyList(), lowered.report.notices, "carrying everything has nothing to report")
}
/** Omitting hidden parts drops the whole subtree - the visible child part included - with notices. */
@Test
fun omittingHiddenPartsDropsTheSubtree() {
val options = Moc3ExportOptions(exportHiddenParts = false)
val lowered = Moc3Export.toMocDocument(puppetWithHiddenObjects(), MocVersion.V50, options = options)
assertEquals(listOf("VisiblePart"), lowered.document.parts.map { part -> part.id })
assertEquals(
listOf("Shown", "OwnFlagHidden"),
lowered.document.artMeshes.map { artMesh -> artMesh.id },
"a drawable under the hidden subtree survived",
)
val reasons = dropReasonsBySubject(lowered.report.notices)
assertEquals(ExportNoticeReason.HiddenPartOmittedByExportOption, reasons["UnderHiddenRoot"])
assertEquals(
ExportNoticeReason.HiddenPartOmittedByExportOption,
reasons["UnderVisibleChild"],
"the hidden-part cascade missed the visible child part's drawable",
)
}
/** Omitting hidden art meshes drops own-flag-hidden drawables and leaves their siblings intact. */
@Test
fun omittingHiddenArtMeshesDropsOwnFlagHiddenDrawables() {
val options = Moc3ExportOptions(exportHiddenDrawables = false)
val lowered = Moc3Export.toMocDocument(puppetWithHiddenObjects(), MocVersion.V50, options = options)
assertEquals(
listOf("UnderHiddenRoot", "UnderVisibleChild", "Shown"),
lowered.document.artMeshes.map { artMesh -> artMesh.id },
"only the own-flag-hidden drawable should drop; hidden PARTS were not omitted",
)
assertEquals(
ExportNoticeReason.HiddenDrawableOmittedByExportOption,
dropReasonsBySubject(lowered.report.notices)["OwnFlagHidden"],
)
}
/** A hidden mask a surviving drawable clips by is kept, flag clear, rather than unclipping it. */
@Test
fun aHiddenMaskASurvivorReferencesIsKept() {
val partId = PartId("Part1")
val mask = drawable("Mask", isVisible = false)
val clipped = drawable("Clipped", maskedBy = listOf(mask.id))
val unreferencedHidden = drawable("UnreferencedHidden", isVisible = false)
val puppet =
puppetOf(
parts =
listOf(
Part(
id = partId,
name = "Part1",
children =
listOf(
OrgChild.Drawable(mask.id),
OrgChild.Drawable(clipped.id),
OrgChild.Drawable(unreferencedHidden.id),
),
),
),
drawables = listOf(mask, clipped, unreferencedHidden),
)
val options = Moc3ExportOptions(exportHiddenDrawables = false)
val lowered = Moc3Export.toMocDocument(puppet, MocVersion.V50, options = options)
assertEquals(
listOf("Mask", "Clipped"),
lowered.document.artMeshes.map { artMesh -> artMesh.id },
"the referenced mask must survive; the unreferenced hidden drawable must not",
)
assertFalse(lowered.document.artMeshes.first { artMesh -> artMesh.id == "Mask" }.isVisible)
assertEquals(
1,
lowered.document.artMeshes.first { artMesh -> artMesh.id == "Clipped" }.maskDrawableIndices.size,
"the survivor's mask reference resolved to nothing",
)
val reasons = dropReasonsBySubject(lowered.report.notices)
assertNull(reasons["Mask"], "the kept mask must not be reported as dropped")
assertEquals(ExportNoticeReason.HiddenDrawableOmittedByExportOption, reasons["UnreferencedHidden"])
assertTrue(
lowered.report.notices.none { notice ->
notice is ExportNotice.UnsupportedChange && notice.reason is ExportNoticeReason.ClippingMaskNotInExport
},
"keeping the mask should leave nothing for the mask filter to report",
)
}
/** Keeping guide-image parts writes the sketch subtree the default drops. */
@Test
fun keepingGuideImagePartsWritesTheSketchSubtree() {
val sketchPartId = PartId("Sketch")
val guide = drawable("Guide")
val puppet =
puppetOf(
parts =
listOf(
Part(id = sketchPartId, name = "Sketch", children = listOf(OrgChild.Drawable(guide.id)), isSketch = true),
),
drawables = listOf(guide),
)
val kept = Moc3Export.toMocDocument(puppet, MocVersion.V50, options = Moc3ExportOptions(exportGuideImageParts = true))
assertEquals(listOf("Guide"), kept.document.artMeshes.map { artMesh -> artMesh.id })
assertEquals(emptyList(), kept.report.notices, "a kept guide has nothing to report")
val dropped = Moc3Export.toMocDocument(puppet, MocVersion.V50)
assertEquals(emptyList(), dropped.document.artMeshes, "the options-less default must still drop the sketch subtree")
}
/** The scale override lands in the canvas record AND rescales the geometry with it. */
@Test
fun pixelsPerUnitOverrideScalesTheBake() {
val partId = PartId("Part1")
val mesh = drawable("ArtMesh1")
val puppet =
puppetOf(
parts = listOf(Part(id = partId, name = "Part1", children = listOf(OrgChild.Drawable(mesh.id)))),
drawables = listOf(mesh),
)
val defaulted = Moc3Export.toMocDocument(puppet, MocVersion.V50)
// pixelsPerUnit is null on the rig, so the heuristic resolves to the canvas width.
assertEquals(100f, defaulted.document.canvas?.pixelsPerUnit)
val doubled =
Moc3Export.toMocDocument(puppet, MocVersion.V50, options = Moc3ExportOptions(pixelsPerUnitOverride = 200f))
assertEquals(200f, doubled.document.canvas?.pixelsPerUnit)
// Twice the pixels per unit means every model-space position is half the size. The record and
// the geometry must come from the same number - a header-only override would fail this.
val defaultedPositions = defaulted.document.artMeshes.single().keyforms.single().vertexPositions
val doubledPositions = doubled.document.artMeshes.single().keyforms.single().vertexPositions
val coordinateIndex = defaultedPositions.indices.first { index -> abs(defaultedPositions[index]) > 1e-6f }
assertEquals(
defaultedPositions[coordinateIndex] / 2f,
doubledPositions[coordinateIndex],
1e-6f,
"the geometry did not follow the overridden scale",
)
}
/** Opting the cdi3 out removes the file and the manifest's reference together. */
@Test
fun omittingTheDisplayInfoDropsTheFileAndTheManifestReference() {
val partId = PartId("Part1")
val mesh = drawable("ArtMesh1")
val puppet =
puppetOf(
parts = listOf(Part(id = partId, name = "Part1", children = listOf(OrgChild.Drawable(mesh.id)))),
drawables = listOf(mesh),
)
val bundle =
Moc3Sidecars.bundle(
puppet,
basename = "rig",
version = MocVersion.V50,
pages = emptyList(),
options = Moc3ExportOptions(includeDisplayInfo = false),
)
assertTrue(bundle.files.none { file -> file.name == "rig.cdi3.json" }, "the opted-out cdi3 was still written")
val manifestFile = bundle.files.first { file -> file.name == "rig.model3.json" }
val manifest = Moc3.readModel3(manifestFile.bytes.decodeToString())
assertNull(manifest.fileReferences.displayInfo, "the manifest still references the opted-out cdi3")
}
}
@@ -0,0 +1,265 @@
package org.umamo.interop.moc3
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.CanvasInfo
import org.umamo.format.moc3.moc.MocParameter
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.format.moc3.moc.ParameterType
import org.umamo.format.moc3.model.ArtMesh
import org.umamo.format.moc3.model.ArtMeshKeyform
import org.umamo.format.moc3.model.Deformer
import org.umamo.format.moc3.model.KeyformBinding
import org.umamo.format.moc3.model.Part
import org.umamo.format.moc3.model.WarpDeformer
import org.umamo.format.moc3.model.WarpKeyform
import org.umamo.interop.moc3.import.Moc3Import
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Hand-built-document tests for the two identity fallbacks [Moc3Import] applies when a MOC3 does not
* carry what the corpus always carries: a blank or duplicated id (MOC3 §5.4) and an absent
* deformer→part column (s15).
*
* The corpus cannot reach either path - every sample has unique non-empty ids and an s15 that places
* something - so these are synthetic documents rather than corpus gates. The inputs are exactly the
* shapes a stripped, third-party, or synthesized MOC3 produces, which is the case `MocDecoder` reads
* the block's common head defensively for.
*
* @see <a href="https://docs.umamo.org/format/MOC3.md">MOC3.md §5.4</a>
*/
class Moc3ImportIdentityTest {
/**
* Builds a one-keyform warp deformer (a 2x2 lattice), static on binding 0.
*
* @param String id The s11 id, possibly blank.
* @param Int parentPartIndex The s15 part index, -1 at the root.
* @return WarpDeformer The deformer.
*/
private fun staticWarp(id: String, parentPartIndex: Int): WarpDeformer =
WarpDeformer(
id = id,
keyformBindingIndex = 0,
isVisible = true,
isEnabled = true,
parentPartIndex = parentPartIndex,
parentDeformerIndex = -1,
rows = 1,
columns = 1,
mode = 0,
keyforms = listOf(WarpKeyform(FloatArray(8), opacity = 1f, multiplyColor = null, screenColor = null)),
)
/**
* Builds a one-keyform, one-triangle art mesh, static on binding 0.
*
* @param String id The s33 id.
* @param Int parentPartIndex The s39 part index, -1 at the root.
* @param Int parentDeformerIndex The s40 deformer index, -1 when parented to the part.
* @return ArtMesh The drawable.
*/
private fun staticMesh(id: String, parentPartIndex: Int, parentDeformerIndex: Int): ArtMesh =
ArtMesh(
id = id,
textureIndex = 0,
constantFlags = 0,
parentPartIndex = parentPartIndex,
parentDeformerIndex = parentDeformerIndex,
vertexUvs = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f),
triangleIndices = shortArrayOf(0, 1, 2),
maskDrawableIndices = IntArray(0),
keyformBindingIndex = 0,
keyforms =
listOf(
ArtMeshKeyform(
vertexPositions = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f),
opacity = 1f,
drawOrder = 500f,
multiplyColor = null,
screenColor = null,
),
),
)
/**
* Assembles a document around the given deformers and meshes. Binding 0 is the zero-axis static
* binding every corpus file reserves, which is what makes every object here static.
*
* @param List deformers The deformer list, in file order.
* @param List artMeshes The drawable list, in file order.
* @param List parts The part list, in file order.
* @param List parameters The parameter list, in file order.
* @return MocDocument The assembled document.
*/
private fun documentOf(
deformers: List<Deformer>,
artMeshes: List<ArtMesh>,
parts: List<Part> = listOf(part("PartHead"), part("PartBody")),
parameters: List<MocParameter> = emptyList(),
): MocDocument =
MocDocument(
version = MocVersion.V50,
canvas = CanvasInfo(pixelsPerUnit = 1f, originX = 0f, originY = 0f, width = 100f, height = 100f),
parameters = parameters,
keyformBindings = mapOf(0 to KeyformBinding(index = 0, axes = emptyList())),
parts = parts,
deformers = deformers,
artMeshes = artMeshes,
glues = emptyList(),
renderOrderGroups = emptyList(),
)
/**
* Builds a static root part.
*
* @param String id The part id.
* @return Part The part.
*/
private fun part(id: String): Part =
Part(id = id, parentPartIndex = -1, keyformBindingIndex = 0, drawOrderKeyforms = floatArrayOf(0f))
/**
* Builds a plain parameter axis.
*
* @param String id The parameter id.
* @param Float defaultValue Its default, which is also what the keyform grid samples at rest.
* @return MocParameter The parameter.
*/
private fun parameter(
id: String,
defaultValue: Float,
): MocParameter =
MocParameter(
id = id,
minimumValue = -30f,
maximumValue = 30f,
defaultValue = defaultValue,
type = ParameterType.NORMAL,
)
/**
* A blank id, a duplicate id, and a file id that collides with what the synthesizer would have
* produced must all still yield distinct runtime ids, with the file's own ids kept verbatim.
*
* The collision is the interesting slot: deformer 0 is blank, so it synthesizes from its index and
* would take "Deformer0" - which deformer 3 already carries in the file. The synthesizer has to
* dodge it rather than duplicate it, because the org tree and every cross-reference key off the id.
*/
@Test
fun blankDuplicateAndCollidingDeformerIdsResolveDistinctly() {
val document =
documentOf(
deformers =
listOf(
staticWarp(id = "", parentPartIndex = 0),
staticWarp(id = "A", parentPartIndex = 0),
staticWarp(id = "A", parentPartIndex = 0),
staticWarp(id = "Deformer0", parentPartIndex = 0),
),
artMeshes = emptyList(),
)
val ids = Moc3Import.fromMocDocument(document, displayInfo = null).deformers.map { it.id.raw }
assertEquals(4, ids.toSet().size, "every deformer id is distinct: $ids")
// The first claimant of a file id keeps it; the later duplicate is the one that gets renamed.
assertEquals("A", ids[1], "first claimant keeps its file id")
assertTrue(ids[2] != "A", "the duplicate slot does not reuse the id")
// A real file id always outranks a synthesized one, even when the synthesizer wanted it first.
assertEquals("Deformer0", ids[3], "a file id is kept verbatim")
assertTrue(ids[0] != "Deformer0", "the synthesized id dodges the file id it would have collided with")
}
/**
* The same rule holds for the other three id spaces, which a moc leaves just as unconstrained.
*
* Reachable through Umamo's own export, not only through a hand-built file: an id too wide for the
* 64-byte record is written shortened, so two names differing past the 63rd byte can arrive here as
* one. Merging them would put both meshes' masks, part membership, and keyforms on one drawable and
* leave the other with none - a silent identity merge on a round trip, which is why every id space
* de-duplicates rather than only the deformers'.
*/
@Test
fun duplicateParameterPartAndDrawableIdsResolveDistinctly() {
val document =
documentOf(
deformers = emptyList(),
artMeshes =
listOf(
staticMesh("Mesh", parentPartIndex = 0, parentDeformerIndex = -1),
staticMesh("Mesh", parentPartIndex = 1, parentDeformerIndex = -1),
),
parts = listOf(part("Part"), part("Part")),
parameters = listOf(parameter("ParamAngleX", defaultValue = 0f), parameter("ParamAngleX", defaultValue = 30f)),
)
val puppet = Moc3Import.fromMocDocument(document, displayInfo = null)
val parameterIds = puppet.parameters.map { it.id.raw }
assertEquals(2, parameterIds.toSet().size, "every parameter id is distinct: $parameterIds")
assertEquals("ParamAngleX", parameterIds[0], "the first claimant keeps its file id")
// Both defaults survive: an id-keyed lookup over the raw file ids would give the first parameter
// the second's default, which is what a blend record on it would then be resolved against.
assertEquals(listOf(0f, 30f), puppet.parameters.map { it.default }, "each parameter keeps its own default")
val drawableIds = puppet.drawables.map { it.id.raw }
assertEquals(2, drawableIds.toSet().size, "every drawable id is distinct: $drawableIds")
assertTrue("Mesh" in drawableIds, "the first claimant keeps its file id")
val partIds = puppet.parts.map { it.id.raw }
assertEquals(2, partIds.toSet().size, "every part id is distinct: $partIds")
assertEquals("Part", partIds[0], "the first claimant keeps its file id")
// Each part keeps its OWN drawable rather than both landing in one: the merge this guards against
// is invisible in an id list, but it shows up here as an empty part.
assertTrue(
puppet.parts.all { part -> part.children.size == 1 },
"each part keeps its own drawable: ${puppet.parts.map { part -> part.children.size }}",
)
}
/**
* With s15 absent (every deformer at -1) the org tree would be flat, so membership is inferred from
* the drawables each deformer deforms.
*/
@Test
fun deformerPartsAreInferredWhenSection15PlacesNothing() {
val document =
documentOf(
deformers = listOf(staticWarp("Warp0", parentPartIndex = -1), staticWarp("Warp1", parentPartIndex = -1)),
artMeshes =
listOf(
staticMesh("Mesh0", parentPartIndex = 0, parentDeformerIndex = 0),
staticMesh("Mesh1", parentPartIndex = 1, parentDeformerIndex = 1),
),
)
val deformers = Moc3Import.fromMocDocument(document, displayInfo = null).deformers.associateBy { it.id.raw }
assertEquals("PartHead", deformers.getValue("Warp0").partId?.raw, "inferred from its own drawable")
assertEquals("PartBody", deformers.getValue("Warp1").partId?.raw, "inferred from its own drawable")
}
/**
* s15 is authoritative: when it places even one deformer, nothing is inferred - a deformer the file
* really does put at the root stays there rather than being pulled into a drawable's part.
*/
@Test
fun section15WinsWheneverItPlacesAnything() {
val document =
documentOf(
// Warp1 is deliberately at the root while deforming a drawable that lives in PartBody -
// exactly the disagreement inference would "fix" if it were allowed to run.
deformers = listOf(staticWarp("Warp0", parentPartIndex = 0), staticWarp("Warp1", parentPartIndex = -1)),
artMeshes =
listOf(
staticMesh("Mesh0", parentPartIndex = 0, parentDeformerIndex = 0),
staticMesh("Mesh1", parentPartIndex = 1, parentDeformerIndex = 1),
),
)
val deformers = Moc3Import.fromMocDocument(document, displayInfo = null).deformers.associateBy { it.id.raw }
assertEquals("PartHead", deformers.getValue("Warp0").partId?.raw, "s15 placement is kept")
assertNull(deformers.getValue("Warp1").partId, "a root deformer stays at the root")
}
}
@@ -0,0 +1,102 @@
package org.umamo.interop.moc3
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* The MOC3 coordinate seam round-trips to float precision.
*
* Every value an export writes goes through one of these inverses, so a discrepancy here is a
* discrepancy in every exported position at once - and one that a semantic round trip cannot see,
* because it would convert and unconvert with the same wrong pair and cancel.
*
* The rotation scale seam gets its own case because it is the one piece of this that is not a
* per-value transform: which factor applies depends on a deformer's ANCESTRY, so the two directions
* can agree on the arithmetic and still disagree on which deformers it applies to.
*/
class Moc3SpaceSeamTest {
private val canvas = MocCanvasMapping(pixelsPerUnit = 900f, originX = 450f, originY = 600f)
/** Values chosen to span sign, magnitude, and zero rather than a single happy sample. */
private val points = floatArrayOf(0f, 0f, 1.5f, -2.25f, -1000f, 1000f, 0.001f, -0.001f)
@Test
fun pointsRoundTripThroughEverySpace() {
for (space in PointSpace.entries) {
val stored = convertPointsToMoc(space, convertPointsToRuntime(space, points, canvas), canvas)
for (index in points.indices) {
assertTrue(
kotlin.math.abs(stored[index] - points[index]) <= 1e-3f,
"$space point[$index]: ${points[index]} -> ${stored[index]}",
)
}
}
}
@Test
fun deltasRoundTripThroughEverySpace() {
for (space in PointSpace.entries) {
val stored = convertDeltasToMoc(space, convertDeltasToRuntime(space, points, canvas), canvas)
for (index in points.indices) {
assertTrue(
kotlin.math.abs(stored[index] - points[index]) <= 1e-3f,
"$space delta[$index]: ${points[index]} -> ${stored[index]}",
)
}
}
}
/**
* A delta must NOT pick up the canvas origin - it cancels out of a difference - while a point must.
* Getting this wrong shifts every keyed offset by the origin, which looks like a plausible rig at
* the default pose and falls apart the moment a parameter moves.
*/
@Test
fun rootSpaceDeltasScaleButDoNotTranslate() {
val delta = floatArrayOf(1f, 1f)
val asDelta = convertDeltasToRuntime(PointSpace.ModelRoot, delta, canvas)
val asPoint = convertPointsToRuntime(PointSpace.ModelRoot, delta, canvas)
assertEquals(900f, asDelta[0], "a root delta scales by ppu alone")
assertEquals(450f + 900f, asPoint[0], "a root point also translates by the origin")
}
/** A zero pixels-per-unit substitutes a unit scale, so the stored values stay finite rather than infinite. */
@Test
fun aDegenerateCanvasIsTheIdentity() {
val degenerate = MocCanvasMapping(pixelsPerUnit = 0f, originX = 0f, originY = 0f)
val stored = convertPointsToMoc(PointSpace.ModelRoot, points, degenerate)
for (value in stored) {
assertTrue(value.isFinite(), "a zero ppu must not produce infinities: $value")
}
}
/**
* Only the FIRST rotation on each root path carries the px→model factor.
*
* Chain: rootRotation -> warp -> nestedRotation. The nested rotation's direct parent is a WARP, so
* a predicate that only looked at the immediate parent would wrongly give it the factor too - the
* question is whether a rotation appears anywhere above, not directly above.
*/
@Test
fun onlyTheFirstRotationOnAPathCarriesTheUnitFactor() {
val parents = intArrayOf(-1, 0, 1)
val isRotation = booleanArrayOf(true, false, true)
val flags = rotationAncestorFlags(3, { parents[it] }, { isRotation[it] })
assertTrue(!flags[0], "the root rotation has no rotation above it")
assertTrue(flags[1], "the warp sits under a rotation")
assertTrue(flags[2], "the nested rotation sits under one too, through the warp")
assertEquals(900f, rotationScaleFactor(flags[0], canvas), "the first rotation carries the factor")
assertEquals(1f, rotationScaleFactor(flags[2], canvas), "a nested rotation inherits it instead")
}
/** A malformed parent cycle terminates instead of hanging the export. */
@Test
fun aCyclicParentChainTerminates() {
val parents = intArrayOf(1, 0)
val flags = rotationAncestorFlags(2, { parents[it] }, { false })
assertTrue(flags.none { it }, "no rotation exists, cycle or not")
}
}
@@ -0,0 +1,270 @@
package org.umamo.interop.moc3
import org.umamo.format.moc3.moc.MocVersion
import org.umamo.interop.ExportNotice
import org.umamo.interop.moc3.export.Moc3VersionDowngrade
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RuntimeFeature
import org.umamo.runtime.model.RuntimeTarget
import org.umamo.runtime.model.WarpForm
import org.umamo.runtime.model.unsupportedFeaturesInUse
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertTrue
/**
* The version strip removes exactly what the target cannot load, and says what it removed.
*
* Built on one kitchen-sink rig rather than a model per feature, because the interesting property is
* that the strips COMPOSE: a Cubism 3.0 export runs eight of them over the same model in sequence,
* and a strip that rebuilt a list from the original instead of from the running copy would silently
* undo whichever strip ran before it.
*
* The corpus-backed half of this lives in `Moc3DowngradeOracleTest`, which proves the stripped files
* actually load; this half proves the model-level rules without needing a corpus or a C core.
*/
class Moc3VersionDowngradeTest {
private val morphParameter = ParameterId("ParamMorph")
/** A rig using every restricted feature that [PuppetModel] can express. */
private fun kitchenSink(): PuppetModel {
val warp =
Deformer.Warp(
id = DeformerId("Warp1"),
name = "Warp1",
parent = null,
partId = PartId("Part1"),
rows = 2,
columns = 2,
isQuadTransform = true,
geometryGrid = null,
multiplyColor = ColorRgb(0.5f, 0.5f, 0.5f),
blendShapes =
listOf(
BlendShapeBinding(
parameterId = morphParameter,
keys = floatArrayOf(0f, 1f),
neutralIndex = 0,
forms = listOf(null, WarpForm(FloatArray(8))),
),
),
)
val rotation =
Deformer.Rotation(
id = DeformerId("Rotation1"),
name = "Rotation1",
parent = null,
partId = PartId("Part1"),
baseAngle = 0f,
geometryGrid = null,
screenColor = ColorRgb(0.25f, 0.25f, 0.25f),
blendShapes =
listOf(
BlendShapeBinding(
parameterId = morphParameter,
keys = floatArrayOf(0f, 1f),
neutralIndex = 0,
forms = listOf(null, null),
),
),
)
val drawable =
Drawable(
id = DrawableId("ArtMesh1"),
name = "ArtMesh1",
parentDeformerId = null,
blendMode = BlendMode.Overlay,
maskedBy = emptyList(),
mesh = null,
geometryGrid = null,
alphaBlendMode = AlphaBlendMode.Atop,
invertMask = true,
blendShapes =
listOf(
BlendShapeBinding(
parameterId = morphParameter,
keys = floatArrayOf(0f, 1f),
neutralIndex = 0,
forms = listOf<MeshForm?>(null, MeshForm(FloatArray(0))),
),
),
)
val part =
Part(
id = PartId("Part1"),
name = "Part1",
children = listOf(OrgChild.Drawable(drawable.id)),
groupMode = PartGroupMode.Isolated,
composite =
PartComposite(
blendMode = BlendMode.Screen,
alphaBlendMode = AlphaBlendMode.Out,
invertMask = true,
multiplyColor = ColorRgb(0.5f, 0.5f, 0.5f),
),
)
return PuppetModel(
parameters =
listOf(
Parameter(morphParameter, "Morph", 0f, 1f, 0f, ParameterKind.BLEND_SHAPE),
Parameter(ParameterId("ParamWheel"), "Wheel", 0f, 360f, 0f, repeat = true),
),
parts = listOf(part),
deformers = listOf(warp, rotation),
drawables = listOf(drawable),
rootChildren = listOf(OrgChild.Part(part.id)),
rootPartId = null,
)
}
/**
* The features named by notices, for comparing against the scan.
*
* @param List notices The strip's notices.
* @return Set The features reported.
*/
private fun strippedFeatures(notices: List<ExportNotice>): Set<RuntimeFeature> =
notices.filterIsInstance<ExportNotice.FeatureStripped>().map { it.feature }.toSet()
@Test
fun theOldestTargetStripsEveryRepresentableFeature() {
val original = kitchenSink()
val stripped = Moc3VersionDowngrade.strip(original, MocVersion.V30)
val puppet = stripped.puppet
val warp = puppet.deformers.first { it is Deformer.Warp } as Deformer.Warp
val rotation = puppet.deformers.first { it is Deformer.Rotation } as Deformer.Rotation
val drawable = puppet.drawables.single()
val part = puppet.parts.single()
assertFalse(warp.isQuadTransform, "the 3.3 warp method must be gone")
assertEquals(emptyList(), warp.blendShapes, "warp blend shapes must be gone")
assertEquals(emptyList(), rotation.blendShapes, "rotation blend shapes must be gone")
assertEquals(emptyList(), drawable.blendShapes, "mesh blend shapes must be gone")
// NOT stripped at v1: the mask bit and the repeat section exist in every moc version, whatever
// the editor's target dialog says about when a rigger may author them.
assertTrue(drawable.invertMask, "the reversed mask is carried by every version")
assertTrue(puppet.parameters.any { it.repeat }, "the repeat flag is carried by every version")
assertEquals(BlendMode.Normal, drawable.blendMode, "Overlay has no pre-5.3 ancestor")
assertEquals(AlphaBlendMode.Over, drawable.alphaBlendMode, "the alpha mode must be back to Over")
assertEquals(ColorRgb.MultiplyIdentity, warp.multiplyColor, "the warp tint must be gone")
assertEquals(ColorRgb.ScreenIdentity, rotation.screenColor, "the rotation tint must be gone")
assertEquals(PartGroupMode.Grouped, part.groupMode, "an isolated part must demote to grouped")
assertEquals(
ParameterKind.NORMAL,
puppet.parameters.first { it.id == morphParameter }.kind,
"a blend-shape parameter must demote to normal",
)
// The pre-export scan and the strip differ by exactly the two features the editor gates later
// than the file format does - the scan over-warns about them, and pinning that here is what keeps
// the difference deliberate instead of a drift nobody notices.
assertEquals(
original.unsupportedFeaturesInUse(RuntimeTarget.Cubism30) -
setOf(RuntimeFeature.ReversedMask, RuntimeFeature.ParameterRepeat),
strippedFeatures(stripped.notices) -
setOf(RuntimeFeature.ReversedMask, RuntimeFeature.ParameterRepeat),
"the strip and the scan disagree about what a 3.0 export loses",
)
}
@Test
fun theSourceModelIsNeverMutated() {
val original = kitchenSink()
val before = original.unsupportedFeaturesInUse(RuntimeTarget.Cubism30)
Moc3VersionDowngrade.strip(original, MocVersion.V30)
assertEquals(
before,
original.unsupportedFeaturesInUse(RuntimeTarget.Cubism30),
"the caller's model must still use everything it started with",
)
assertTrue(before.isNotEmpty(), "the fixture must actually use restricted features")
}
@Test
fun eachTargetStripsOnlyWhatItsVersionPredates() {
val original = kitchenSink()
// 5.0 keeps blend shapes and color, and loses only the two 5.3 features in use.
val toFiveZero = Moc3VersionDowngrade.strip(original, MocVersion.V50)
assertEquals(
setOf(RuntimeFeature.ExtendedBlendModes, RuntimeFeature.PartComposite),
strippedFeatures(toFiveZero.notices),
)
assertEquals(
1,
(toFiveZero.puppet.deformers.first { it is Deformer.Warp } as Deformer.Warp).blendShapes.size,
"5.0 carries warp blend shapes",
)
assertEquals(
ColorRgb(0.5f, 0.5f, 0.5f),
(toFiveZero.puppet.deformers.first { it is Deformer.Warp } as Deformer.Warp).multiplyColor,
"5.0 carries deformer color",
)
// 4.2 additionally loses the rotation-target blend record, but keeps the mesh and warp ones.
val toFourTwo = Moc3VersionDowngrade.strip(original, MocVersion.V42)
assertTrue(RuntimeFeature.ExtendedBlendShapes in strippedFeatures(toFourTwo.notices))
assertEquals(
1,
toFourTwo.puppet.drawables.single().blendShapes.size,
"4.2 carries mesh blend shapes",
)
// 5.3 is the ceiling: nothing is stripped and the model comes back unchanged.
val toFiveThree = Moc3VersionDowngrade.strip(original, MocVersion.V53)
assertEquals(emptyList(), toFiveThree.notices)
assertTrue(toFiveThree.puppet === original, "an unrestricted target must not copy the model")
}
@Test
fun aColourTrackIsDroppedAlongWithTheStatic() {
val original = kitchenSink()
val tracked =
original.copy(
drawables =
original.drawables.map { drawable ->
drawable.copy(
multiplyColor = ColorRgb(0.5f, 0.5f, 0.5f),
channelGrids = ChannelGrids(mapOf(FormChannel.MULTIPLY_COLOR to colourTrack())),
)
},
)
val stripped = Moc3VersionDowngrade.strip(tracked, MocVersion.V40).puppet.drawables.single()
assertEquals(ColorRgb.MultiplyIdentity, stripped.multiplyColor, "the static must reset")
assertEquals(null, stripped.channelGrids[FormChannel.MULTIPLY_COLOR], "the track must go with it")
}
/**
* A one-cell multiply track, enough to make the channel count as in use.
*
* @return KeyformGrid The track.
*/
private fun colourTrack(): KeyformGrid<ChannelValue> =
KeyformGrid(
axes = emptyList(),
cells = listOf(KeyformCell(intArrayOf(), ChannelValue.Color(ColorRgb(0.5f, 0.5f, 0.5f)))),
)
}
@@ -0,0 +1,519 @@
package org.umamo.interop.uma
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.PartForm
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RenderDrawable
import org.umamo.runtime.model.RenderGroup
import org.umamo.runtime.model.RenderNode
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.WarpForm
/*
* The structural comparer the UMA round-trip tests share: every field the puppet entry carries - structure,
* meshes, keyform grids, channel tracks, blend shapes, glue - and the derived render root, compared exactly:
* floats by their bits, since a shortest-round-trip decimal and a buffer both give back the same bits and
* anything less is a bug.
*/
/**
* Collects differences between an expected and an actual value by path.
*
* @property MutableList differences One line per difference.
*/
private class DifferenceCollector(val differences: MutableList<String> = ArrayList()) {
/**
* Records a difference when two values are not equal.
*
* @param String path Where the values sit.
* @param Any? expected The expected value.
* @param Any? actual The actual value.
*/
fun same(path: String, expected: Any?, actual: Any?) {
if (expected != actual) {
differences += "$path: expected $expected, got $actual"
}
}
/**
* Records a difference when two floats differ in any bit.
*
* @param String path Where the values sit.
* @param Float expected The expected value.
* @param Float actual The actual value.
*/
fun bits(path: String, expected: Float, actual: Float) {
if (expected.toRawBits() != actual.toRawBits()) {
differences += "$path: expected $expected (0x${expected.toRawBits().toUInt().toString(16)}), got $actual (0x${actual.toRawBits().toUInt().toString(16)})"
}
}
/**
* Records a difference when two colors differ in any channel's bits.
*
* @param String path Where the values sit.
* @param ColorRgb expected The expected color.
* @param ColorRgb actual The actual color.
*/
fun color(path: String, expected: ColorRgb, actual: ColorRgb) {
bits("$path.red", expected.red, actual.red)
bits("$path.green", expected.green, actual.green)
bits("$path.blue", expected.blue, actual.blue)
}
/**
* Records a difference when two float arrays differ in length or in any bit.
*
* @param String path Where the arrays sit.
* @param FloatArray expected The expected array.
* @param FloatArray actual The actual array.
*/
fun floats(path: String, expected: FloatArray, actual: FloatArray) {
if (expected.size != actual.size) {
differences += "$path: expected ${expected.size} floats, got ${actual.size}"
return
}
val first = expected.indices.firstOrNull { valueIndex -> expected[valueIndex].toRawBits() != actual[valueIndex].toRawBits() } ?: return
differences += "$path[$first]: expected ${expected[first]}, got ${actual[first]}"
}
/**
* Records a difference when two int arrays differ.
*
* @param String path Where the arrays sit.
* @param IntArray expected The expected array.
* @param IntArray actual The actual array.
*/
fun ints(path: String, expected: IntArray, actual: IntArray) {
if (!expected.contentEquals(actual)) {
differences += "$path: the arrays differ"
}
}
/**
* Compares two optional meshes.
*
* @param String path Where the meshes sit.
* @param DrawableMesh? expected The expected mesh.
* @param DrawableMesh? actual The actual mesh.
*/
fun mesh(path: String, expected: DrawableMesh?, actual: DrawableMesh?) {
if (expected == null || actual == null) {
same("$path present", expected != null, actual != null)
return
}
floats("$path.positions", expected.positions, actual.positions)
floats("$path.uvs", expected.uvs, actual.uvs)
ints("$path.indices", expected.indices, actual.indices)
}
/**
* Compares two optional keyform grids: axes, cell order, coordinates, and each cell's form.
*
* @param String path Where the grids sit.
* @param KeyformGrid? expected The expected grid.
* @param KeyformGrid? actual The actual grid.
* @param Function compareForm Compares one pair of forms given its path.
*/
fun <T> grid(path: String, expected: KeyformGrid<T>?, actual: KeyformGrid<T>?, compareForm: (String, T, T) -> Unit) {
if (expected == null || actual == null) {
same("$path present", expected != null, actual != null)
return
}
each("$path.axes", expected.axes, actual.axes) { axisPath, left, right ->
same("$axisPath.parameter", left.parameterId, right.parameterId)
floats("$axisPath.keys", left.keys, right.keys)
}
each("$path.cells", expected.cells, actual.cells) { cellPath, left, right ->
ints("$cellPath.coordinate", left.coordinate, right.coordinate)
compareForm(cellPath, left.form, right.form)
}
}
/**
* Compares two owners' channel tracks, channel by channel.
*
* @param String path Where the tracks sit.
* @param ChannelGrids expected The expected tracks.
* @param ChannelGrids actual The actual tracks.
*/
fun channels(path: String, expected: ChannelGrids, actual: ChannelGrids) {
same("$path.channels keys", expected.gridsByChannel.keys, actual.gridsByChannel.keys)
for ((channel, expectedGrid) in expected.gridsByChannel) {
val actualGrid = actual.gridsByChannel[channel] ?: continue
grid("$path.channels.${channel.name}", expectedGrid, actualGrid) { valuePath, left, right -> channelValue("$valuePath.value", left, right) }
}
}
/**
* Compares two channel values by kind and bits.
*
* @param String path Where the values sit.
* @param ChannelValue expected The expected value.
* @param ChannelValue actual The actual value.
*/
fun channelValue(path: String, expected: ChannelValue, actual: ChannelValue) {
when {
expected is ChannelValue.Scalar && actual is ChannelValue.Scalar -> bits(path, expected.value, actual.value)
expected is ChannelValue.Color && actual is ChannelValue.Color -> color(path, expected.color, actual.color)
expected is ChannelValue.Flag && actual is ChannelValue.Flag -> same(path, expected.flag, actual.flag)
else -> differences += "$path: expected a ${expected::class.simpleName}, got a ${actual::class.simpleName}"
}
}
/**
* Compares two owners' blend-shape bindings: parameters, keys, neutrals, forms, and limits.
*
* @param String path Where the bindings sit.
* @param List expected The expected bindings.
* @param List actual The actual bindings.
* @param Function compareForm Compares one pair of non-null forms given its path.
*/
fun <T : Any> blendShapes(path: String, expected: List<BlendShapeBinding<T>>, actual: List<BlendShapeBinding<T>>, compareForm: (String, T, T) -> Unit) {
each("$path.blendShapes", expected, actual) { bindingPath, left, right ->
same("$bindingPath.parameter", left.parameterId, right.parameterId)
floats("$bindingPath.keys", left.keys, right.keys)
same("$bindingPath.neutralIndex", left.neutralIndex, right.neutralIndex)
each("$bindingPath.forms", left.forms, right.forms) { formPath, leftForm, rightForm ->
if (leftForm == null || rightForm == null) {
same("$formPath present", leftForm != null, rightForm != null)
} else {
compareForm(formPath, leftForm, rightForm)
}
}
each("$bindingPath.limits", left.limits, right.limits) { limitPath, leftLimit, rightLimit ->
same("$limitPath.parameter", leftLimit.parameterId, rightLimit.parameterId)
each("$limitPath.points", leftLimit.points, rightLimit.points) { pointPath, leftPoint, rightPoint ->
bits("$pointPath.value", leftPoint.value, rightPoint.value)
bits("$pointPath.weight", leftPoint.weight, rightPoint.weight)
}
}
}
}
/**
* Compares two render-tree nodes and their subtrees.
*
* @param String path Where the nodes sit.
* @param RenderNode expected The expected node.
* @param RenderNode actual The actual node.
*/
fun renderNode(path: String, expected: RenderNode, actual: RenderNode) {
when {
expected is RenderDrawable && actual is RenderDrawable -> same("$path.id", expected.id, actual.id)
expected is RenderGroup && actual is RenderGroup -> {
same("$path.partId", expected.partId, actual.partId)
same("$path.drawOrder", expected.drawOrder, actual.drawOrder)
same("$path.composite", expected.composite, actual.composite)
channels(path, expected.channelGrids, actual.channelGrids)
each("$path.children", expected.children, actual.children) { childPath, left, right -> renderNode(childPath, left, right) }
}
else -> differences += "$path: expected a ${expected::class.simpleName}, got a ${actual::class.simpleName}"
}
}
/**
* Compares two lists element by element after checking their sizes.
*
* @param String path Where the lists sit.
* @param List expected The expected list.
* @param List actual The actual list.
* @param Function compare Compares one pair of elements given its path.
*/
fun <T> each(path: String, expected: List<T>, actual: List<T>, compare: (String, T, T) -> Unit) {
if (expected.size != actual.size) {
differences += "$path: expected ${expected.size} elements, got ${actual.size}"
return
}
for (elementIndex in expected.indices) {
compare("$path[$elementIndex]", expected[elementIndex], actual[elementIndex])
}
}
}
/**
* Every difference between two models across the structure the puppet entry carries.
*
* @param PuppetModel expected The model before the round trip.
* @param PuppetModel actual The model after it.
* @return List<String> One line per difference; empty when the structure is identical.
*/
internal fun puppetStructureDifferences(expected: PuppetModel, actual: PuppetModel): List<String> {
val collector = DifferenceCollector()
with(collector) {
bits("canvasWidth", expected.canvasWidth, actual.canvasWidth)
bits("canvasHeight", expected.canvasHeight, actual.canvasHeight)
bits("worldOriginX", expected.worldOriginX, actual.worldOriginX)
bits("worldOriginZ", expected.worldOriginZ, actual.worldOriginZ)
same("pixelsPerUnit bits", expected.pixelsPerUnit?.toRawBits(), actual.pixelsPerUnit?.toRawBits())
same("runtimeTarget", expected.runtimeTarget, actual.runtimeTarget)
same("rendersFromSourceLayers", expected.rendersFromSourceLayers, actual.rendersFromSourceLayers)
same("rootPartId", expected.rootPartId, actual.rootPartId)
same("rootChildren", expected.rootChildren, actual.rootChildren)
same("parameterLinks", expected.parameterLinks, actual.parameterLinks)
same("parameterTree", expected.parameterTree, actual.parameterTree)
each("parameters", expected.parameters, actual.parameters) { path, left, right ->
same("$path.id", left.id, right.id)
same("$path.name", left.name, right.name)
bits("$path.min", left.min, right.min)
bits("$path.max", left.max, right.max)
bits("$path.default", left.default, right.default)
same("$path.kind", left.kind, right.kind)
same("$path.repeat", left.repeat, right.repeat)
}
each("parts", expected.parts, actual.parts) { path, left, right ->
same("$path.id", left.id, right.id)
same("$path.name", left.name, right.name)
same("$path.children", left.children, right.children)
same("$path.isVisible", left.isVisible, right.isVisible)
same("$path.isSketch", left.isSketch, right.isSketch)
same("$path.isSelectable", left.isSelectable, right.isSelectable)
same("$path.groupMode", left.groupMode, right.groupMode)
same("$path.drawOrder", left.drawOrder, right.drawOrder)
val leftComposite = left.composite
val rightComposite = right.composite
same("$path.composite.blendMode", leftComposite.blendMode, rightComposite.blendMode)
same("$path.composite.alphaBlendMode", leftComposite.alphaBlendMode, rightComposite.alphaBlendMode)
same("$path.composite.maskedBy", leftComposite.maskedBy, rightComposite.maskedBy)
same("$path.composite.maskedByParts", leftComposite.maskedByParts, rightComposite.maskedByParts)
same("$path.composite.invertMask", leftComposite.invertMask, rightComposite.invertMask)
bits("$path.composite.opacity", leftComposite.opacity, rightComposite.opacity)
color("$path.composite.multiplyColor", leftComposite.multiplyColor, rightComposite.multiplyColor)
color("$path.composite.screenColor", leftComposite.screenColor, rightComposite.screenColor)
channels(path, left.channelGrids, right.channelGrids)
blendShapes(path, left.blendShapes, right.blendShapes) { formPath, leftForm: PartForm, rightForm -> partForm(formPath, leftForm, rightForm) }
}
each("deformers", expected.deformers, actual.deformers) { path, left, right ->
same("$path.id", left.id, right.id)
same("$path.name", left.name, right.name)
same("$path.parent", left.parent, right.parent)
same("$path.partId", left.partId, right.partId)
same("$path.isVisible", left.isVisible, right.isVisible)
same("$path.isEnabled", left.isEnabled, right.isEnabled)
same("$path.isSelectable", left.isSelectable, right.isSelectable)
when {
left is Deformer.Warp && right is Deformer.Warp -> {
same("$path.rows", left.rows, right.rows)
same("$path.columns", left.columns, right.columns)
same("$path.isQuadTransform", left.isQuadTransform, right.isQuadTransform)
bits("$path.opacity", left.opacity, right.opacity)
color("$path.multiplyColor", left.multiplyColor, right.multiplyColor)
color("$path.screenColor", left.screenColor, right.screenColor)
grid("$path.geometry", left.geometryGrid, right.geometryGrid) { formPath, leftForm, rightForm -> floats("$formPath.controlPoints", leftForm.controlPoints, rightForm.controlPoints) }
blendShapes(path, left.blendShapes, right.blendShapes) { formPath, leftForm: WarpForm, rightForm -> warpForm(formPath, leftForm, rightForm) }
}
left is Deformer.Rotation && right is Deformer.Rotation -> {
bits("$path.baseAngle", left.baseAngle, right.baseAngle)
same("$path.flipX", left.flipX, right.flipX)
same("$path.flipY", left.flipY, right.flipY)
bits("$path.opacity", left.opacity, right.opacity)
color("$path.multiplyColor", left.multiplyColor, right.multiplyColor)
color("$path.screenColor", left.screenColor, right.screenColor)
grid("$path.geometry", left.geometryGrid, right.geometryGrid) { formPath, leftForm, rightForm ->
bits("$formPath.originX", leftForm.originX, rightForm.originX)
bits("$formPath.originY", leftForm.originY, rightForm.originY)
bits("$formPath.angle", leftForm.angle, rightForm.angle)
bits("$formPath.scale", leftForm.scale, rightForm.scale)
}
blendShapes(path, left.blendShapes, right.blendShapes) { formPath, leftForm: RotationForm, rightForm -> rotationForm(formPath, leftForm, rightForm) }
}
else -> differences += "$path: expected a ${left::class.simpleName}, got a ${right::class.simpleName}"
}
channels(path, left.channelGrids, right.channelGrids)
}
each("drawables", expected.drawables, actual.drawables) { path, left, right ->
same("$path.id", left.id, right.id)
same("$path.name", left.name, right.name)
same("$path.parentDeformerId", left.parentDeformerId, right.parentDeformerId)
same("$path.blendMode", left.blendMode, right.blendMode)
same("$path.maskedBy", left.maskedBy, right.maskedBy)
same("$path.invertMask", left.invertMask, right.invertMask)
bits("$path.drawOrder", left.drawOrder, right.drawOrder)
bits("$path.opacity", left.opacity, right.opacity)
color("$path.multiplyColor", left.multiplyColor, right.multiplyColor)
color("$path.screenColor", left.screenColor, right.screenColor)
same("$path.alphaBlendMode", left.alphaBlendMode, right.alphaBlendMode)
same("$path.culling", left.culling, right.culling)
same("$path.isVisible", left.isVisible, right.isVisible)
same("$path.isSelectable", left.isSelectable, right.isSelectable)
same("$path.textureSourceId", left.textureSourceId, right.textureSourceId)
same("$path.texturePage", left.texturePage, right.texturePage)
same("$path.atlasTileId", left.atlasTileId, right.atlasTileId)
mesh("$path.mesh", left.mesh, right.mesh)
grid("$path.geometry", left.geometryGrid, right.geometryGrid) { formPath, leftForm, rightForm -> floats("$formPath.positionDeltas", leftForm.positionDeltas, rightForm.positionDeltas) }
channels(path, left.channelGrids, right.channelGrids)
blendShapes(path, left.blendShapes, right.blendShapes) { formPath, leftForm: MeshForm, rightForm -> meshForm(formPath, leftForm, rightForm) }
}
each("glues", expected.glues, actual.glues) { path, left, right ->
same("$path.meshA", left.meshA, right.meshA)
same("$path.meshB", left.meshB, right.meshB)
same("$path.id", left.id, right.id)
bits("$path.intensity", left.intensity, right.intensity)
each("$path.pairs", left.pairs, right.pairs) { pairPath, leftPair, rightPair ->
same("$pairPath.indexA", leftPair.indexA, rightPair.indexA)
same("$pairPath.indexB", leftPair.indexB, rightPair.indexB)
bits("$pairPath.weightA", leftPair.weightA, rightPair.weightA)
bits("$pairPath.weightB", leftPair.weightB, rightPair.weightB)
}
channels(path, left.channelGrids, right.channelGrids)
}
renderNode("renderRoot", expected.renderRoot, actual.renderRoot)
}
return collector.differences
}
/**
* Every difference between two models' atlases: page sizes, the page addressing and composition, and every tile
* with its placement compared by bits, its binding, pin, and lineage.
*
* @param PuppetModel expected The model before the round trip.
* @param PuppetModel actual The model after it.
* @return List<String> One line per difference; empty when the atlases are identical.
*/
internal fun atlasDifferences(expected: PuppetModel, actual: PuppetModel): List<String> {
val collector = DifferenceCollector()
with(collector) {
val left = expected.atlas
val right = actual.atlas
same("atlas.pages", left.pages, right.pages)
same("atlas.storedUvsAddressPages", left.storedUvsAddressPages, right.storedUvsAddressPages)
same("atlas.composition", left.composition, right.composition)
each("atlas.tiles", left.tiles, right.tiles) { path, leftTile, rightTile ->
same("$path.id", leftTile.id, rightTile.id)
same("$path.name", leftTile.name, rightTile.name)
same("$path.width", leftTile.width, rightTile.width)
same("$path.height", leftTile.height, rightTile.height)
same("$path.source", leftTile.source, rightTile.source)
same("$path.pinned", leftTile.pinned, rightTile.pinned)
same("$path.replaces", leftTile.replaces, rightTile.replaces)
val leftPlacement = leftTile.placement
val rightPlacement = rightTile.placement
if (leftPlacement == null || rightPlacement == null) {
same("$path.placement present", leftPlacement != null, rightPlacement != null)
} else {
same("$path.placement.pageIndex", leftPlacement.pageIndex, rightPlacement.pageIndex)
bits("$path.placement.positionX", leftPlacement.positionX, rightPlacement.positionX)
bits("$path.placement.positionY", leftPlacement.positionY, rightPlacement.positionY)
bits("$path.placement.scaleX", leftPlacement.scaleX, rightPlacement.scaleX)
bits("$path.placement.scaleY", leftPlacement.scaleY, rightPlacement.scaleY)
bits("$path.placement.rotationDegrees", leftPlacement.rotationDegrees, rightPlacement.rotationDegrees)
}
}
}
return collector.differences
}
/**
* Every difference between two models' linked source art: each source's record and every inventory row with every
* flag and hash.
*
* @param PuppetModel expected The model before the round trip.
* @param PuppetModel actual The model after it.
* @return List<String> One line per difference; empty when the sources are identical.
*/
internal fun sourcesDifferences(expected: PuppetModel, actual: PuppetModel): List<String> {
val collector = DifferenceCollector()
with(collector) {
each("sources", expected.sources, actual.sources) { path, left, right ->
same("$path.id", left.id, right.id)
same("$path.name", left.name, right.name)
same("$path.path", left.path, right.path)
same("$path.format", left.format, right.format)
same("$path.contentHash", left.contentHash, right.contentHash)
same("$path.lastModified", left.lastModified, right.lastModified)
same("$path.offsetX", left.offsetX, right.offsetX)
same("$path.offsetZ", left.offsetZ, right.offsetZ)
each("$path.layers", left.layers, right.layers) { layerPath, leftLayer, rightLayer -> same(layerPath, leftLayer, rightLayer) }
}
}
return collector.differences
}
/**
* Every difference between two models across everything a UMA document carries: the puppet entry's structure and
* geometry, the atlas, and the linked source art.
*
* @param PuppetModel expected The model before the round trip.
* @param PuppetModel actual The model after it.
* @return List<String> One line per difference; empty when the documents are identical.
*/
internal fun documentDifferences(expected: PuppetModel, actual: PuppetModel): List<String> =
puppetStructureDifferences(expected, actual) + atlasDifferences(expected, actual) + sourcesDifferences(expected, actual)
/**
* Compares two drawable blend forms.
*
* @param String path Where the forms sit.
* @param MeshForm expected The expected form.
* @param MeshForm actual The actual form.
*/
private fun DifferenceCollector.meshForm(path: String, expected: MeshForm, actual: MeshForm) {
floats("$path.positionDeltas", expected.positionDeltas, actual.positionDeltas)
bits("$path.drawOrder", expected.drawOrder, actual.drawOrder)
bits("$path.opacity", expected.opacity, actual.opacity)
color("$path.multiplyColor", expected.multiplyColor, actual.multiplyColor)
color("$path.screenColor", expected.screenColor, actual.screenColor)
}
/**
* Compares two warp blend forms.
*
* @param String path Where the forms sit.
* @param WarpForm expected The expected form.
* @param WarpForm actual The actual form.
*/
private fun DifferenceCollector.warpForm(path: String, expected: WarpForm, actual: WarpForm) {
floats("$path.controlPoints", expected.controlPoints, actual.controlPoints)
bits("$path.opacity", expected.opacity, actual.opacity)
color("$path.multiplyColor", expected.multiplyColor, actual.multiplyColor)
color("$path.screenColor", expected.screenColor, actual.screenColor)
}
/**
* Compares two rotation blend forms.
*
* @param String path Where the forms sit.
* @param RotationForm expected The expected form.
* @param RotationForm actual The actual form.
*/
private fun DifferenceCollector.rotationForm(path: String, expected: RotationForm, actual: RotationForm) {
bits("$path.originX", expected.originX, actual.originX)
bits("$path.originY", expected.originY, actual.originY)
bits("$path.angle", expected.angle, actual.angle)
bits("$path.scale", expected.scale, actual.scale)
same("$path.flipX", expected.flipX, actual.flipX)
same("$path.flipY", expected.flipY, actual.flipY)
bits("$path.opacity", expected.opacity, actual.opacity)
color("$path.multiplyColor", expected.multiplyColor, actual.multiplyColor)
color("$path.screenColor", expected.screenColor, actual.screenColor)
}
/**
* Compares two part blend forms.
*
* @param String path Where the forms sit.
* @param PartForm expected The expected form.
* @param PartForm actual The actual form.
*/
private fun DifferenceCollector.partForm(path: String, expected: PartForm, actual: PartForm) {
bits("$path.drawOrder", expected.drawOrder, actual.drawOrder)
bits("$path.opacity", expected.opacity, actual.opacity)
color("$path.multiplyColor", expected.multiplyColor, actual.multiplyColor)
color("$path.screenColor", expected.screenColor, actual.screenColor)
}
@@ -0,0 +1,235 @@
package org.umamo.interop.uma
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.UmaWriteException
import org.umamo.format.uma.UmaWriterInfo
import org.umamo.format.uma.textures.UmaPixelSource
import org.umamo.format.uma.textures.UmaRenderPagePixels
import org.umamo.runtime.model.ArtSource
import org.umamo.runtime.model.ArtSourceId
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.AtlasComposition
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.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.PuppetAtlas
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.SourceLayerRef
import org.umamo.runtime.model.withDerivedRenderRoot
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Pins the whole-document bridge (docs/format/UMA.md §5, §6) on synthetic models: every atlas and source field
* survives a save exactly for every atlas shape, a reopened document samples the render pages it was saved with or
* derives them, and the comparer the corpus gate relies on sees a one-bit change.
*/
class UmaDocumentBridgeTest {
private val writer = UmaWriterInfo("Umamo", "test")
private val digest = "0123456789abcdef".repeat(4)
/**
* A PNG of one flat color.
*
* @param Int width The width.
* @param Int height The height.
* @param Int value The byte every channel takes.
* @return ByteArray The PNG.
*/
private fun png(width: Int, height: Int, value: Int): ByteArray = PngCodec.write(RasterImage(width, height, ByteArray(width * height * 4) { value.toByte() }))
/**
* A drawable bound to [tile], or to a page when [texturePage] is given.
*
* @param String id The drawable's id.
* @param String? tile The tile it samples.
* @param Int texturePage The page it samples, or -1.
* @return Drawable The drawable.
*/
private fun drawable(id: String, tile: String?, texturePage: Int = -1): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = null,
geometryGrid = null,
texturePage = texturePage,
atlasTileId = tile?.let(::AtlasTileId),
)
/**
* A model over [drawables] with [atlas] and [sources].
*
* @param List drawables The drawables.
* @param PuppetAtlas atlas The atlas.
* @param List sources The linked source art.
* @return PuppetModel The model.
*/
private fun modelOf(drawables: List<Drawable>, atlas: PuppetAtlas, sources: List<ArtSource> = emptyList()): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables,
rootChildren = drawables.map { item -> OrgChild.Drawable(item.id) },
rootPartId = null,
atlas = atlas,
sources = sources,
).withDerivedRenderRoot()
/**
* An atlas using every field: layer-addressed coordinates, a composition off the defaults, a placed and pinned
* tile with a stable binding and a placement whose floats a decimal round trip is most likely to bend, a
* reloaded tile with a weak binding and a lineage, and a bare tile.
*
* @return PuppetAtlas The atlas.
*/
private fun fullAtlas(): PuppetAtlas =
PuppetAtlas(
pages = listOf(AtlasPage(16, 16)),
tiles =
listOf(
AtlasTile(AtlasTileId("art-0/lyid:1"), "Eye", 4, 3, AtlasPlacement(0, 1.5f, -0.0f, -1f, Float.MIN_VALUE, 90.25f), SourceLayerRef(ArtSourceId("art-0"), "lyid:1", true), pinned = true),
AtlasTile(AtlasTileId("art-0/name:Mouth#2~1"), "Mouth", 2, 2, source = SourceLayerRef(ArtSourceId("art-0"), "name:Mouth#2", false), replaces = AtlasTileId("art-0/name:Mouth#2")),
AtlasTile(AtlasTileId("guid-3"), "Hair", 5, 1),
),
storedUvsAddressPages = false,
composition = AtlasComposition(alphaThreshold = 8, extrude = 0),
)
/**
* Sources using every field and flag.
*
* @return List<ArtSource> The sources.
*/
private fun fullSources(): List<ArtSource> =
listOf(
ArtSource(
id = ArtSourceId("art-0"),
name = "character.clip",
path = "C:/work/character.clip",
format = "clip",
layers =
listOf(
ArtSourceLayer("lyid:1", "Eye", "Head/Face", -12, 180, 4, 3, visible = false, present = false, contentHash = digest, empty = true, replaced = true, ignored = true),
ArtSourceLayer("name:Mouth#2", "Mouth", "", 0, 0, 2, 2, visible = true),
),
contentHash = digest,
lastModified = 1_757_894_400_123L,
offsetX = 64,
offsetZ = -32,
),
ArtSource(ArtSourceId("guid-7"), "Erica.psd", null, "psd"),
)
/** The PNG per tile of [fullAtlas], by id. */
private val tilePngs: Map<String, ByteArray> =
mapOf("art-0/lyid:1" to png(4, 3, 10), "art-0/name:Mouth#2~1" to png(2, 2, 20), "guid-3" to png(5, 1, 30))
/**
* [model] saved as a whole document and read back.
*
* @param PuppetModel model The model.
* @param UmaRenderPagePixels renderPages What its drawables sample.
* @return UmaModel The reopened document.
*/
private fun saved(model: PuppetModel, renderPages: UmaRenderPagePixels): UmaModel =
Uma.read(Uma.write(UmaDocumentBridge.documentOf(UmaModel.create(writer), model, UmaPixelSource({ id -> tilePngs[id] }, renderPages, null))))
/**
* Every atlas and source field survives a save exactly, and the render pages come back with each drawable's image.
*/
@Test
fun everyAtlasAndSourceFieldRoundTrips() {
val model = modelOf(listOf(drawable("D0", "art-0/lyid:1"), drawable("D1", "guid-3")), fullAtlas(), fullSources())
val reducedCopy = png(2, 2, 60)
val document = saved(model, UmaRenderPagePixels.Stored(listOf(reducedCopy, tilePngs.getValue("guid-3")), mapOf("D0" to 0, "D1" to 1)))
val reopened = UmaDocumentBridge.modelOf(document)
val differences = documentDifferences(model, reopened)
assertTrue(differences.isEmpty(), "differences: $differences")
assertEquals(model.atlas, reopened.atlas)
assertEquals(model.sources, reopened.sources)
val pages = UmaDocumentBridge.pagesOf(document)
val pageSet = assertNotNull(pages.pageSet, "stored render pages come back as a page set")
assertEquals(mapOf("D0" to 0, "D1" to 1), pageSet.atlasIndexByDrawableId)
assertContentEquals(reducedCopy, pageSet.pageBytes[0])
assertContentEquals(tilePngs.getValue("guid-3"), pageSet.pageBytes[1])
assertContentEquals(tilePngs.getValue("art-0/name:Mouth#2~1"), pages.tilePng(AtlasTileId("art-0/name:Mouth#2~1")), "an unbound tile's pixels are there")
}
/**
* A document whose pages derive stores no render pages, so the loader composes them.
*/
@Test
fun derivedPagesStoreNoPageSet() {
val model = modelOf(listOf(drawable("D0", "art-0/lyid:1")), fullAtlas().copy(storedUvsAddressPages = true))
val document = saved(model, UmaRenderPagePixels.Derived)
assertNull(UmaDocumentBridge.pagesOf(document).pageSet)
assertEquals(model.atlas, UmaDocumentBridge.modelOf(document).atlas)
}
/**
* Every atlas shape round-trips exactly: pages with no tiles (a CMO3 whose atlas holds no model image), and no
* pages or tiles at all beside stored render pages the drawables name by page number (a MOC3-origin rig).
*/
@Test
fun everyAtlasShapeRoundTrips() {
val pagesOnly = modelOf(emptyList(), PuppetAtlas(pages = listOf(AtlasPage(1024, 1024))))
assertEquals(pagesOnly.atlas, UmaDocumentBridge.modelOf(saved(pagesOnly, UmaRenderPagePixels.Derived)).atlas, "pages without tiles")
val tileless = modelOf(listOf(drawable("ArtMesh0", null, texturePage = 1), drawable("ArtMesh1", null, texturePage = 0)), PuppetAtlas.Empty)
val pagePngs = listOf(png(16, 16, 1), png(8, 8, 2))
val document = saved(tileless, UmaRenderPagePixels.Stored(pagePngs, mapOf("ArtMesh0" to 1, "ArtMesh1" to 0)))
val reopened = UmaDocumentBridge.modelOf(document)
assertEquals(PuppetAtlas.Empty, reopened.atlas, "the render pages do not enter an empty atlas")
assertEquals(listOf(1, 0), reopened.drawables.map { item -> item.texturePage })
val pageSet = assertNotNull(UmaDocumentBridge.pagesOf(document).pageSet)
assertContentEquals(pagePngs[1], pageSet.pageBytes[pageSet.atlasIndexByDrawableId.getValue("ArtMesh0")])
assertContentEquals(pagePngs[0], pageSet.pageBytes[pageSet.atlasIndexByDrawableId.getValue("ArtMesh1")])
}
/**
* The comparer sees a one-bit change in a placement, a flipped inventory flag, and a changed hash.
*/
@Test
fun comparerSeesSmallDifferences() {
val model = modelOf(listOf(drawable("D0", "art-0/lyid:1")), fullAtlas(), fullSources())
val placement = model.atlas.tiles[0].placement!!
val nudged = placement.copy(positionX = Float.fromBits(placement.positionX.toRawBits() + 1))
val movedTile = model.copy(atlas = model.atlas.copy(tiles = listOf(model.atlas.tiles[0].copy(placement = nudged)) + model.atlas.tiles.drop(1)))
assertEquals(1, atlasDifferences(model, movedTile).size, "a one-bit placement change")
val source = model.sources[0]
val flipped = model.copy(sources = listOf(source.copy(layers = listOf(source.layers[0].copy(ignored = false)) + source.layers.drop(1))) + model.sources.drop(1))
assertEquals(1, sourcesDifferences(model, flipped).size, "a flipped ignore mark")
val rehashed = model.copy(sources = listOf(source.copy(contentHash = digest.reversed())) + model.sources.drop(1))
assertEquals(1, sourcesDifferences(model, rehashed).size, "a changed file hash")
}
/**
* A save refuses a placement JSON cannot hold, naming where.
*/
@Test
fun unwritableAtlasesAreRefused() {
val atlas = fullAtlas()
val nanTile = atlas.tiles[0].copy(placement = atlas.tiles[0].placement!!.copy(rotationDegrees = Float.NaN))
val failure = assertFailsWith<UmaWriteException> { UmaTexturesBridge.texturesOf(modelOf(emptyList(), atlas.copy(tiles = listOf(nanTile)))) }
assertTrue(failure.path.contains("tiles[art-0/lyid:1].placement.rotationDegrees"), "the failure names ${failure.path}")
}
}
@@ -0,0 +1,261 @@
package org.umamo.interop.uma
import org.umamo.format.uma.Uma
import org.umamo.format.uma.UmaModel
import org.umamo.format.uma.UmaWriteException
import org.umamo.format.uma.UmaWriterInfo
import org.umamo.format.uma.puppet.UmaDeformer
import org.umamo.format.uma.puppet.UmaDeformerKind
import org.umamo.format.uma.puppet.UmaDrawable
import org.umamo.format.uma.puppet.UmaParameter
import org.umamo.format.uma.puppet.UmaPart
import org.umamo.format.uma.puppet.UmaPuppet
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.ParameterLink
import org.umamo.runtime.model.ParameterNode
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RenderGroup
import org.umamo.runtime.model.RuntimeTarget
import org.umamo.runtime.model.deriveRenderRoot
import org.umamo.runtime.model.withDerivedRenderRoot
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertTrue
/**
* Pins the puppet entry's bridge in both directions (docs/format/UMA.md §4) on synthetic models: every
* structure field away from its default and every enum value survives a save exactly, and defaults stay out of
* the file. The shapes the flat schema cannot enforce are the format layer's (UmaPuppetShapeTest).
*/
class UmaPuppetBridgeTest {
private val writer = UmaWriterInfo("Umamo", "test")
/**
* [model] saved as UMA and read back.
*
* @param PuppetModel model The model.
* @return PuppetModel The model the file describes.
*/
private fun roundTrip(model: PuppetModel): PuppetModel {
val bytes = Uma.write(UmaModel.create(writer).withPuppet(UmaPuppetExport.puppetOf(model)))
return UmaPuppetImport.modelOf(Uma.read(bytes).puppet!!)
}
/**
* A model with every structure field away from its default, every enum value used somewhere, and the
* floats a decimal round trip is most likely to bend.
*
* @param RuntimeTarget runtimeTarget The document's target.
* @return PuppetModel The model.
*/
private fun fullModel(runtimeTarget: RuntimeTarget): PuppetModel {
val drawables =
BlendMode.entries.mapIndexed { modeIndex, mode ->
val alphaMode = AlphaBlendMode.entries[modeIndex % AlphaBlendMode.entries.size]
if (modeIndex == 0) {
Drawable(
id = DrawableId("D0"),
name = "Eye L",
parentDeformerId = DeformerId("R1"),
blendMode = mode,
maskedBy = listOf(DrawableId("D1")),
mesh = null,
geometryGrid = null,
drawOrder = 499.5f,
opacity = -0.0f,
multiplyColor = ColorRgb(0.5f, -0.0f, Float.MIN_VALUE),
screenColor = ColorRgb(0.1f, 0.2f, 0.3f),
invertMask = true,
alphaBlendMode = alphaMode,
culling = true,
isVisible = false,
isSelectable = false,
textureSourceId = DrawableId("D1"),
texturePage = 2,
atlasTileId = AtlasTileId("art-0/lyid:12~1"),
)
} else {
Drawable(DrawableId("D$modeIndex"), "Drawable $modeIndex", null, mode, emptyList(), null, null, alphaBlendMode = alphaMode)
}
}
return PuppetModel(
parameters =
listOf(
Parameter(ParameterId("P0"), "Angle", -0.0f, 30f, Float.MIN_VALUE),
Parameter(ParameterId("P1"), "Morph", -1f, 1f, 1.4e-44f, ParameterKind.BLEND_SHAPE, repeat = true),
),
parts =
listOf(
Part(
id = PartId("Head"),
name = "Head",
children = listOf(OrgChild.Drawable(DrawableId("D1")), OrgChild.Part(PartId("Arm"))),
isVisible = false,
isSketch = true,
isSelectable = false,
groupMode = PartGroupMode.Grouped,
drawOrder = 700,
composite =
PartComposite(
blendMode = BlendMode.Multiply,
alphaBlendMode = AlphaBlendMode.Disjoint,
maskedBy = listOf(DrawableId("D0")),
maskedByParts = listOf(PartId("Body")),
invertMask = true,
opacity = 0.25f,
multiplyColor = ColorRgb(0.5f, 0.25f, 1f),
screenColor = ColorRgb(0.125f, 0f, 0f),
),
),
Part(PartId("Body"), "Body", listOf(OrgChild.Drawable(DrawableId("D2"))), groupMode = PartGroupMode.Isolated),
Part(PartId("Arm"), "Arm", emptyList()),
),
deformers =
listOf(
Deformer.Warp(
id = DeformerId("W1"),
name = "Warp",
parent = null,
partId = PartId("Head"),
rows = 3,
columns = 4,
isQuadTransform = false,
geometryGrid = null,
opacity = 0.5f,
multiplyColor = ColorRgb(0.9f, 0.8f, 0.7f),
screenColor = ColorRgb(0.01f, 0.02f, 0.03f),
isSelectable = false,
isVisible = false,
isEnabled = false,
),
Deformer.Rotation(
id = DeformerId("R1"),
name = "Rotation",
parent = DeformerId("W1"),
partId = PartId("Body"),
baseAngle = -0.0f,
geometryGrid = null,
flipX = true,
flipY = true,
),
),
drawables = drawables,
rootChildren = listOf(OrgChild.Part(PartId("Head")), OrgChild.Part(PartId("Body")), OrgChild.Drawable(DrawableId("D0"))),
rootPartId = PartId("__RootPart__"),
parameterLinks = listOf(ParameterLink(ParameterId("P0"), ParameterId("P1"))),
parameterTree =
listOf(
ParameterNode.Group(
ParameterGroupId("G1"),
"Face",
initiallyOpen = true,
children = listOf(ParameterNode.Param(ParameterId("P0")), ParameterNode.Group(ParameterGroupId("G2"), "", false, listOf(ParameterNode.Param(ParameterId("P1"))))),
),
),
canvasWidth = 2400f,
canvasHeight = 3000f,
worldOriginX = 1200f,
worldOriginZ = -0.0f,
pixelsPerUnit = 1f,
runtimeTarget = runtimeTarget,
rendersFromSourceLayers = true,
).withDerivedRenderRoot()
}
/**
* Every structure field survives a save exactly, under every runtime target.
*/
@Test
fun everyStructureFieldRoundTripsExactly() {
for (target in RuntimeTarget.entries) {
val model = fullModel(target)
val differences = puppetStructureDifferences(model, roundTrip(model))
assertTrue(differences.isEmpty(), "$target: ${differences.take(20)}")
}
}
/**
* The comparer the round trips rest on does see a single flipped bit, a renamed object, and a reordered
* list, so an empty result means something.
*/
@Test
fun comparerSeesSmallDifferences() {
val model = fullModel(RuntimeTarget.NoTarget)
val signFlip = model.copy(drawables = model.drawables.map { drawable -> if (drawable.id == DrawableId("D0")) drawable.copy(opacity = 0.0f) else drawable })
assertEquals(listOf("drawables[0].opacity"), puppetStructureDifferences(model, signFlip).map { difference -> difference.substringBefore(':') }, "-0.0 against 0.0")
val renamed = model.copy(parts = model.parts.map { part -> if (part.id == PartId("Arm")) part.copy(name = "Arm L") else part })
assertEquals(listOf("parts[2].name"), puppetStructureDifferences(model, renamed).map { difference -> difference.substringBefore(':') }, "a rename")
assertTrue(puppetStructureDifferences(model, model.copy(parameters = model.parameters.reversed())).isNotEmpty(), "a reorder")
}
/**
* The render root is never read from the file; the model always carries the organizational tree's own
* derivation.
*/
@Test
fun renderRootIsDerived() {
val reopened = roundTrip(fullModel(RuntimeTarget.NoTarget))
assertEquals(reopened.deriveRenderRoot(), reopened.renderRoot, "the render root is the derivation")
assertTrue(reopened.renderRoot.children.any { node -> node is RenderGroup && node.partId == PartId("Head") }, "and a grouped part forms its group")
}
/**
* A model at every default writes only what the schema requires.
*/
@Test
fun defaultsStayOutOfTheFile() {
val model =
PuppetModel(
parameters = listOf(Parameter(ParameterId("P"), "P", 0f, 1f, 0f)),
parts = listOf(Part(PartId("Part"), "Part", emptyList())),
deformers =
listOf(
Deformer.Warp(DeformerId("W"), "W", null, null, 2, 2, true, null),
Deformer.Rotation(DeformerId("R"), "R", null, null, 0f, null),
),
drawables = listOf(Drawable(DrawableId("D"), "D", null, BlendMode.Normal, emptyList(), null, null)),
rootChildren = emptyList(),
rootPartId = null,
).withDerivedRenderRoot()
val expected =
UmaPuppet(
parameters = listOf(UmaParameter("P", "P", 0f, 1f, 0f)),
parts = listOf(UmaPart("Part", "Part")),
deformers =
listOf(
UmaDeformer("W", UmaDeformerKind.Warp, "W", rows = 2, columns = 2, isQuadTransform = true),
UmaDeformer("R", UmaDeformerKind.Rotation, "R", baseAngle = 0f),
),
drawables = listOf(UmaDrawable("D", "D")),
)
assertEquals(expected, UmaPuppetExport.puppetOf(model))
assertTrue(puppetStructureDifferences(model, roundTrip(model)).isEmpty(), "and restores every default on read")
}
/**
* A non-finite value refuses the save and names where it sits.
*/
@Test
fun nonFiniteValueRefusesTheSaveByPath() {
val model = fullModel(RuntimeTarget.NoTarget).let { base -> base.copy(drawables = base.drawables.map { drawable -> if (drawable.id == DrawableId("D3")) drawable.copy(opacity = Float.NaN) else drawable }) }
val failure = assertFailsWith<UmaWriteException> { UmaPuppetExport.puppetOf(model) }
assertTrue(failure.message.orEmpty().contains("drawables[D3].opacity"), "the failure names the value: ${failure.message}")
}
}
@@ -0,0 +1,224 @@
package org.umamo.interop.uma
import org.umamo.format.uma.Uma
import org.umamo.format.uma.UmaModel
import org.umamo.format.uma.UmaWriteException
import org.umamo.format.uma.UmaWriterInfo
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.BlendShapeBinding
import org.umamo.runtime.model.BlendWeightLimit
import org.umamo.runtime.model.BlendWeightLimitPoint
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.Deformer
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.GluePair
import org.umamo.runtime.model.KeyformAxis
import org.umamo.runtime.model.KeyformCell
import org.umamo.runtime.model.KeyformGrid
import org.umamo.runtime.model.MeshDeltaForm
import org.umamo.runtime.model.MeshForm
import org.umamo.runtime.model.OrgChild
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PartForm
import org.umamo.runtime.model.PartGroupMode
import org.umamo.runtime.model.PartId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.RotationForm
import org.umamo.runtime.model.RotationPivotForm
import org.umamo.runtime.model.WarpForm
import org.umamo.runtime.model.WarpLatticeForm
import org.umamo.runtime.model.withDerivedRenderRoot
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertTrue
/**
* Pins the puppet entry's geometry half in both directions (docs/format/UMA.md §4.9-§4.14) on synthetic
* models: meshes, every grid kind (a sparse one included), every channel, every blend form, and glue survive a
* save bit for bit, and the buffer carries even a NaN payload while inline JSON refuses one. The geometry
* invariants the renderer relies on are the format layer's (UmaPuppetShapeTest).
*/
class UmaPuppetGeometryBridgeTest {
private val writer = UmaWriterInfo("Umamo", "test")
/**
* [model] saved as UMA and read back.
*
* @param PuppetModel model The model.
* @return PuppetModel The model the file describes.
*/
private fun roundTrip(model: PuppetModel): PuppetModel {
val bytes = Uma.write(UmaModel.create(writer).withPuppet(UmaPuppetExport.puppetOf(model)))
return UmaPuppetImport.modelOf(Uma.read(bytes).puppet!!)
}
/**
* Eight distinct floats for a quad's four vertices, starting at [start].
*
* @param Float start The first value.
* @return FloatArray The values.
*/
private fun quadFloats(start: Float): FloatArray = FloatArray(8) { valueIndex -> start + valueIndex * 0.125f }
/**
* A one-axis channel track over P0 with one value per key.
*
* @param List<ChannelValue> values The three values.
* @return KeyformGrid The track.
*/
private fun track(values: List<ChannelValue>): KeyformGrid<ChannelValue> =
KeyformGrid(listOf(KeyformAxis(ParameterId("P0"), floatArrayOf(-30f, 0f, 30f))), values.mapIndexed { keyIndex, value -> KeyformCell(intArrayOf(keyIndex), value) })
/**
* A model exercising every geometry field.
*
* @return PuppetModel The model.
*/
private fun geometryModel(): PuppetModel {
val axes = listOf(KeyformAxis(ParameterId("P0"), floatArrayOf(-30f, 0f, 30f)), KeyformAxis(ParameterId("P1"), floatArrayOf(-0.0f, 1f)))
val denseCells = (0 until 2).flatMap { secondKey -> (0 until 3).map { firstKey -> KeyformCell(intArrayOf(firstKey, secondKey), MeshDeltaForm(quadFloats(firstKey + secondKey * 3f))) } }
val quad = DrawableMesh(floatArrayOf(0f, 0f, 10f, 0f, 10f, 10f, 0f, 10f), floatArrayOf(0f, 0f, 1f, 0f, 1f, 1f, 0f, 1f), intArrayOf(0, 1, 2, 0, 2, 3))
val colorTracks =
ChannelGrids(
linkedMapOf(
FormChannel.DRAW_ORDER to track(listOf(ChannelValue.Scalar(490f), ChannelValue.Scalar(-0.0f), ChannelValue.Scalar(510.5f))),
FormChannel.OPACITY to track(listOf(ChannelValue.Scalar(0f), ChannelValue.Scalar(0.5f), ChannelValue.Scalar(1f))),
FormChannel.MULTIPLY_COLOR to track(listOf(ChannelValue.Color(ColorRgb(1f, 0.5f, 0.25f)), ChannelValue.Color(ColorRgb.MultiplyIdentity), ChannelValue.Color(ColorRgb(0f, 0f, Float.MIN_VALUE)))),
FormChannel.SCREEN_COLOR to track(listOf(ChannelValue.Color(ColorRgb(0.1f, 0.2f, 0.3f)), ChannelValue.Color(ColorRgb.ScreenIdentity), ChannelValue.Color(ColorRgb.ScreenIdentity))),
),
)
val limits = listOf(BlendWeightLimit(ParameterId("P0"), listOf(BlendWeightLimitPoint(-30f, 0f), BlendWeightLimitPoint(30f, 1f))))
return PuppetModel(
parameters = listOf(Parameter(ParameterId("P0"), "Angle", -30f, 30f, 0f), Parameter(ParameterId("P1"), "Morph", 0f, 1f, 0f)),
parts =
listOf(
Part(
id = PartId("Head"),
name = "Head",
children = listOf(OrgChild.Drawable(DrawableId("D0")), OrgChild.Drawable(DrawableId("D1"))),
groupMode = PartGroupMode.Isolated,
channelGrids = ChannelGrids(linkedMapOf(FormChannel.DRAW_ORDER to track(listOf(ChannelValue.Scalar(400f), ChannelValue.Scalar(500f), ChannelValue.Scalar(600f))))),
blendShapes = listOf(BlendShapeBinding(ParameterId("P1"), floatArrayOf(0f, 1f), 0, listOf(null, PartForm(600f, 0.75f, ColorRgb(0.5f, 0.5f, 0.5f))), limits)),
),
),
deformers =
listOf(
Deformer.Warp(
id = DeformerId("W1"),
name = "Warp",
parent = null,
partId = PartId("Head"),
rows = 1,
columns = 1,
isQuadTransform = true,
geometryGrid = KeyformGrid(axes.take(1), (0 until 3).map { keyIndex -> KeyformCell(intArrayOf(keyIndex), WarpLatticeForm(quadFloats(keyIndex * 10f))) }),
channelGrids = ChannelGrids(linkedMapOf(FormChannel.OPACITY to track(listOf(ChannelValue.Scalar(1f), ChannelValue.Scalar(0.25f), ChannelValue.Scalar(1f))))),
blendShapes = listOf(BlendShapeBinding(ParameterId("P1"), floatArrayOf(0f, 1f), 0, listOf(null, WarpForm(quadFloats(-5f), 0.5f)))),
),
Deformer.Rotation(
id = DeformerId("R1"),
name = "Rotation",
parent = DeformerId("W1"),
partId = PartId("Head"),
baseAngle = 15f,
geometryGrid = KeyformGrid(axes.take(1), (0 until 3).map { keyIndex -> KeyformCell(intArrayOf(keyIndex), RotationPivotForm(0.5f, -0.0f, keyIndex * 15f, 1f + keyIndex)) }),
channelGrids =
ChannelGrids(
linkedMapOf(
FormChannel.FLIP_X to track(listOf(ChannelValue.Flag(false), ChannelValue.Flag(true), ChannelValue.Flag(false))),
FormChannel.FLIP_Y to track(listOf(ChannelValue.Flag(true), ChannelValue.Flag(true), ChannelValue.Flag(false))),
),
),
blendShapes = listOf(BlendShapeBinding(ParameterId("P1"), floatArrayOf(0f, 1f), 0, listOf(null, RotationForm(1f, 2f, 45f, 0.5f, flipX = true, flipY = false, opacity = 0.5f)), limits)),
),
),
drawables =
listOf(
Drawable(
id = DrawableId("D0"),
name = "Eye",
parentDeformerId = DeformerId("R1"),
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = quad,
geometryGrid = KeyformGrid(axes, denseCells),
channelGrids = colorTracks,
blendShapes = listOf(BlendShapeBinding(ParameterId("P1"), floatArrayOf(0f, 1f), 0, listOf(null, MeshForm(quadFloats(9f), 510f, 0.5f, ColorRgb(0.9f, 0.9f, 0.9f), ColorRgb(0.1f, 0f, 0f))), limits)),
),
Drawable(
id = DrawableId("D1"),
name = "Brow",
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(quad.positions.copyOf(), quad.uvs.copyOf(), quad.indices.copyOf()),
// A sparse grid: one of the six cells is missing, and the others keep their order.
geometryGrid = KeyformGrid(axes, denseCells.filterIndexed { cellIndex, _ -> cellIndex != 4 }.reversed()),
),
),
rootChildren = listOf(OrgChild.Part(PartId("Head"))),
rootPartId = null,
glues =
listOf(
Glue(
meshA = DrawableId("D0"),
meshB = DrawableId("D1"),
pairs = listOf(GluePair(0, 3, 0.5f, 0.25f), GluePair(1, 2, 1f, -0.0f)),
channelGrids = ChannelGrids(linkedMapOf(FormChannel.GLUE_INTENSITY to track(listOf(ChannelValue.Scalar(0f), ChannelValue.Scalar(1f), ChannelValue.Scalar(0.5f))))),
intensity = 0.75f,
id = "Glue__D0__D1",
),
),
).withDerivedRenderRoot()
}
/**
* Every geometry field survives a save bit for bit.
*/
@Test
fun everyGeometryFieldRoundTripsExactly() {
val model = geometryModel()
val differences = puppetStructureDifferences(model, roundTrip(model))
assertTrue(differences.isEmpty(), differences.take(20).toString())
}
/**
* The comparer does see a single flipped bit deep inside a delta buffer.
*/
@Test
fun comparerSeesADeltaBit() {
val model = geometryModel()
val drawable = model.drawables.first()
val grid = drawable.geometryGrid!!
val flipped = grid.cells.first().form.positionDeltas.copyOf().also { deltas -> deltas[5] = Float.fromBits(deltas[5].toRawBits() xor 1) }
val changedGrid = KeyformGrid(grid.axes, listOf(KeyformCell(grid.cells.first().coordinate, MeshDeltaForm(flipped))) + grid.cells.drop(1))
val changed = model.copy(drawables = listOf(drawable.copy(geometryGrid = changedGrid)) + model.drawables.drop(1))
assertEquals(listOf("drawables[0].geometry.cells[0].positionDeltas[5]"), puppetStructureDifferences(model, changed).map { difference -> difference.substringBefore(':') })
}
/**
* A buffer carries any float bit for bit, a NaN payload included; the same value inline refuses the save.
*/
@Test
fun bufferCarriesNaNWhileInlineRefuses() {
val base = geometryModel()
val payloadNaN = Float.fromBits(0x7FC00001)
val withNaN = base.copy(drawables = base.drawables.map { drawable -> if (drawable.id == DrawableId("D1")) drawable.copy(mesh = DrawableMesh(floatArrayOf(payloadNaN, 0f, 10f, 0f, 10f, 10f, 0f, 10f), drawable.mesh!!.uvs, drawable.mesh!!.indices)) else drawable })
val reopened = roundTrip(withNaN)
assertEquals(payloadNaN.toRawBits(), reopened.drawables.first { drawable -> drawable.id == DrawableId("D1") }.mesh!!.positions[0].toRawBits(), "the payload survives")
val inlineNaN = base.copy(parameters = base.parameters, parts = base.parts, deformers = base.deformers.map { deformer -> if (deformer is Deformer.Rotation) deformer.copy(geometryGrid = KeyformGrid(deformer.geometryGrid!!.axes, listOf(KeyformCell(intArrayOf(0), RotationPivotForm(Float.NaN, 0f, 0f, 1f))))) else deformer })
val failure = assertFailsWith<UmaWriteException> { UmaPuppetExport.puppetOf(inlineNaN) }
assertTrue(failure.message.orEmpty().contains("deformers[R1].geometry.cells[0].originX"), "the failure names the value: ${failure.message}")
}
}
@@ -0,0 +1,237 @@
package org.umamo.interop.cmo3
import org.umamo.format.atlas.AtlasPackItem
import org.umamo.format.atlas.AtlasPackOptions
import org.umamo.format.atlas.AtlasPackReserve
import org.umamo.format.atlas.AtlasPackSkipReason
import org.umamo.format.atlas.packAtlas
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.DrawableMesh
import org.umamo.runtime.model.PuppetModel
/**
* Un-deduplicates baked atlas twins before fresh-graph synthesis.
*
* A .moc3 bake may pack mirrored duplicates as ONE atlas slot sampled by drawables at different
* canvas placements. The CMO3 model-image web cannot express that shape: a CModelImage carries a
* single canvas placement, so a shared material loses every twin but the first in the editor's
* source-image mode, while duplicated materials over one slot make the editor's atlas recomposite
* stack the shared art's alpha. Official documents never contain the shape either - every corpus
* multi-drawable material is co-located (Erica: 45 of 45 groups share mesh AND placement), and
* real mirror pairs are separate source layers in separate slots. This prepass restores that
* structure: each ADDITIONAL placement of a shared slot gets the patch pixels copied onto a
* synthesized extra page, packed by the shared atlas packer, and its drawables' uvs remapped
* there, so every slot downstream carries a single canvas placement and the image chain builds one
* correctly-placed material per twin.
*/
internal object Cmo3AtlasUndedup {
/** Transparent spacing between packed patches (and the page border): the packer's gutter. */
private const val PACK_GUTTER = 2
/** The un-deduplicated inputs for the fresh-graph pipeline. */
internal class Result(
val puppet: PuppetModel,
val pages: List<Cmo3Conversion.AtlasPage>,
val pageIndexByDrawableId: Map<String, Int>,
/** The drawables whose uvs were remapped onto a synthesized page, for tests and reports. */
val duplicatedDrawableIds: List<String>,
/**
* The drawables of a further placement whose patch is too large for a page even on its own,
* left sharing the source slot with their uvs untouched, for the export notice. A further
* placement with no opaque pixel (a hit area's twin) shares silently and is listed nowhere:
* there is nothing to show at either placement, so the web's single placement costs nothing.
*/
val sharedDrawableIds: List<String> = emptyList(),
)
/** One atlas slot shared by several drawables: page + uv bbox + the mesh arrays. */
private class SlotKey(
val pageIndex: Int,
private val uvs: FloatArray,
private val indices: IntArray,
) {
override fun equals(other: Any?): Boolean =
other is SlotKey &&
pageIndex == other.pageIndex &&
uvs.contentEquals(other.uvs) &&
indices.contentEquals(other.indices)
override fun hashCode(): Int {
var result = pageIndex
result = 31 * result + uvs.contentHashCode()
result = 31 * result + indices.contentHashCode()
return result
}
}
/** One placement sub-group needing its own copy of a slot's patch. */
private class DuplicationJob(
val sourcePageIndex: Int,
val sourceRect: IntArray,
val drawableIds: List<String>,
)
/**
* Detects shared slots sampled from multiple canvas placements and gives every additional
* placement its own patch copy on a synthesized page.
*
* @param PuppetModel puppet The model to convert; canvas-frame rest meshes.
* @param List pages The atlas pages, in model3 texture order.
* @param Map pageIndexByDrawableId Each drawable id's atlas page index.
* @return Result The (possibly) remapped puppet, extended page list, and updated page map.
*/
fun undeduplicate(
puppet: PuppetModel,
pages: List<Cmo3Conversion.AtlasPage>,
pageIndexByDrawableId: Map<String, Int>,
): Result {
// Group drawables by slot, then by quantized placement within the slot.
val placementsBySlot = LinkedHashMap<SlotKey, LinkedHashMap<List<Long>, MutableList<String>>>()
val rectBySlot = HashMap<SlotKey, IntArray>()
for (drawable in puppet.drawables) {
val pageIndex = pageIndexByDrawableId[drawable.id.raw] ?: continue
val page = pages.getOrNull(pageIndex) ?: continue
val mesh = drawable.mesh ?: continue
val rect = Cmo3ImageChainBuilder.patchRectOf(mesh.uvs, page.width, page.height) ?: continue
val slotKey = SlotKey(pageIndex, mesh.uvs, mesh.indices)
rectBySlot[slotKey] = rect
val fit = fitAtlasPageToCanvasTransform(mesh.uvs, mesh.positions, page.width, page.height)
val placementKey =
listOf(
Math.round(fit.m00.toDouble() * 1024),
Math.round(fit.m01.toDouble() * 1024),
Math.round(fit.m10.toDouble() * 1024),
Math.round(fit.m11.toDouble() * 1024),
Math.round(fit.m02.toDouble()),
Math.round(fit.m12.toDouble()),
)
placementsBySlot
.getOrPut(slotKey) { LinkedHashMap() }
.getOrPut(placementKey) { ArrayList() }
.add(drawable.id.raw)
}
// The first placement of a slot keeps the original pixels; every further placement is a job.
val jobs = ArrayList<DuplicationJob>()
for ((slotKey, placements) in placementsBySlot) {
if (placements.size < 2) {
continue
}
for ((placementIndex, drawableIds) in placements.values.withIndex()) {
if (placementIndex == 0) {
continue
}
jobs.add(DuplicationJob(slotKey.pageIndex, rectBySlot.getValue(slotKey), drawableIds))
}
}
if (jobs.isEmpty()) {
return Result(puppet, pages, pageIndexByDrawableId, emptyList())
}
// Each job's patch is cut out of its source page and handed to the shared packer as a tile
// whose reserve is the whole patch: the mesh's uv box reaches into the transparent margin
// around the opaque art, and the reserve keeps that margin on the tile's own transparent space
// rather than on a neighbor's pixels. The key is the job's first drawable, stable and unique,
// so the pack is deterministic run to run.
val decodedPages = HashMap<Int, RasterImage>()
val jobByKey = LinkedHashMap<String, DuplicationJob>()
val items =
jobs.map { job ->
val sourcePage = decodedPages.getOrPut(job.sourcePageIndex) { PngCodec.read(pages[job.sourcePageIndex].pngBytes) }
val key = job.drawableIds.first()
jobByKey[key] = job
val width = job.sourceRect[2] - job.sourceRect[0]
val height = job.sourceRect[3] - job.sourceRect[1]
AtlasPackItem(key, width, height, cutPatch(sourcePage, job.sourceRect), reserve = AtlasPackReserve(0, 0, width, height))
}
// Extrusion stays off and the trim threshold at one: the image chain crops each layer PNG by
// its uv box, so an extruded band inside the reserved margin would put edge color where the
// bake had transparent pixels, and a lossless trim blitted into a transparent reserve
// reproduces the patch verbatim.
val pageCap = maxOf(1024, pages.maxOf { page -> maxOf(page.width, page.height) })
val packed =
packAtlas(
items,
AtlasPackOptions(
maxPageSize = pageCap,
gutter = PACK_GUTTER,
extrude = 0,
allowRotation = false,
powerOfTwoPages = true,
squarePages = true,
shrinkPages = true,
alphaThreshold = 1,
),
)
// Remap the duplicated drawables' uvs onto the synthesized pages.
val newPageIndexByDrawableId = HashMap(pageIndexByDrawableId)
val remapByDrawableId = HashMap<String, FloatArray>()
val duplicatedIds = ArrayList<String>()
for (placement in packed.placements) {
check(placement.quarterTurns == 0) { "the un-dedup packs without rotation" }
val job = jobByKey.getValue(placement.key)
val sourcePage = pages[job.sourcePageIndex]
val page = packed.pages[placement.pageIndex]
val pageIndex = pages.size + placement.pageIndex
// The packer placed the patch's opaque trim at (pageX, pageY), the trim sitting
// (trimLeft, trimTop) inside the patch: newPagePx = pageX + (oldPagePx - (sourceX + trimLeft)).
val deltaX = (placement.pageX - job.sourceRect[0] - placement.trimLeft).toFloat()
val deltaY = (placement.pageY - job.sourceRect[1] - placement.trimTop).toFloat()
for (drawableId in job.drawableIds) {
newPageIndexByDrawableId[drawableId] = pageIndex
remapByDrawableId[drawableId] =
floatArrayOf(deltaX, deltaY, sourcePage.width.toFloat(), sourcePage.height.toFloat(), page.width.toFloat(), page.height.toFloat())
duplicatedIds.add(drawableId)
}
}
// A patch the packer could not place keeps its drawables on the source slot. One with no
// opaque pixel shares silently, since nothing shows at either placement; one larger than a
// page even alone is the unrepresentable case the conversion reports.
val sharedIds =
packed.skipped
.filter { skip -> skip.reason == AtlasPackSkipReason.LargerThanPage }
.flatMap { skip -> jobByKey.getValue(skip.key).drawableIds }
val builtPages = pages + packed.pages.map { page -> Cmo3Conversion.AtlasPage(PngCodec.write(page), page.width, page.height) }
val remappedDrawables =
puppet.drawables.map { drawable ->
val remap = remapByDrawableId[drawable.id.raw] ?: return@map drawable
val mesh = drawable.mesh ?: return@map drawable
val newUvs = FloatArray(mesh.uvs.size)
var componentIndex = 0
while (componentIndex + 1 < mesh.uvs.size) {
newUvs[componentIndex] = (mesh.uvs[componentIndex] * remap[2] + remap[0]) / remap[4]
newUvs[componentIndex + 1] = (mesh.uvs[componentIndex + 1] * remap[3] + remap[1]) / remap[5]
componentIndex += 2
}
drawable.copy(mesh = DrawableMesh(mesh.positions, newUvs, mesh.indices))
}
return Result(
puppet.copy(drawables = remappedDrawables),
builtPages,
newPageIndexByDrawableId,
duplicatedIds,
sharedIds,
)
}
/**
* The pixels of one patch rect cut out of a decoded page, as their own straight-alpha raster.
*
* @param RasterImage page The decoded source page.
* @param IntArray rect The patch rect on the page, [x0, y0, x1, y1] with exclusive maxima.
* @return ByteArray The patch's RGBA pixels, row-major from its top row.
*/
private fun cutPatch(page: RasterImage, rect: IntArray): ByteArray {
val width = rect[2] - rect[0]
val height = rect[3] - rect[1]
val rgba = ByteArray(width * height * 4)
for (rowIndex in 0 until height) {
val sourceOffset = ((rect[1] + rowIndex) * page.width + rect[0]) * 4
page.rgba.copyInto(rgba, rowIndex * width * 4, sourceOffset, sourceOffset + width * 4)
}
return rgba
}
}
@@ -0,0 +1,92 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CModelImage
import org.umamo.format.cmo3.model.gen.CModelImageGroup
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.ModelImageEntry
import org.umamo.format.cmo3.model.type.CAffine
/*
* The retained graph's atlas web indexed by tile id (the model image guid), the one walk both the
* web reconcile and the per-tile placement lowering read. Two copies of the walk would have to
* agree on guid filtering and on capturing the FULL canvas affine, or the reconcile and the lowering
* that runs right after it could classify one tile differently inside a single export.
*/
/**
* One tracked entry: the element, the atlas that currently holds it, and that atlas's index.
*
* @property ModelImageEntry entry The packed entry.
* @property CTextureAtlas atlas The atlas element holding it.
* @property Int atlasIndex That atlas's index in the texture manager's list.
*/
internal class AtlasEntrySite(
val entry: ModelImageEntry,
val atlas: CTextureAtlas,
val atlasIndex: Int,
)
/**
* A texture manager's atlas web, keyed by tile id.
*
* @property Map siteByTileId Each tracked entry by the tile it packs.
* @property List strayEntryAtlasIndices The atlas index of every entry that cannot be tracked (no
* guid, or a guid already seen), one element per such entry.
* @property Map modelImageByTileId Each pooled model image by its guid.
* @property Map canvasAffineByTileId Each model image's canvas placement as a six-float affine.
*/
internal class Cmo3AtlasWebIndex(
val siteByTileId: Map<String, AtlasEntrySite>,
val strayEntryAtlasIndices: List<Int>,
val modelImageByTileId: Map<String, CModelImage>,
val canvasAffineByTileId: Map<String, FloatArray>,
)
/**
* Indexes [textureManager]'s atlas web.
*
* Built fresh by every pass that reads it rather than shared between them: the web reconcile moves
* entries between atlases, so an index taken before it is stale for the placement lowering that runs
* after.
*
* @param CTextureManager textureManager The retained graph's texture manager.
* @return Cmo3AtlasWebIndex The web as it stands now.
*/
internal fun indexAtlasWeb(textureManager: CTextureManager): Cmo3AtlasWebIndex {
// CMO3: CTextureManager field _textureAtlases -> CTextureAtlas field modelImages -> ModelImageEntry
// field modelImageGuid. Which atlas holds an entry IS the tile's page membership. A guid-less or
// guid-duplicated entry cannot be tracked against the model; it stays where it sits and only
// constrains page deletion. Indices are the RAW list positions, which is what the reconcile
// addresses the list by.
val siteByTileId = HashMap<String, AtlasEntrySite>()
val strayEntryAtlasIndices = ArrayList<Int>()
for ((atlasIndex, member) in Cmo3Import.elementsOf(textureManager._textureAtlases).withIndex()) {
val atlas = member as? CTextureAtlas ?: continue
for (entry in Cmo3Import.elementsOf(atlas.modelImages).filterIsInstance<ModelImageEntry>()) {
val uuid = Cmo3Import.uuidOf(entry.modelImageGuid)
if (uuid == null || siteByTileId.containsKey(uuid)) {
strayEntryAtlasIndices.add(atlasIndex)
} else {
siteByTileId[uuid] = AtlasEntrySite(entry, atlas, atlasIndex)
}
}
}
// CMO3: CTextureManager field _modelImageGroups -> CModelImageGroup field _modelImages -> CModelImage
// fields guid / _materialLocalToCanvasTransform - where the art sits on the CANVAS. A repack moves
// art on the page and never on the canvas, so this is the fixed point every rewritten transform
// pair has to keep composing to. The FULL affine, not just its translation: an official file's
// model images are pure translations, but a converted graph carries the original packing's linear
// part here, and the composition must reproduce it.
val modelImageByTileId = HashMap<String, CModelImage>()
val canvasAffineByTileId = HashMap<String, FloatArray>()
for (group in Cmo3Import.elementsOf(textureManager._modelImageGroups).filterIsInstance<CModelImageGroup>()) {
for (modelImage in Cmo3Import.elementsOf(group._modelImages).filterIsInstance<CModelImage>()) {
val uuid = Cmo3Import.uuidOf(modelImage.guid) ?: continue
modelImageByTileId[uuid] = modelImage
val canvas = modelImage._materialLocalToCanvasTransform as? CAffine ?: continue
canvasAffineByTileId[uuid] = canvas.toAffineArray()
}
}
return Cmo3AtlasWebIndex(siteByTileId, strayEntryAtlasIndices, modelImageByTileId, canvasAffineByTileId)
}
@@ -0,0 +1,539 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.Cmo3GraphEditor
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CModelImage
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureInputExtension
import org.umamo.format.cmo3.model.gen.CTextureInput_ModelImage
import org.umamo.format.cmo3.model.gen.CTextureInput_TextureAtlasRegion
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.gen.GTransform2
import org.umamo.format.cmo3.model.gen.ModelImageEntry
import org.umamo.format.cmo3.model.identity.Guid
import org.umamo.format.cmo3.model.type.CAffine
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.composeAffine
import org.umamo.runtime.model.inversePlacementAffine
import org.umamo.runtime.model.lineageRoot
import org.umamo.runtime.model.placementAffine
import java.util.IdentityHashMap
/**
* The full atlas-web reconcile: page set, entry membership, drawable texture
* references, and page images, brought to the EDITED model's packing as one all-or-nothing pass.
*
* The membership half is the load-bearing one: a ModelImageEntry physically lives inside its page's
* CTextureAtlas element, and the import reads a tile's page purely from which atlas holds its entry.
* Rewriting the entry's transforms without also moving the entry between atlases would leave a file
* whose placements point at one page while the membership still names another - a jumbled reimport,
* the failure mode this class exists to close.
*
* Everything here follows the model's page order: model page i is `_textureAtlases[i]`, so the page
* set reconciles positionally - retained atlases are reused in place (their page resources mutated,
* never replaced, because page-resource IDENTITY is what storedUvsAddressPages recovery reads),
* atlases past the retained count are minted with the fresh conversion's own builders, and retained
* atlases past the edited count are deleted after everything living has moved out of them.
*
* A pack-in - a bound tile that never had an entry gaining a placement - mints the entry and each
* bound drawable's region input, so a whole-model repack of a document with never-packed bound art
* (Erica carries three such drawables) exports consistently too.
*
* The art itself is the retained layer web's ([Cmo3RetainedLayerWeb]): a tile the graph has no
* model image for (a reload's added layer, an Add Artwork file) has its layer and model image minted
* before the pack-in mints its entry, and a reloaded tile has its lineage root's layer rewritten to
* the new pixels before the entry moves - so the layered image the official editor shows is the art
* the pages carry. A created drawable over any tile with a model image and a placement is handed a
* texture binding ([Result.mintedBindings]), which the structural pass binds it through.
*
* All or nothing: validation runs first and any gap declines the WHOLE reconcile - the honest
* notices then flow from the property lowering unchanged. Nothing here may half-write, because the
* reconcile has no rollback.
*/
internal class Cmo3AtlasWebLowering(
private val target: Cmo3Model,
private val modelSource: CModelSource,
private val baseline: PuppetModel,
private val edited: PuppetModel,
private val editor: Cmo3GraphEditor,
private val tileRasters: (AtlasTileId) -> RasterImage?,
private val nowMillis: Long,
// The document's texture frames, taken from the graph before the export changed it.
private val textureFrames: Cmo3TextureFrames,
) {
/**
* What the reconcile did.
*
* @property Boolean pagesRecomposed True when the full web reconcile ran; the stale-page notices
* key on it.
* @property Boolean pruneNeeded True when graph structure was dropped, so the export must run
* the shared-pool prune.
* @property Map mintedBindings A texture binding for every created drawable over a tile the
* web now holds, by drawable id; the structural pass binds
* such a drawable through it.
* @property Set reconciledTileIds The lineage roots whose layer web was minted or rewritten,
* so the tile lowering owes no metadata notice for them.
*/
class Result(
val pagesRecomposed: Boolean,
val pruneNeeded: Boolean,
val mintedBindings: Map<String, Cmo3DrawableTextureBinding> = emptyMap(),
val reconciledTileIds: Set<String> = emptySet(),
) {
companion object {
/** The no-op outcome: nothing touched, notices stay. */
val Declined: Result = Result(pagesRecomposed = false, pruneNeeded = false)
}
}
/** One drawable source whose region input must be rewritten for its tile's new placement. */
private class RetargetCandidate(
val source: CArtMeshSource,
val region: CTextureInput_TextureAtlasRegion,
val input: CAffine,
val tileId: String,
)
/** One drawable source over a packed-IN tile, which gains a fresh region input. */
private class PackInCandidate(
val source: CArtMeshSource,
val extension: CTextureInputExtension,
val tileId: String,
)
/**
* Reconciles the atlas web onto [recomposedPages], or declines whole.
*
* @param List recomposedPages The pages composed for the edited model's packing, in its page order.
* @return Result Whether the reconcile ran, and whether it dropped structure.
*/
fun reconcile(recomposedPages: List<Cmo3Conversion.AtlasPage>): Result {
if (recomposedPages.isEmpty()) {
return Result.Declined
}
// CMO3: CModelSource field textureManager -> CTextureManager field _textureAtlases.
val textureManager = modelSource.textureManager as? CTextureManager ?: return Result.Declined
val atlasList = mutableGraphListOf(textureManager._textureAtlases) ?: return Result.Declined
if (atlasList.any { member -> member !is CTextureAtlas }) {
return Result.Declined
}
val newPageCount = edited.atlas.pages.size
// The pages are the EDITED model's inventory, in its own page order: same count, positionally
// indexed. The patch stays authoritative on dimensions, matching the reuse arm's existing
// contract.
if (recomposedPages.size != newPageCount) {
return Result.Declined
}
// --- Gather the web. ---
// The model-image and canvas-placement maps are LOCAL copies: the layer web below extends them
// with what it mints and moves, and every composition after that reads the extended state.
val web = indexAtlasWeb(textureManager)
val siteByTileId = web.siteByTileId
val strayEntryAtlasIndices = web.strayEntryAtlasIndices
val canvasAffineByTileId = HashMap(web.canvasAffineByTileId)
val modelImageByTileId = HashMap<String, CModelImage>(web.modelImageByTileId)
val retainedWeb = Cmo3RetainedLayerWeb(target, textureManager, editor, edited, tileRasters, nowMillis, textureFrames)
// --- Classify every edited tile; ANY gap declines whole. ---
// Every tile is keyed by its LINEAGE ROOT: a reloaded tile (`<guid>~<n>`, AtlasTile.replaces) is
// the model image its root imported from as far as the web knows, so its placement reads as that
// entry moving - and its layer is rewritten to the new art (a rewrite job) before the entry
// does. A tile with no model image at all has its whole layer web minted (a mint job), which
// is what lets its pack-in mint an entry.
val baselinePlacementByTileId = baseline.atlas.tiles.associateBy({ tile -> tile.id.lineageRoot.raw }, { tile -> tile.placement })
val editedTileIds = HashSet<String>()
val changedPlacementByTileId = HashMap<String, Pair<AtlasPlacement?, AtlasPlacement>>()
val boundTileIds = edited.drawables.mapNotNullTo(HashSet()) { drawable -> drawable.atlasTileId?.lineageRoot?.raw }
val moves = ArrayList<Pair<AtlasEntrySite, AtlasPlacement>>()
val packOuts = ArrayList<AtlasEntrySite>()
val packInPlacementByTileId = LinkedHashMap<String, AtlasPlacement>()
val rewriteJobs = ArrayList<Cmo3RetainedLayerWeb.RewriteJob>()
val mintJobs = ArrayList<Cmo3RetainedLayerWeb.MintJob>()
for (tile in edited.atlas.tiles) {
val tileId = tile.id.lineageRoot.raw
editedTileIds.add(tileId)
val newPlacement = tile.placement
val site = siteByTileId[tileId]
val modelImage = modelImageByTileId[tileId]
if (modelImage == null) {
// No model image: the tile's art is minted when the document holds it. An unplaced
// tile with nothing to mint has nothing to reconcile either; a placed one must mint,
// or its pack-in has no image to hang the entry on.
val job = retainedWeb.mintJobFor(tile)
if (job != null) {
mintJobs.add(job)
canvasAffineByTileId[tileId] = job.canvasAffine
} else if (newPlacement != null) {
return Result.Declined
}
} else if (tile.replaces != null) {
// A reloaded tile: the root's layer takes the new art, and the canvas placement every
// composition below reads is the refreshed row's origin.
val job = retainedWeb.rewriteJobFor(tile, modelImage) ?: return Result.Declined
rewriteJobs.add(job)
canvasAffineByTileId[tileId] = job.canvasAffine
}
if (newPlacement == null) {
if (site != null) {
// A pack-out removes the entry; a drawable still sampling the page through it
// would be stranded, so a BOUND pack-out declines (the repack never produces one).
if (tileId in boundTileIds) {
return Result.Declined
}
packOuts.add(site)
}
continue
}
if (site == null) {
// Pack-in: a never-packed tile gaining a placement mints its entry and its bound
// drawables' region inputs below - possible only when the tile's canvas placement
// resolves (a minted tile's is the job's).
if (canvasAffineByTileId[tileId] == null) {
return Result.Declined
}
if (newPlacement.pageIndex !in 0 until newPageCount || inversePlacementAffine(newPlacement) == null) {
return Result.Declined
}
packInPlacementByTileId[tileId] = newPlacement
continue
}
if (newPlacement.pageIndex !in 0 until newPageCount) {
return Result.Declined
}
if (canvasAffineByTileId[tileId] == null || inversePlacementAffine(newPlacement) == null) {
return Result.Declined
}
val oldPlacement = baselinePlacementByTileId[tileId]
if (oldPlacement != newPlacement) {
changedPlacementByTileId[tileId] = oldPlacement to newPlacement
}
if (newPlacement.pageIndex != site.atlasIndex) {
moves.add(site to newPlacement)
}
}
// Entries the edited model does not track (stray, or a tile outside the edited set) stay
// where they sit - which must survive the page-set reconcile.
for (atlasIndex in strayEntryAtlasIndices) {
if (atlasIndex >= newPageCount) {
return Result.Declined
}
}
for ((tileId, site) in siteByTileId) {
if (tileId !in editedTileIds && site.atlasIndex >= newPageCount) {
return Result.Declined
}
}
// --- Gather the drawables to retarget: every source over a placement-changed tile. ---
// CMO3: CDrawableSourceSet field _sources -> CArtMeshSource field _extensions ->
// CTextureInputExtension field _textureInputs.
val artMeshes =
Cmo3Import.elementsOf((modelSource.drawableSourceSet as? CDrawableSourceSet)?._sources)
.filterIsInstance<CArtMeshSource>()
val editedDrawableIds = edited.drawables.mapTo(HashSet()) { drawable -> drawable.id.raw }
val fileDrawableIds = HashSet<String>()
val meshByDrawableId = HashMap<String, CArtMeshSource>()
val candidates = ArrayList<RetargetCandidate>()
val packInCandidates = ArrayList<PackInCandidate>()
val existingTextureByAtlasIndex = HashMap<Int, GTexture2D>()
for (mesh in artMeshes) {
val drawableId = Cmo3Import.idStrOf(mesh.id) ?: continue
fileDrawableIds.add(drawableId)
val texture = mesh.texture as? GTexture2D
if (texture != null) {
// The page's ONE shared texture, found by resource identity - the same rule the
// import's page-packed classification reads.
val sampled = texture.srcImageResource
for ((atlasIndex, member) in atlasList.withIndex()) {
if ((member as CTextureAtlas).cachedAtlasImage === sampled) {
existingTextureByAtlasIndex.putIfAbsent(atlasIndex, texture)
}
}
}
if (drawableId !in editedDrawableIds) {
// Pending deletion: the structural pass removes the source; nothing to retarget.
continue
}
meshByDrawableId[drawableId] = mesh
val extension =
Cmo3Import.elementsOf(mesh._extensions).filterIsInstance<CTextureInputExtension>().firstOrNull() ?: continue
val tileId =
Cmo3Import.uuidOf(
Cmo3Import.elementsOf(extension._textureInputs)
.filterIsInstance<CTextureInput_ModelImage>()
.firstOrNull()
?._modelImageGuid,
) ?: continue
val region =
Cmo3Import.elementsOf(extension._textureInputs)
.filterIsInstance<CTextureInput_TextureAtlasRegion>()
.firstOrNull()
if (tileId in packInPlacementByTileId) {
if (region != null) {
// A region input over a tile with no entry is an inconsistent web; decline whole
// rather than guess which half to trust.
return Result.Declined
}
packInCandidates.add(PackInCandidate(mesh, extension, tileId))
continue
}
if (tileId !in changedPlacementByTileId) {
continue
}
if (region == null) {
// A bound drawable sampling its art directly while its tile's packing moved: the
// re-derived page-frame coordinates have no region input to ride, so decline whole.
return Result.Declined
}
val input = region.inputImageLocalToCanvasTransform as? CAffine ?: return Result.Declined
candidates.add(RetargetCandidate(mesh, region, input, tileId))
}
// Every EDITED drawable the file holds over a packed-in tile must have been found file-side,
// or its re-derived page-frame coordinates would export with nothing retargeting its sampling.
// A created drawable (not in the file yet) takes the binding path instead.
for (tileId in packInPlacementByTileId.keys) {
val editedBound = edited.drawables.count { drawable -> drawable.atlasTileId?.lineageRoot?.raw == tileId && drawable.id.raw in fileDrawableIds }
val found = packInCandidates.count { candidate -> candidate.tileId == tileId }
if (editedBound != found) {
return Result.Declined
}
}
val reconciledTileIds = HashSet<String>()
rewriteJobs.mapTo(reconciledTileIds) { job -> job.tileId }
mintJobs.mapTo(reconciledTileIds) { job -> job.tileId }
// --- Mutation. Validation is complete; anything impossible past here is a caller bug. ---
// 0. The layer web: rewrites and mints, so every model image the steps below hang an entry on
// or compose against exists and holds the edited art. A file-side drawable over reconciled
// art has its icons re-rendered, since they show the pixels that just changed.
val applied = retainedWeb.apply(rewriteJobs, mintJobs)
modelImageByTileId.putAll(applied.modelImageByTileId)
for (drawable in edited.drawables) {
val mesh = meshByDrawableId[drawable.id.raw] ?: continue
val editedTileId = drawable.atlasTileId ?: continue
if (editedTileId.lineageRoot.raw !in reconciledTileIds) {
continue
}
val raster = tileRasters(editedTileId) ?: continue
retainedWeb.replaceDrawableIcons(mesh, raster, Cmo3Icons.artUvsOf(edited, drawable))
}
// 1. Snapshots, so every rewrite reads pre-mutation values regardless of sharing.
val oldEntryHalfByTileId = HashMap<String, FloatArray>()
for (tileId in changedPlacementByTileId.keys) {
val entryHalf = siteByTileId.getValue(tileId).entry.atlasLocalToCanvasTransform as? CAffine ?: continue
oldEntryHalfByTileId[tileId] = entryHalf.toAffineArray()
}
val oldInputByRegion = IdentityHashMap<CTextureInput_TextureAtlasRegion, FloatArray>()
for (candidate in candidates) {
oldInputByRegion.getOrPut(candidate.region) { candidate.input.toAffineArray() }
}
// 2. Reuse retained pages in model order: bytes always, the dimension web on a resize. The
// resource is mutated IN PLACE, never replaced - its identity is the storedUvsAddressPages
// recovery test.
val retainedCount = minOf(atlasList.size, newPageCount)
for (pageIndex in 0 until retainedCount) {
val atlas = atlasList[pageIndex] as CTextureAtlas
val page = recomposedPages[pageIndex]
// CMO3: CTextureAtlas field cachedAtlasImage - the page's CImageResource.
val resource = atlas.cachedAtlasImage as? CImageResource ?: return Result.Declined
if (resource.imageFileBuf == null) {
return Result.Declined
}
target.replaceLayerPng(resource, page.pngBytes)
if (resource.width != page.width || resource.height != page.height) {
// CMO3: CImageResource fields width / height - corpus-verified to equal the decoded PNG's.
resource.width = page.width
resource.height = page.height
// CMO3: CTextureAtlas fields width / height - the page extent the reader trusts.
atlas.width = page.width
atlas.height = page.height
// CMO3: CTextureAtlas field cachedImageManager - rebuilt so the cache raster's
// 64-aligned padding transform describes the NEW dimensions.
atlas.cachedImageManager = Cmo3ImageChainBuilder.paddedCacheManager(resource, page.width, page.height)
}
}
// 3. Mint pages past the retained count, with the fresh conversion's own builders.
val mintedTextureByAtlasIndex = HashMap<Int, GTexture2D>()
for (pageIndex in atlasList.size until newPageCount) {
val page = recomposedPages[pageIndex]
val path = target.nextImageFileBufPath()
val resource = Cmo3ImageChainBuilder.pageImageResource(path, page.width, page.height, page.pngBytes.size)
target.addLayerPng(resource, page.pngBytes)
val atlas = Cmo3ImageChainBuilder.pageAtlas(pageIndex, page.width, page.height, resource)
atlasList.add(atlas)
mintedTextureByAtlasIndex[pageIndex] = Cmo3ImageChainBuilder.pageTexture(atlas.name, resource)
}
// 4. Re-home every cross-page entry: list membership plus the owning-page back-reference.
for ((site, newPlacement) in moves) {
val destination = atlasList[newPlacement.pageIndex] as CTextureAtlas
mutableGraphListOf(site.atlas.modelImages)?.remove(site.entry)
mutableGraphListOf(destination.modelImages)?.add(site.entry)
// CMO3: ModelImageEntry field atlas - the owning-page back-reference.
site.entry.atlas = destination
}
// 5. Pack-outs: the entry leaves its page (import reads placement=null from entry absence);
// the tile's CModelImage web stays - the art inventory is untouched.
for (site in packOuts) {
mutableGraphListOf(site.atlas.modelImages)?.remove(site.entry)
}
// The page's shared texture, for every drawable that samples the page from here on.
fun pageTextureFor(pageIndex: Int): GTexture2D {
mintedTextureByAtlasIndex[pageIndex]?.let { minted -> return minted }
return existingTextureByAtlasIndex.getOrPut(pageIndex) {
// No drawable ever sampled this retained page; give it the shared texture the fresh
// path would have built.
val atlas = atlasList[pageIndex] as CTextureAtlas
Cmo3ImageChainBuilder.pageTexture(atlas.name, atlas.cachedAtlasImage as CImageResource)
}
}
// 6. Pack-ins: mint the entry the tile never had. The transforms are written with the same
// shared math the property lowering uses, which then rewrites them identically for the
// placement diff - the mint exists so an entry is THERE to rewrite.
for ((tileId, newPlacement) in packInPlacementByTileId) {
val destination = atlasList[newPlacement.pageIndex] as CTextureAtlas
val modelImage = modelImageByTileId.getValue(tileId)
val canvasAffine = canvasAffineByTileId.getValue(tileId)
val entryHalf =
checkNotNull(atlasLocalToCanvasFor(canvasAffine, newPlacement)) {
"pack-in tile '$tileId' lost its composition after validation"
}
val entry =
Cmo3ImageChainBuilder.packedEntry(
atlas = destination,
modelImageGuid = modelImage.guid,
atlasLocalToCanvas = affineOf(entryHalf),
packing = Cmo3ImageChainBuilder.writePacking(GTransform2(), newPlacement),
)
mutableGraphListOf(destination.modelImages)?.add(entry)
}
// 7. Delete retained atlases past the edited count, highest first. Validation moved or
// removed every tracked entry; a leftover here is a validation bug, not document state.
var deletedAny = false
for (pageIndex in atlasList.size - 1 downTo newPageCount) {
val atlas = atlasList[pageIndex] as CTextureAtlas
check(Cmo3Import.elementsOf(atlas.modelImages).filterIsInstance<ModelImageEntry>().isEmpty()) {
"atlas $pageIndex still holds entries after the membership reconcile"
}
(atlas.cachedAtlasImage as? CImageResource)?.let { resource -> target.removeLayerPng(resource) }
atlasList.removeAt(pageIndex)
deletedAny = true
}
// 8. Retarget every candidate from the snapshots.
for (candidate in candidates) {
val (oldPlacement, newPlacement) = changedPlacementByTileId.getValue(candidate.tileId)
val site = siteByTileId.getValue(candidate.tileId)
if (newPlacement.pageIndex != site.atlasIndex) {
val destination = atlasList[newPlacement.pageIndex] as CTextureAtlas
// CMO3: CArtMeshSource field texture - the page's shared GTexture2D.
candidate.source.texture = pageTextureFor(newPlacement.pageIndex)
// CMO3: CTextureInput_TextureAtlasRegion field textureAtlasGuid - repointed at the
// destination atlas's own guid object (the official files' shared-ref shape).
candidate.region.textureAtlasGuid = destination.guid
}
val canvasAffine = canvasAffineByTileId.getValue(candidate.tileId)
val snapshotInput = oldInputByRegion.getValue(candidate.region)
val entryOldHalf = oldEntryHalfByTileId[candidate.tileId]
// CMO3: CTextureInput_TextureAtlasRegion field inputImageLocalToCanvasTransform - the
// PAGE-pixels-to-canvas placement the editor inverts for its mesh-over-patch views. The
// corpus keeps it equal to the entry's atlasLocalToCanvasTransform, so when the old input
// matched the entry's old half it is written through the same shared math the entry pair
// takes (bit-identical); a drawable carrying its own placement (a shared tile sampled
// from two spots) keeps its own via the exact re-fit oldInput
// composed-with P_old composed-with P_new-inverse.
val newInput =
if (entryOldHalf != null && snapshotInput.contentEquals(entryOldHalf)) {
atlasLocalToCanvasFor(canvasAffine, newPlacement)
} else if (oldPlacement != null) {
inversePlacementAffine(newPlacement)?.let { inverseNew ->
composeAffine(composeAffine(snapshotInput, placementAffine(oldPlacement)), inverseNew)
}
} else {
atlasLocalToCanvasFor(canvasAffine, newPlacement)
}
checkNotNull(newInput) { "tile '${candidate.tileId}' lost its input re-fit after validation" }
candidate.input.setFromAffineArray(newInput)
}
// 9. Pack-in drawables: a fresh region input into the EXISTING extension (the shape
// freshTextureInputExtension writes for a created drawable), the page's shared texture, and
// the live input pointer when the document displays from the atlas. The reconcile runs
// before the drawable lowering, so storedUvsFor then sees the region and writes the repack's
// page-frame coordinates verbatim.
for (candidate in packInCandidates) {
val newPlacement = packInPlacementByTileId.getValue(candidate.tileId)
val destination = atlasList[newPlacement.pageIndex] as CTextureAtlas
val inputAffine =
checkNotNull(atlasLocalToCanvasFor(canvasAffineByTileId.getValue(candidate.tileId), newPlacement)) {
"pack-in tile '${candidate.tileId}' lost its input re-fit after validation"
}
// CMO3: CArtMeshSource field texture - the page's shared GTexture2D.
candidate.source.texture = pageTextureFor(newPlacement.pageIndex)
val region =
CTextureInput_TextureAtlasRegion().apply {
// CMO3: CTextureInput_TextureAtlasRegion fields textureAtlasGuid +
// inputImageLocalToCanvasTransform (ACTextureInput super carries the owner backref).
optionalTransformOnCanvas = CAffine()
_owner = candidate.extension
textureAtlasGuid = destination.guid
inputImageLocalToCanvasTransform = affineOf(inputAffine)
}
mutableGraphListOf(candidate.extension._textureInputs)?.add(region)
if (!edited.rendersFromSourceLayers) {
// CMO3: CTextureInputExtension field currentTextureInputData - which input the
// document's display mode samples.
candidate.extension.currentTextureInputData = region
}
}
// 10. Bindings for the created drawables: every drawable the file does not hold yet whose tile
// has a model image and a placement gets the page's shared texture, the page's atlas, the
// model image, the entry's transform as its region input, and its own icons over its patch -
// the official relation, and the shape the fresh web hands the structural pass for the same
// drawable.
val editedPlacementByTileId = edited.atlas.tiles.associateBy({ tile -> tile.id.lineageRoot.raw }, { tile -> tile.placement })
val mintedBindings = HashMap<String, Cmo3DrawableTextureBinding>()
for (drawable in edited.drawables) {
if (drawable.id.raw in fileDrawableIds) {
continue
}
val editedTileId = drawable.atlasTileId ?: continue
val tileId = editedTileId.lineageRoot.raw
val placement = editedPlacementByTileId[tileId] ?: continue
val modelImage = modelImageByTileId[tileId] ?: continue
val canvasAffine = canvasAffineByTileId[tileId] ?: continue
val entryHalf = atlasLocalToCanvasFor(canvasAffine, placement) ?: continue
val destination = atlasList.getOrNull(placement.pageIndex) as? CTextureAtlas ?: continue
val icons = tileRasters(editedTileId)?.let { raster -> retainedWeb.drawableIcons(raster, Cmo3Icons.artUvsOf(edited, drawable)) }
mintedBindings[drawable.id.raw] =
Cmo3DrawableTextureBinding(
pageTextureFor(placement.pageIndex),
destination.guid as Guid,
modelImage.guid as Guid,
affineOf(entryHalf),
icon32 = icons?.first,
icon16 = icons?.second,
)
}
return Result(pagesRecomposed = true, pruneNeeded = deletedAny || packOuts.isNotEmpty() || applied.releasedCopy, mintedBindings = mintedBindings, reconciledTileIds = reconciledTileIds)
}
}
@@ -0,0 +1,210 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.raster.RasterImage
import org.umamo.interop.ExportNotice
import org.umamo.interop.ExportReport
import org.umamo.interop.cmo3TargetVersionNo
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
import kotlin.math.roundToInt
/**
* Converts a puppet with NO retained CMO3 graph (a MOC3-origin or artwork-origin document) into a
* fresh Cmo3Model: the blank skeleton plus the image chain are synthesized, serialized, and read
* back through the normal codec, then the ordinary reconcile lowers the whole puppet onto the empty
* baseline as created entities. Stateless - each call builds a new graph; the caller writes the
* result with Cmo3.write.
*
* The file this produces opens and renders in the official Cubism Editor and switches between its
* layered-art and texture-atlas display modes. An artwork-origin document writes its REAL source
* art: every tile with a raster and an inventory row becomes a layer of its file's layered image
* ([Cmo3SourceLayerWeb]), so the export is the shape the editor writes for its own PSD import and
* reopens with the same layer identities. A MOC3-origin document has none of that: a .moc3
* carries only the packed pages, so [Cmo3ImageChainBuilder] fabricates a source document by slicing
* the packed atlas back apart, every layer in that output is a slice of a baked page rather than the
* artwork the rig was drawn from, and the report leads with MissingSourceArt for as long as any
* drawable's art came out of a page.
*
* One open issue at scale: modelF (~850 MB, several hundred layers) OOMs the official editor when
* switched back to texture-atlas mode. Atlas mode recomposites the page from the materials, so
* peak memory tracks the TOTAL crop area this builder emits rather than the page size - measure
* that ratio before treating it as an editor limit.
*
* The CMO3-origin path ([Cmo3Export.apply] onto a retained graph) keeps the document's real
* layered art, and its byte-identity gates hold.
*/
public object Cmo3Conversion {
/** One atlas page: the original PNG bytes (model3 texture order) plus its pixel dimensions. */
public class AtlasPage(
public val pngBytes: ByteArray,
public val width: Int,
public val height: Int,
)
/**
* The conversion outcome: the fresh model, the reconcile's advisory report, and the puppet
* actually encoded - the input after the atlas un-dedup prepass, whose uvs differ from the
* caller's wherever a baked twin was routed to its own synthesized slot. Round-trip checks
* must compare a re-import against THIS puppet, not the caller's.
*/
public class Result(
public val model: Cmo3Model,
public val report: ExportReport,
public val puppet: PuppetModel,
)
/**
* Builds a fresh CMO3 for [puppet].
*
* @param PuppetModel puppet The model to convert (the session's current state).
* @param List pages The atlas pages, in model3 texture order.
* @param Map pageIndexByDrawableId Each drawable id's atlas page index; a drawable
* missing here cannot bind a texture and surfaces as a notice.
* @param String modelName The document display name the skeleton records.
* @param Long nowMillis The wall-clock import timestamp the image chain records.
* @param Int obfuscateKey The container XOR key; the editor mints one per save.
* @param Function tileRasters The document's own pixels for a tile, or null when it holds
* none; a tile with a raster and an inventory row writes its real
* layer, every other drawable takes the crop stand-in. A
* MOC3-origin document has no tiles and passes nothing.
* @param RasterImage modelThumbnail The model's rest-pose thumbnail the three model icons fit,
* or null for the blank icons the editor writes for a model it
* never rendered.
* @return Result The fresh model plus the reconcile report.
*/
public fun freshCmo3(
puppet: PuppetModel,
pages: List<AtlasPage>,
pageIndexByDrawableId: Map<String, Int>,
modelName: String,
nowMillis: Long,
obfuscateKey: Int,
tileRasters: (AtlasTileId) -> RasterImage? = { null },
modelThumbnail: RasterImage? = null,
): Result {
// Real layers first: a drawable whose tile has a raster and an inventory row writes that
// raster as its own layer, and leaves the crop path - the un-dedup included, since a real
// tile's model image is the single-placement shape by construction.
val sourceImages = Cmo3SourceLayerWeb.inputsOf(puppet, tileRasters)
val realDrawableIds = sourceImages.flatMapTo(HashSet()) { image -> image.layers.flatMap { layer -> layer.drawableIds } }
val cropPageIndexByDrawableId = pageIndexByDrawableId.filterKeys { drawableId -> drawableId !in realDrawableIds }
// Baked twins (one atlas slot, several canvas placements) are unrepresentable in the
// model-image web; the prepass copies each additional placement's patch onto a synthesized
// page and remaps those drawables' uvs there. Everything below runs on ITS outputs.
val undedup = Cmo3AtlasUndedup.undeduplicate(puppet, pages, cropPageIndexByDrawableId)
val effectivePuppet = undedup.puppet
val effectivePages = undedup.pages
val effectivePageIndexByDrawableId = undedup.pageIndexByDrawableId
val skeleton =
Cmo3SkeletonBuilder.buildBlank(
modelName = modelName,
canvasWidth = effectivePuppet.canvasWidth.roundToInt(),
canvasHeight = effectivePuppet.canvasHeight.roundToInt(),
targetVersionNo = effectivePuppet.runtimeTarget.cmo3TargetVersionNo(),
modelThumbnail = modelThumbnail,
)
// Each page's drawable regions feed the per-drawable patch webs (crop + placement fit).
// The puppet's mesh.positions MUST be canvas-frame here: the app's MOC3 document loader
// normalizes parent-local rest meshes through :render's restMeshesToCanvasSpace before any
// export, and callers converting a raw Moc3Import puppet must do the same (the official
// source-level positions and the whole placement web are canvas geometry).
val regionsByPage = List(effectivePages.size) { ArrayList<Cmo3ImageChainBuilder.DrawableRegion>() }
for (drawable in effectivePuppet.drawables) {
val pageIndex = effectivePageIndexByDrawableId[drawable.id.raw] ?: continue
val mesh = drawable.mesh ?: continue
regionsByPage.getOrNull(pageIndex)?.add(
Cmo3ImageChainBuilder.DrawableRegion(drawable.id.raw, mesh.uvs, mesh.positions, mesh.indices),
)
}
val chain =
Cmo3ImageChainBuilder.populate(
skeleton.root,
effectivePages,
regionsByPage,
nowMillis,
fromSourceLayers = effectivePuppet.rendersFromSourceLayers,
sourceImages = sourceImages,
)
val model =
Cmo3.read(
Cmo3FreshFile.assemble(
skeleton.root,
skeleton.iconEntries.map { icon ->
Cmo3FreshFile.PngEntry(
icon.path,
icon.pngBytes,
)
} + chain.pngEntries,
obfuscateKey,
),
)
rebindPageResources(chain, model)
val bindings = HashMap<String, Cmo3DrawableTextureBinding>()
for (drawable in effectivePuppet.drawables) {
// A real-layer drawable has its own binding; a crop-path drawable its own or its page's.
val binding =
chain.bindingByDrawableId[drawable.id.raw]
?: effectivePageIndexByDrawableId[drawable.id.raw]?.let { pageIndex -> chain.pageFallbackBindings.getOrNull(pageIndex) }
binding?.let { resolved -> bindings[drawable.id.raw] = resolved }
}
val report = Cmo3Export.apply(effectivePuppet, model, bindings)
// An export whose art did not all come from real layers - a drawable sliced out of a page or
// bound to no page, or a document with no real layer to write at all - is source-art-less, so
// the notice leads the report rather than hiding behind the per-entity findings. It is the
// one finding that describes the WHOLE file rather than an entity in it, which no amount of
// per-drawable detail would tell the user; a document whose every drawable wrote its real
// layer carries no such finding. A twin the prepass had to leave sharing its slot follows
// it, for the same reason.
val everyDrawableIsReal = sourceImages.isNotEmpty() && effectivePuppet.drawables.all { drawable -> drawable.id.raw in realDrawableIds }
val leading = ArrayList<ExportNotice>()
if (!everyDrawableIsReal) {
leading.add(ExportNotice.MissingSourceArt(effectivePages.size))
}
if (undedup.sharedDrawableIds.isNotEmpty()) {
val nameById = effectivePuppet.drawables.associate { drawable -> drawable.id.raw to drawable.name }
leading.add(ExportNotice.SharedAtlasSlotKept(undedup.sharedDrawableIds.map { drawableId -> nameById[drawableId] ?: drawableId }))
}
return Result(model, report.copy(notices = leading + report.notices), effectivePuppet)
}
/**
* Re-points each page texture at the RE-READ atlas's own page resource.
*
* The image chain is built over the pre-serialization skeleton, so a binding's GTexture2D still
* carries that graph's CImageResource - while the reconcile hangs that texture off drawables in
* the graph read back out of the assembled bytes. Left alone the document ends up with two
* equal-but-distinct resources per page (one under the atlas's cachedAtlasImage, one under the
* drawables' texture) where the editor's own files share a single one by reference.
*
* That split is not cosmetic: whether a drawable's uvs are page-frame is decided by whether the
* resource it samples IS one of the atlases' page resources (docs/format/CMO3.md section 6 - a
* document can carry an atlas while its drawables sample per-layer rasters instead), and the test
* is identity because a CImageResource has no value equality. With the twin resource in place
* every re-imported drawable reads as never-packed, so its source-layer view drops the packing
* inverse and draws atlas-frame uvs straight onto the layer crop.
*
* @param Cmo3ImageChainBuilder.BuiltImageChain chain The image chain built over the skeleton.
* @param Cmo3Model model The model read back out of the assembled bytes.
*/
private fun rebindPageResources(chain: Cmo3ImageChainBuilder.BuiltImageChain, model: Cmo3Model) {
// CMO3: CModelSource field textureManager -> CTextureManager field _textureAtlases ->
// CTextureAtlas field cachedAtlasImage - the page's own pixels.
val textureManager = (model.root as? CModelSource)?.textureManager as? CTextureManager ?: return
val pageResourceByPath = HashMap<String, CImageResource>()
for (atlas in Cmo3Import.elementsOf(textureManager._textureAtlases).filterIsInstance<CTextureAtlas>()) {
val pageResource = atlas.cachedAtlasImage as? CImageResource ?: continue
pageResource.imageFileBuf?.archivePath?.let { path -> pageResourceByPath[path] = pageResource }
}
// One texture per page, shared by every binding on it, so the page fallbacks reach them all.
for (binding in chain.pageFallbackBindings) {
val path = (binding.texture.srcImageResource as? CImageResource)?.imageFileBuf?.archivePath ?: continue
pageResourceByPath[path]?.let { pageResource -> binding.texture.srcImageResource = pageResource }
}
}
}
@@ -0,0 +1,163 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.gen.CImageIcon
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.identity.Guid
import org.umamo.format.cmo3.model.type.CAffine
/**
* The texture web a synthesized drawable binds to when it has no existing source to clone - the
* per-page objects the image-chain builder created (docs/format/CMO3.md §4 How a Drawable
* References its Texture). Instances are shared per atlas page: every drawable on the page
* references the SAME GTexture2D and guid objects, so the writer hoists them exactly like the
* editor's own files (one atlas GTexture2D for all packed drawables). The icons are the drawable's
* own (one per drawable, like the editor's files), their PNG entries already collected or embedded
* by whoever built the binding.
*/
public class Cmo3DrawableTextureBinding(
/** The page's shared texture (srcImageResource = the page CImageResource). */
val texture: GTexture2D,
/** The page's CTextureAtlas guid - the atlas-region input's target. */
val textureAtlasGuid: Guid,
/** The drawable's own CModelImage guid (its patch web), or null when it has no patch. */
val modelImageGuid: Guid?,
/** The drawable's fitted atlas-page-to-canvas placement (the region input's transform). */
val inputImageLocalToCanvasTransform: CAffine,
/** The drawable's 32px thumbnail of its texture patch, or null when it has no art to show. */
val icon32: CImageIcon? = null,
/** The drawable's 16px thumbnail, or null likewise. */
val icon16: CImageIcon? = null,
)
/**
* Fits a drawable's atlas-page-to-canvas placement transform: the affine mapping page pixel
* coordinates (uv times page size) onto the drawable's base mesh positions.
*
* CMO3: CTextureInput_TextureAtlasRegion field inputImageLocalToCanvasTransform - the editor
* inverts this to place the mesh over its texture patch in the atlas and mesh-edit views, so an
* identity here draws every mesh at its assembled canvas position instead. Cubism-authored
* mappings are exact per-drawable affines (the layer's canvas translation composed with the
* packer's scale, rotation, and translate), so a least-squares fit recovers them to float
* precision; a degenerate mesh falls back to a single-axis regression, then to a pure centroid
* translation.
*
* The moments are accumulated about the point cloud's MEAN, not about the page origin, and that is
* load-bearing rather than a tidiness preference. A patch sits thousands of pixels out on a
* 16384-square page while spanning only a few hundred, so origin-referenced moments are dominated
* by the offset: the system's conditioning picks up the squared offset-to-spread ratio, the
* informative pivot falls far below any offset-scaled singularity tolerance, and a perfectly
* determined fit is rejected as degenerate. What it degrades to - a per-axis regression - cannot
* express an off-diagonal term at all, so a drawable the packer rotated comes back squashed onto
* the wrong axis. Centering drops the offset term outright: the solve sees only the cloud's own
* shape, and the translation comes back from the means.
*
* A packing that rotates or mirrors the patch is therefore carried faithfully. The crop the image
* chain slices out is still the axis-aligned uv bounding box, which for a rotated patch encloses
* the art plus its surrounding page pixels - that is a property of reconstructing source art from a
* baked page, and real source art removes it along with the fit itself.
*
* This fit exists only because a MOC3-origin export has to RECONSTRUCT the placement a CMO3 would
* have read straight off its source art - see [Cmo3ImageChainBuilder]'s header for why that whole
* reconstruction is a stopgap. A residual survives it by construction for any drawable under a
* warp deformer: the exported base mesh is the rest pose pushed through the warp's lattice, whose
* bilinear map is not affine, so no CAffine reproduces it exactly. The fit is the closest affine,
* which is what the atlas view needs.
*
* @param FloatArray uvs Interleaved atlas-frame texture coordinates (u then v per vertex).
* @param FloatArray positions Interleaved base canvas positions (x then y per vertex).
* @param Int pageWidth The atlas page's pixel width.
* @param Int pageHeight The atlas page's pixel height.
* @return CAffine The fitted transform (identity when there are no vertices).
*/
internal fun fitAtlasPageToCanvasTransform(uvs: FloatArray, positions: FloatArray, pageWidth: Int, pageHeight: Int): CAffine {
val vertexCount = minOf(uvs.size, positions.size) / 2
if (vertexCount == 0) {
return CAffine()
}
val pointCount = vertexCount.toDouble()
var meanPageX = 0.0
var meanPageY = 0.0
val meanCanvas = DoubleArray(2)
for (vertexIndex in 0 until vertexCount) {
meanPageX += uvs[2 * vertexIndex].toDouble() * pageWidth
meanPageY += uvs[2 * vertexIndex + 1].toDouble() * pageHeight
for (axis in 0 until 2) {
meanCanvas[axis] += positions[2 * vertexIndex + axis].toDouble()
}
}
meanPageX /= pointCount
meanPageY /= pointCount
meanCanvas[0] /= pointCount
meanCanvas[1] /= pointCount
// Centered second moments: the page cloud's own covariance plus its cross-covariance with each
// canvas axis. These are the normal equations of `canvas = a*pageX + b*pageY + t` with t
// eliminated, which is exactly what centering buys.
var pageXX = 0.0
var pageXY = 0.0
var pageYY = 0.0
val canvasPageX = DoubleArray(2)
val canvasPageY = DoubleArray(2)
for (vertexIndex in 0 until vertexCount) {
val pageX = uvs[2 * vertexIndex].toDouble() * pageWidth - meanPageX
val pageY = uvs[2 * vertexIndex + 1].toDouble() * pageHeight - meanPageY
pageXX += pageX * pageX
pageXY += pageX * pageY
pageYY += pageY * pageY
for (axis in 0 until 2) {
val canvas = positions[2 * vertexIndex + axis].toDouble() - meanCanvas[axis]
canvasPageX[axis] += pageX * canvas
canvasPageY[axis] += pageY * canvas
}
}
val determinant = pageXX * pageYY - pageXY * pageXY
// Relative test: the page cloud spans two independent directions only when its covariance
// determinant is a real fraction of the product of its variances. A patch collapsed to a line
// (a degenerate mesh) fails here and takes the single-axis path below.
val hasTwoAxisSpread = determinant > 1e-12 * pageXX * pageYY
val linear = Array(2) { DoubleArray(2) }
for (axis in 0 until 2) {
if (hasTwoAxisSpread) {
linear[axis][0] = (canvasPageX[axis] * pageYY - canvasPageY[axis] * pageXY) / determinant
linear[axis][1] = (canvasPageY[axis] * pageXX - canvasPageX[axis] * pageXY) / determinant
continue
}
// Collinear page cloud: regress against whichever page axis actually carries the spread, so
// a rotated strip still recovers its coefficient instead of dividing by nothing. The other
// column is unconstrained by the data and takes its identity value rather than zero - a zero
// column would make the affine singular, and the editor INVERTS this transform to draw the
// mesh over its patch.
if (pageXX >= pageYY && pageXX > 0.0) {
linear[axis][0] = canvasPageX[axis] / pageXX
linear[axis][1] = if (axis == 1) 1.0 else 0.0
} else if (pageYY > 0.0) {
linear[axis][0] = if (axis == 0) 1.0 else 0.0
linear[axis][1] = canvasPageY[axis] / pageYY
} else {
// Every vertex shares one page pixel: nothing to scale, so place by the centroid alone.
linear[axis][0] = if (axis == 0) 1.0 else 0.0
linear[axis][1] = if (axis == 0) 0.0 else 1.0
}
}
// A near-identity linear part is least-squares noise on a pure translation (the editor's own
// unscaled packings): snap it so the written transform matches the editor's exact-translation
// shape instead of 0.9999997-style drift.
if (kotlin.math.abs(linear[0][0] - 1.0) < 1e-3 &&
kotlin.math.abs(linear[0][1]) < 1e-3 &&
kotlin.math.abs(linear[1][0]) < 1e-3 &&
kotlin.math.abs(linear[1][1] - 1.0) < 1e-3
) {
linear[0][0] = 1.0
linear[0][1] = 0.0
linear[1][0] = 0.0
linear[1][1] = 1.0
}
val transform = CAffine()
// The translation is whatever carries the page mean onto the canvas mean under the linear part.
transform.m00 = linear[0][0].toFloat()
transform.m01 = linear[0][1].toFloat()
transform.m02 = (meanCanvas[0] - linear[0][0] * meanPageX - linear[0][1] * meanPageY).toFloat()
transform.m10 = linear[1][0].toFloat()
transform.m11 = linear[1][1].toFloat()
transform.m12 = (meanCanvas[1] - linear[1][0] * meanPageX - linear[1][1] * meanPageY).toFloat()
return transform
}
@@ -0,0 +1,387 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.edit
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.raster.RasterImage
import org.umamo.interop.DeformerField
import org.umamo.interop.DrawableField
import org.umamo.interop.EntityDiff
import org.umamo.interop.ExportFormat
import org.umamo.interop.ExportNotice
import org.umamo.interop.ExportReport
import org.umamo.interop.GlueDiff
import org.umamo.interop.GlueField
import org.umamo.interop.ParameterField
import org.umamo.interop.ParameterGroupField
import org.umamo.interop.PartField
import org.umamo.interop.PuppetDiff
import org.umamo.interop.diffPuppetModels
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.Deformer
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.Part
import org.umamo.runtime.model.PuppetModel
/**
* Lowers an edited [PuppetModel] back onto the retained CMO3 graph it was imported from - the
* export half of the CMO3 interop boundary (Cmo3Import is the import half).
*
* The design is a state-based reconcile, not a Change-log replay: [apply] re-imports the graph
* to get a baseline, diffs the edited model against it, and only diff entries touch the graph.
* An unedited model therefore leaves the graph untouched and a subsequent Cmo3.write byte-
* identical; a re-export after an export reconciles against the just-updated graph and is a
* no-op. Structure runs first (created entities get identity shells, deleted ones leave their
* source sets), then every surviving/created entity's fields flow through the one field-level
* lowering path. Edits the lowering cannot (yet or ever) express in CMO3 are returned as
* notices, never silently dropped.
*
* The graph is mutated IN PLACE ([Cmo3Model] holds identity-keyed reconcile metadata a deep
* copy cannot carry). The full diff is computed before any mutation, so a failed export
* leaves either the untouched or the fully-reconciled graph - and either way the next apply
* self-heals from model state.
*/
object Cmo3Export {
/** Every field of a synthesized drawable, so its shell is populated through the Changed path. */
private val ALL_DRAWABLE_FIELDS =
setOf(
DrawableField.NAME,
DrawableField.PARENT_DEFORMER,
DrawableField.BLEND_MODE,
DrawableField.ALPHA_BLEND_MODE,
DrawableField.MASKED_BY,
DrawableField.INVERT_MASK,
DrawableField.CULLING,
DrawableField.VISIBLE,
DrawableField.SELECTABLE,
DrawableField.MESH_TOPOLOGY,
DrawableField.GEOMETRY,
DrawableField.CHANNELS,
DrawableField.STATICS,
DrawableField.BLEND_SHAPES,
)
/** Every field of a synthesized part. */
private val ALL_PART_FIELDS = PartField.entries.toSet()
/** Every warp field except KIND (fixed at synthesis) and the rotation-only BASE_ANGLE. */
private val ALL_WARP_FIELDS = DeformerField.entries.toSet() - DeformerField.KIND - DeformerField.BASE_ANGLE
/** Every rotation field except KIND (fixed at synthesis) and the warp-only lattice pair. */
private val ALL_ROTATION_FIELDS =
DeformerField.entries.toSet() - DeformerField.KIND - DeformerField.LATTICE - DeformerField.QUAD_TRANSFORM
/** Every field of a synthesized glue. */
private val ALL_GLUE_FIELDS = GlueField.entries.toSet()
/**
* Reconciles [edited] onto [target]'s graph in place and returns the advisory report.
*
* The fresh-graph synthesis path (MOC3-origin -> CMO3) constructs a blank target graph and
* reuses this same reconcile: an empty baseline lowers everything as created, with
* [drawableTextureBindings] supplying the texture web created drawables bind to when they have
* no existing source to clone (a session duplicate) - the CMO3-origin export path passes none,
* and its created drawables over reconciled art bind through the bindings the atlas-web
* reconcile mints instead.
*
* @param PuppetModel edited The session's current model (EditorSession.model.value - NOT the
* document's original import, which edits never update).
* @param Cmo3Model target The retained CMO3 model whose graph receives the edits.
* @param Map drawableTextureBindings Per-drawable-id texture webs for created drawables
* without a texture source; empty for CMO3-origin exports.
* @param List recomposedPages The pages a repack composed for the edited model's packing,
* in the edited model's page order; empty when the session did not
* repack, which leaves the graph and archive untouched.
* @param Function tileRasters The document's own pixels for a tile, or null when it holds none;
* a reloaded or added tile with a raster writes its real layer into the
* retained graph, and one without declines the atlas-web reconcile.
* @param Long nowMillis The timestamp a layer minted into the retained graph records.
* @param RasterImage modelThumbnail The model's rest-pose thumbnail the three model icons take on
* an edited export, or null to leave the icons the graph has.
* @return ExportReport The notices for everything not (yet) lowered.
*/
fun apply(
edited: PuppetModel,
target: Cmo3Model,
drawableTextureBindings: Map<String, Cmo3DrawableTextureBinding> = emptyMap(),
recomposedPages: List<Cmo3Conversion.AtlasPage> = emptyList(),
tileRasters: (AtlasTileId) -> RasterImage? = { null },
nowMillis: Long = 0L,
modelThumbnail: RasterImage? = null,
): ExportReport {
val modelSource = target.root as? CModelSource ?: error("CMO3 model root is not a CModelSource")
val baseline = Cmo3Import.fromModelSource(modelSource)
val diff = diffPuppetModels(baseline, edited)
if (diff.isEmpty) {
return ExportReport(ExportFormat.Cmo3, emptyList())
}
// Taken before any pass writes: a reload rewrite rebuilds a model image's cache, and every later
// pass must still know which textures were the editor's reduced copies.
val textureFrames = Cmo3TextureFrames(modelSource)
val notices = ArrayList<ExportNotice>()
val editor = target.edit()
// The atlas-web reconcile runs before the graph lowering so the stale-page notices know
// whether the stored pages already show the new packing. Strictly diff-gated by the CALLER:
// an unedited document passes no pages, and the graph and archive are then never touched.
val webResult = Cmo3AtlasWebLowering(target, modelSource, baseline, edited, editor, tileRasters, nowMillis, textureFrames).reconcile(recomposedPages)
val pagesRecomposed = webResult.pagesRecomposed
// The model icons follow an edited export (the diff is non-empty here): the editor regenerates
// them on its own saves, and a thumbnail of the rest pose is what it shows for the file.
if (modelThumbnail != null) {
(modelSource.textureManager as? CTextureManager)?.let { textureManager ->
Cmo3RetainedLayerWeb(target, textureManager, editor, edited, tileRasters, nowMillis, textureFrames).replaceModelIcons(modelSource, modelThumbnail)
}
}
// A created drawable over art the reconcile minted binds through the binding it handed back;
// a caller's own binding for the same drawable (the fresh-graph path) outranks it.
val bindings =
if (webResult.mintedBindings.isEmpty()) {
drawableTextureBindings
} else {
webResult.mintedBindings + drawableTextureBindings
}
// Structural pass - set membership: identity shells for creations, source removal for
// deletions. Category order follows the reference web (parameters/groups first, then parts
// and deformers, then the drawables that bind to them, then the glues that bind drawables),
// and the structural index is REBUILT between categories so same-export creations resolve.
var anyDeleted = webResult.pruneNeeded
var structural =
Cmo3StructureLowering(
modelSource,
Cmo3GraphIndex(modelSource),
editor,
edited,
notices,
textureFrames,
bindings,
)
/**
* Rolls the structural lowering onto a fresh index, carrying the deletion flag forward.
*
* @return Cmo3StructureLowering The replacement instance.
*/
fun refreshedStructural(): Cmo3StructureLowering {
anyDeleted = anyDeleted || structural.deletedAnything
return Cmo3StructureLowering(
modelSource,
Cmo3GraphIndex(modelSource),
editor,
edited,
notices,
textureFrames,
bindings,
)
}
val editedParameterById = edited.parameters.associateBy(Parameter::id)
val editedPartById = edited.parts.associateBy(Part::id)
val editedDeformerById = edited.deformers.associateBy(Deformer::id)
val editedDrawableById = edited.drawables.associateBy(Drawable::id)
val synthesizedParameters = HashSet<Any>()
val synthesizedGroups = HashSet<Any>()
val synthesizedParts = HashSet<Any>()
val synthesizedDeformers = HashSet<Any>()
val synthesizedDrawables = HashSet<Any>()
val synthesizedGlues = HashSet<Triple<Any, Any, Int>>()
for (entityDiff in diff.parameters) {
when (entityDiff) {
is EntityDiff.Created ->
editedParameterById[entityDiff.id]?.let { parameter ->
if (structural.synthesizeParameter(parameter)) {
synthesizedParameters.add(entityDiff.id)
}
}
is EntityDiff.Deleted -> structural.deleteParameter(entityDiff.id)
is EntityDiff.Changed -> Unit
}
}
for (entityDiff in diff.parameterGroups) {
when (entityDiff) {
is EntityDiff.Created ->
if (structural.synthesizeParameterGroup(entityDiff.id)) {
synthesizedGroups.add(entityDiff.id)
}
is EntityDiff.Deleted -> structural.deleteParameterGroup(entityDiff.id)
is EntityDiff.Changed -> Unit
}
}
for (entityDiff in diff.parts) {
when (entityDiff) {
is EntityDiff.Created ->
editedPartById[entityDiff.id]?.let { part ->
if (structural.synthesizePart(part)) {
synthesizedParts.add(entityDiff.id)
}
}
is EntityDiff.Deleted -> structural.deletePart(entityDiff.id.raw)
is EntityDiff.Changed -> Unit
}
}
for (entityDiff in diff.deformers) {
when (entityDiff) {
is EntityDiff.Created ->
editedDeformerById[entityDiff.id]?.let { deformer ->
if (structural.synthesizeDeformer(deformer)) {
synthesizedDeformers.add(entityDiff.id)
}
}
is EntityDiff.Deleted -> structural.deleteDeformer(entityDiff.id.raw)
is EntityDiff.Changed -> Unit
}
}
structural = refreshedStructural()
for (entityDiff in diff.drawables) {
when (entityDiff) {
is EntityDiff.Created ->
editedDrawableById[entityDiff.id]?.let { drawable ->
if (structural.synthesizeDrawable(drawable)) {
synthesizedDrawables.add(entityDiff.id)
}
}
is EntityDiff.Deleted -> structural.deleteDrawable(entityDiff.id)
is EntityDiff.Changed -> Unit
}
}
structural = refreshedStructural()
val editedGluesByPair = edited.glues.groupBy { glue -> glue.meshA to glue.meshB }
for (glueDiff in diff.glues) {
when (glueDiff) {
is GlueDiff.Created ->
editedGluesByPair[glueDiff.meshA to glueDiff.meshB]?.getOrNull(glueDiff.ordinal)?.let { glue ->
if (structural.synthesizeGlue(glue, glueDiff.ordinal)) {
synthesizedGlues.add(Triple(glueDiff.meshA, glueDiff.meshB, glueDiff.ordinal))
}
}
is GlueDiff.Deleted -> structural.deleteGlue(glueDiff.meshA, glueDiff.meshB, glueDiff.ordinal)
is GlueDiff.Changed -> Unit
}
}
anyDeleted = anyDeleted || structural.deletedAnything
// Deletions are done; synthesized creations become Changed-with-every-field so their shells
// are populated by the ordinary field lowering (one tested path, no synthesis copy of it).
val upgradedDiff =
PuppetDiff(
parameters =
diff.parameters.mapNotNull { entityDiff ->
when {
entityDiff is EntityDiff.Created && entityDiff.id in synthesizedParameters ->
EntityDiff.Changed(entityDiff.id, setOf(ParameterField.NAME, ParameterField.RANGE))
entityDiff is EntityDiff.Deleted -> null
else -> entityDiff
}
},
parameterGroups =
diff.parameterGroups.mapNotNull { entityDiff ->
when {
entityDiff is EntityDiff.Created && entityDiff.id in synthesizedGroups ->
EntityDiff.Changed(
entityDiff.id,
setOf(
ParameterGroupField.NAME,
ParameterGroupField.INITIALLY_OPEN,
ParameterGroupField.CHILDREN,
),
)
entityDiff is EntityDiff.Deleted -> null
else -> entityDiff
}
},
parts =
diff.parts.mapNotNull { entityDiff ->
when {
entityDiff is EntityDiff.Created && entityDiff.id in synthesizedParts ->
EntityDiff.Changed(entityDiff.id, ALL_PART_FIELDS)
entityDiff is EntityDiff.Deleted -> null
else -> entityDiff
}
},
deformers =
diff.deformers.mapNotNull { entityDiff ->
when {
entityDiff is EntityDiff.Created && entityDiff.id in synthesizedDeformers ->
EntityDiff.Changed(
entityDiff.id,
if (editedDeformerById[entityDiff.id] is Deformer.Warp) ALL_WARP_FIELDS else ALL_ROTATION_FIELDS,
)
entityDiff is EntityDiff.Deleted -> null
else -> entityDiff
}
},
drawables =
diff.drawables.mapNotNull { entityDiff ->
when {
entityDiff is EntityDiff.Created && entityDiff.id in synthesizedDrawables ->
EntityDiff.Changed(entityDiff.id, ALL_DRAWABLE_FIELDS)
entityDiff is EntityDiff.Deleted -> null
else -> entityDiff
}
},
glues =
diff.glues.mapNotNull { glueDiff ->
when {
glueDiff is GlueDiff.Created &&
Triple<Any, Any, Int>(
glueDiff.meshA,
glueDiff.meshB,
glueDiff.ordinal,
) in synthesizedGlues ->
GlueDiff.Changed(glueDiff.meshA, glueDiff.meshB, glueDiff.ordinal, ALL_GLUE_FIELDS)
glueDiff is GlueDiff.Deleted -> null
else -> glueDiff
}
},
// Tiles have no structural pass: art arrives and leaves with an import, never with a pack,
// so a created or deleted tile forwards as-is and takes its notice in the lowering.
atlasTiles = diff.atlasTiles,
document = diff.document,
)
// Field-lowering pass over a REBUILT index (it must see the shells and forget the removed
// sources). Parameters and groups first (tree rebuilds reference their sources), then
// deformer moves (they mutate _childGuids), then parts (whose CHILDREN rebuild anchors on
// the moved lists), then drawables, glues, and the document fields.
val lowering =
Cmo3PropertyLowering(
target = target,
index = Cmo3GraphIndex(modelSource),
editor = editor,
baseline = baseline,
edited = edited,
notices = notices,
textureFrames = textureFrames,
pagesRecomposed = pagesRecomposed,
reconciledTileIds = webResult.reconciledTileIds,
)
lowering.lowerParameters(upgradedDiff.parameters)
lowering.lowerParameterGroups(upgradedDiff.parameterGroups)
lowering.lowerDeformers(upgradedDiff.deformers)
lowering.lowerParts(upgradedDiff.parts)
lowering.lowerDrawables(upgradedDiff.drawables)
lowering.flushWeldNotice()
lowering.lowerGlues(upgradedDiff.glues)
lowering.lowerAtlasTiles(upgradedDiff.atlasTiles)
lowering.lowerDocument(upgradedDiff.document)
if (anyDeleted) {
editor.pruneUnreachableShared()
}
return ExportReport(ExportFormat.Cmo3, notices)
}
}
@@ -0,0 +1,40 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.Cmo3Author
import org.umamo.format.cmo3.caff.CaffArchive
import org.umamo.format.cmo3.caff.CaffCodec
import org.umamo.format.cmo3.caff.CaffEntry
import org.umamo.format.cmo3.caff.CompressOption
/**
* Assembles a complete .cmo3 byte stream for a fresh (never-read) model root, following the
* corpus-wide container conventions (docs/format/CMO3.md §2 invariants): every entry obfuscated,
* PNG entries RAW with an empty tag, main.xml FAST-compressed and LAST in the file table.
*
* The result is meant to be fed straight back through `Cmo3.read`, which returns a [Cmo3Model]
* with normal read-side metadata - the reconcile exporter then treats the fresh graph exactly
* like a read document.
*/
internal object Cmo3FreshFile {
/** One embedded PNG entry: the unique archive path plus the raw PNG bytes. */
internal class PngEntry(val path: String, val pngBytes: ByteArray)
/**
* Serializes [root] via [Cmo3Author] and wraps it with the given PNGs into a CAFF container.
*
* @param Any root The fresh model root (a CModelSource web built in memory).
* @param List pngEntries The embedded PNGs, in allocation order (icons, then pages).
* @param Int obfuscateKey The container XOR key; the editor mints one per save.
* @return ByteArray The complete .cmo3 file bytes.
*/
internal fun assemble(root: Any, pngEntries: List<PngEntry>, obfuscateKey: Int): ByteArray {
val entries = ArrayList<CaffEntry>(pngEntries.size + 1)
for (pngEntry in pngEntries) {
// CMO3: PNG entries - tag "", RAW compression, obfuscated (corpus invariant).
entries.add(CaffEntry(pngEntry.path, "", pngEntry.pngBytes, CompressOption.RAW, obfuscated = true))
}
// CMO3: the main_xml entry - FAST compression, obfuscated, LAST in the table (corpus invariant).
entries.add(CaffEntry("main.xml", CaffArchive.TAG_MAIN_XML, Cmo3Author.writeFreshMainXml(root), CompressOption.FAST, obfuscated = true))
return CaffCodec.write(CaffArchive(obfuscateKey = obfuscateKey, entries = entries))
}
}
@@ -0,0 +1,84 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.ACDeformerSource
import org.umamo.format.cmo3.model.gen.CAffecterSourceSet
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CDeformerSourceSet
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.CGlueSource
import org.umamo.format.cmo3.model.gen.CParameterGroup
import org.umamo.format.cmo3.model.gen.CParameterGroupSet
import org.umamo.format.cmo3.model.gen.CParameterSource
import org.umamo.format.cmo3.model.gen.CParameterSourceSet
import org.umamo.format.cmo3.model.gen.CPartSource
import org.umamo.format.cmo3.model.gen.CPartSourceSet
/**
* Lookup index over a CMO3 model graph for the export reconcile: every source category listed and
* keyed by its runtime id (the Id.idstr the import carries verbatim) and by GUID uuid. Mirrors
* Cmo3Import's pass 1, in the opposite direction: where import resolves graph references to runtime
* ids, the lowering resolves runtime ids back to the graph objects it must mutate.
*/
internal class Cmo3GraphIndex(val modelSource: CModelSource) {
val parameterSources: List<CParameterSource> =
Cmo3Import.elementsOf((modelSource.parameterSourceSet as? CParameterSourceSet)?._sources)
.filterIsInstance<CParameterSource>()
private val allPartSources: List<CPartSource> =
Cmo3Import.elementsOf((modelSource.partSourceSet as? CPartSourceSet)?._sources)
.filterIsInstance<CPartSource>()
/** The synthetic __RootPart__ tree anchor (excluded from the runtime parts list). */
val rootPartSource: CPartSource? = modelSource.rootPart as? CPartSource
/** The user-facing parts, excluding the synthetic root - the ones runtime PartIds resolve to. */
val userPartSources: List<CPartSource> =
allPartSources.filter { part -> Cmo3Import.uuidOf(part.guid) != Cmo3Import.uuidOf(rootPartSource?.guid) }
val deformerSources: List<ACDeformerSource> =
Cmo3Import.elementsOf((modelSource.deformerSourceSet as? CDeformerSourceSet)?._sources)
.filterIsInstance<ACDeformerSource>()
val drawableSources: List<CArtMeshSource> =
Cmo3Import.elementsOf((modelSource.drawableSourceSet as? CDrawableSourceSet)?._sources)
.filterIsInstance<CArtMeshSource>()
val glueSources: List<CGlueSource> =
Cmo3Import.elementsOf((modelSource.affecterSourceSet as? CAffecterSourceSet)?._sources)
.filterIsInstance<CGlueSource>()
val groupSources: List<CParameterGroup> =
Cmo3Import.elementsOf((modelSource.parameterGroupSet as? CParameterGroupSet)?._groups)
.filterIsInstance<CParameterGroup>()
/** The hidden top parameter group whose _childGuids is the panel's authoritative root order. */
val rootParameterGroup: CParameterGroup? = modelSource.rootParameterGroup as? CParameterGroup
val parameterByIdStr: Map<String, CParameterSource> = byIdStr(parameterSources) { it.id }
val partByIdStr: Map<String, CPartSource> = byIdStr(userPartSources) { it.id }
val deformerByIdStr: Map<String, ACDeformerSource> = byIdStr(deformerSources) { it.id }
val drawableByIdStr: Map<String, CArtMeshSource> = byIdStr(drawableSources) { it.id }
val groupByIdStr: Map<String, CParameterGroup> = byIdStr(groupSources) { it.id }
/** User-part uuids - with [drawableUuids], the org-child classification for _childGuids walks. */
val userPartUuids: Set<String> = userPartSources.mapNotNull { Cmo3Import.uuidOf(it.guid) }.toSet()
val drawableUuids: Set<String> = drawableSources.mapNotNull { Cmo3Import.uuidOf(it.guid) }.toSet()
/** Drawable guid uuid to its runtime id string - the glue targets' resolution key. */
val drawableIdStrByUuid: Map<String, String> =
buildMap {
for (source in drawableSources) {
val uuid = Cmo3Import.uuidOf(source.guid) ?: continue
val idStr = Cmo3Import.idStrOf(source.id) ?: continue
put(uuid, idStr)
}
}
private fun <TSource> byIdStr(sources: List<TSource>, idOf: (TSource) -> Any?): Map<String, TSource> =
buildMap {
for (source in sources) {
Cmo3Import.idStrOf(idOf(source))?.let { idStr -> put(idStr, source) }
}
}
}
@@ -0,0 +1,12 @@
package org.umamo.interop.cmo3
/**
* The graph collection field as the mutable list the XML reader materialized, or null when the
* field is absent or holds no list. The reader's collections erase to MutableList<Any?>, so this
* is the one home for the unavoidable unchecked cast every in-place list mutation needs.
*
* @param Any? field The owner's collection field value.
* @return MutableList? The field's mutable list, or null.
*/
@Suppress("UNCHECKED_CAST")
internal fun mutableGraphListOf(field: Any?): MutableList<Any?>? = field as? MutableList<Any?>
@@ -0,0 +1,134 @@
package org.umamo.interop.cmo3
import org.umamo.format.art.LayerBounds
import org.umamo.format.cmo3.model.custom.CWritableImage
import org.umamo.format.cmo3.model.gen.CImageIcon
import org.umamo.format.cmo3.model.type.FileRef
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.format.raster.cropped
import org.umamo.format.raster.fittedInto
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.applyUvAffine
import org.umamo.runtime.model.storedToArtAffineForTile
import kotlin.math.ceil
import kotlin.math.floor
/*
* The thumbnails a CMO3 carries, as the official editor writes them (docs/format/CMO3.md section 4,
* Thumbnails): every icon is a CImageIcon over a CWritableImage naming an image*.png entry, a
* straight-alpha RGBA PNG exactly the square's size, holding the art fitted into the square. A
* layer's icons fit its whole raster, a model image's its filtered image, a drawable's the patch its
* mesh covers on that image, the model's a rendered thumbnail. One builder serves the fresh graph
* (entries collected for the assembler) and the retained graph (entries embedded as they are
* minted, or replaced in place at an icon's existing path).
*/
/**
* The icon builders.
*/
internal object Cmo3Icons {
/** The three model icon edges, in the order CModelSource carries them (_icon64, _icon32, _icon16). */
val MODEL_ICON_SIZES: List<Int> = listOf(64, 32, 16)
/**
* The PNG an icon of [size] holds for [raster].
*
* @param RasterImage raster The art.
* @param Int size The square's edge.
* @return ByteArray The encoded PNG.
*/
fun iconPngOf(raster: RasterImage, size: Int): ByteArray = PngCodec.write(raster.fittedInto(size))
/**
* An icon of [raster] at [size], its PNG collected for the assembler under [path].
*
* @param RasterImage raster The art.
* @param Int size The square's edge.
* @param String path The unique archive path for the PNG entry.
* @param MutableList entries The PNG entry collector.
* @return CImageIcon The icon.
*/
fun iconOf(raster: RasterImage, size: Int, path: String, entries: MutableList<Cmo3FreshFile.PngEntry>): CImageIcon {
entries.add(Cmo3FreshFile.PngEntry(path, iconPngOf(raster, size)))
return iconReferencing(size, path)
}
/**
* An icon wrapper referencing an embedded PNG entry the caller owns.
*
* @param Int size The square's edge.
* @param String path The archive entry path the icon references.
* @return CImageIcon The icon.
*/
fun iconReferencing(size: Int, path: String): CImageIcon =
CImageIcon().apply {
image =
CWritableImage().apply {
// CMO3: CWritableImage attrs width/height/type + file child (every corpus icon).
width = size
height = size
type = "INT_ARGB"
image = FileRef().apply { archivePath = path }
}
}
/**
* The archive path an icon's PNG lives at, or null when the slot holds no such icon.
*
* @param Any? icon A CImageIcon slot.
* @return String? The path.
*/
fun archivePathOf(icon: Any?): String? = ((icon as? CImageIcon)?.image as? CWritableImage)?.image?.archivePath
/**
* The patch a drawable's icon shows: the mesh's uv bounding box on its art, or the whole art when
* the mesh is unknown.
*
* @param RasterImage raster The art the drawable samples, in its own frame.
* @param FloatArray? artUvs The drawable's texture coordinates in that frame, interleaved, or null.
* @return RasterImage The patch.
*/
fun patchOf(raster: RasterImage, artUvs: FloatArray?): RasterImage {
if (artUvs == null || artUvs.size < 2 || raster.width <= 0 || raster.height <= 0) {
return raster
}
var minU = Float.POSITIVE_INFINITY
var minV = Float.POSITIVE_INFINITY
var maxU = Float.NEGATIVE_INFINITY
var maxV = Float.NEGATIVE_INFINITY
var componentIndex = 0
while (componentIndex + 1 < artUvs.size) {
minU = minOf(minU, artUvs[componentIndex])
maxU = maxOf(maxU, artUvs[componentIndex])
minV = minOf(minV, artUvs[componentIndex + 1])
maxV = maxOf(maxV, artUvs[componentIndex + 1])
componentIndex += 2
}
if (!minU.isFinite() || !minV.isFinite() || !maxU.isFinite() || !maxV.isFinite()) {
return raster
}
// The box in pixels, clamped to the art and at least one pixel each way.
val left = floor(minU * raster.width).toInt().coerceIn(0, raster.width - 1)
val top = floor(minV * raster.height).toInt().coerceIn(0, raster.height - 1)
val right = ceil(maxU * raster.width).toInt().coerceIn(left + 1, raster.width)
val bottom = ceil(maxV * raster.height).toInt().coerceIn(top + 1, raster.height)
return raster.cropped(LayerBounds(left, top, right - left, bottom - top))
}
/**
* A drawable's texture coordinates in its tile's own frame, or null when it has no mesh or its
* tile's mapping cannot be formed - the same mapping the rig-work check reads.
*
* @param PuppetModel model The model the drawable belongs to.
* @param Drawable drawable The drawable.
* @return FloatArray? The art-frame uvs, interleaved.
*/
fun artUvsOf(model: PuppetModel, drawable: Drawable): FloatArray? {
val uvs = drawable.mesh?.uvs?.takeIf { stored -> stored.isNotEmpty() } ?: return null
val tileId = drawable.atlasTileId ?: return null
val storedToArt = model.atlas.storedToArtAffineForTile(tileId) ?: return null
return applyUvAffine(uvs, storedToArt)
}
}
@@ -0,0 +1,799 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.Cmo3GraphEditor
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CLayer
import org.umamo.format.cmo3.model.custom.CModelImage
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.custom.CWritableImage
import org.umamo.format.cmo3.model.gen.ACLayerGroup
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.CImageIcon
import org.umamo.format.cmo3.model.gen.CLayerGroup
import org.umamo.format.cmo3.model.gen.CLayerSelectorMap
import org.umamo.format.cmo3.model.gen.CLayeredImage
import org.umamo.format.cmo3.model.gen.CModelImageGroup
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.EnvValueSet
import org.umamo.format.cmo3.model.gen.FilterEnv
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.gen.LayerSet
import org.umamo.format.cmo3.model.gen.LayeredImageWrapper
import org.umamo.format.cmo3.model.gen.ModelImageFilterSet
import org.umamo.format.cmo3.model.identity.Id
import org.umamo.format.cmo3.model.type.CAffine
import org.umamo.format.cmo3.model.type.CRect
import org.umamo.format.cmo3.type.CArrayList
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.ArtSource
import org.umamo.runtime.model.ArtSourceLayer
import org.umamo.runtime.model.AtlasTile
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.lineageRoot
import org.umamo.runtime.model.storedToArtAffineForTile
import kotlin.math.roundToInt
/*
* The real-layer web of a RETAINED graph: what a CMO3-origin export writes for the art that changed
* since the import. A reload supersedes a tile with a new one (`<root>~n`) whose pixels reach the
* pages, while the layered image the editor decomposed at import still holds the layer as imported;
* a reload's added layer and an Add Artwork file mint tiles the graph has no model image for at all.
* This brings the layered-image tree, the model images, and their canvas placements to the edited
* model, with the same builders the fresh web uses, so the official editor's layered view shows the
* art the rigger sees and a reopened export re-imports against the file by key.
*
* Two jobs, both validated before anything is written:
* - a rewrite, for a reloaded tile whose lineage root has a model image: the layer that image
* composites takes the tile's pixels, rect, name, and visibility, and the image's canvas
* placement moves to the row's origin (a relink repoints the image at the row's layer first,
* minting the layer when the file never had it);
* - a mint, for a tile with no model image: a layer under its file's layered image (found by the
* source's guid, minted for a file the graph never held) in the folder its row names, and a
* model image over it.
* The entry and the drawables' region inputs are the atlas-web reconcile's, which runs over the maps
* this class extends.
*/
/**
* The retained-graph layer writer. Validation ([rewriteJobFor], [mintJobFor]) hands the reconcile a
* job per tile or null to decline whole; [apply] runs the jobs it was handed.
*
* @param Cmo3Model target The retained model, whose archive receives the pixels.
* @param CTextureManager textureManager The graph's texture manager.
* @param Cmo3GraphEditor editor The graph editor, for slots the retained document omitted.
* @param PuppetModel edited The session's model.
* @param Function tileRasters The document's pixels for a tile, or null.
* @param Long nowMillis The timestamp minted env values and wrappers record.
* @param Cmo3TextureFrames textureFrames The document's texture frames, taken before the export wrote.
*/
internal class Cmo3RetainedLayerWeb(
private val target: Cmo3Model,
private val textureManager: CTextureManager,
private val editor: Cmo3GraphEditor,
private val edited: PuppetModel,
private val tileRasters: (AtlasTileId) -> RasterImage?,
private val nowMillis: Long,
private val textureFrames: Cmo3TextureFrames,
) {
/**
* The art a job writes: the tile, its file and inventory row, and its pixels.
*
* @property String tileId The tile's lineage root - the key the atlas web tracks.
* @property AtlasTile tile The edited tile.
* @property ArtSource source The file the tile is bound to.
* @property ArtSourceLayer row The inventory row the binding names.
* @property RasterImage raster The tile's pixels, straight alpha.
* @property FloatArray canvasAffine The model image's canvas placement: a pure translation to
* the row's origin, as a six-float affine.
*/
internal open class Job(
val tileId: String,
val tile: AtlasTile,
val source: ArtSource,
val row: ArtSourceLayer,
val raster: RasterImage,
) {
val canvasAffine: FloatArray = floatArrayOf(1f, 0f, row.left.toFloat(), 0f, 1f, row.top.toFloat())
}
/**
* A reloaded tile whose lineage root's model image is rewritten to the tile's art.
*
* @property CModelImage modelImage The root's model image.
* @property SoleLayerInput sole The one layer input the image composites today.
* @property CImageResource filtered The image's filtered resource, which holds an archive entry.
*/
internal class RewriteJob(
tileId: String,
tile: AtlasTile,
source: ArtSource,
row: ArtSourceLayer,
raster: RasterImage,
val modelImage: CModelImage,
val sole: SoleLayerInput,
val filtered: CImageResource,
) : Job(tileId, tile, source, row, raster)
/** A tile with no model image, whose whole layer web is minted. */
internal class MintJob(
tileId: String,
tile: AtlasTile,
source: ArtSource,
row: ArtSourceLayer,
raster: RasterImage,
) : Job(tileId, tile, source, row, raster)
/**
* What [apply] added to the web, for the reconcile's maps.
*
* @property Map modelImageByTileId The model image of every minted tile, by lineage root.
* @property Boolean releasedCopy True when a rewrite left a reduced cache copy unreferenced and
* removed its pixels, so the shared pool needs a prune.
*/
internal class Applied(val modelImageByTileId: Map<String, CModelImage>, val releasedCopy: Boolean = false)
/** Set once a rewrite removes a reduced copy nothing samples any more. */
private var releasedCopy = false
/** The edited drawables by raw id, for the coordinates a retargeted drawable stores. */
private val editedDrawableById by lazy { edited.drawables.associateBy { drawable -> drawable.id.raw } }
private val sourceById = edited.sources.associateBy { source -> source.id }
/** Whether the graph carries the two lists a new file's web is added to. */
private val canMintFiles: Boolean =
mutableGraphListOf(textureManager._rawImages) != null && mutableGraphListOf(textureManager._modelImageGroups) != null
/**
* The names object every mint threads, built on first use: the archive's own path sequences, and
* the filter definitions of a model image the graph already holds (fresh ones when it holds none,
* or one another writer shaped differently).
*/
private val names: Cmo3ImageChainBuilder.Cmo3FreshChainNames by lazy { namesFor() }
/** The PNG entries the shared builders collected since the last [embedPending]. */
private val pendingEntries = ArrayList<Cmo3FreshFile.PngEntry>()
/**
* Embeds every collected entry in the archive. Called after each builder call, so the local path
* sequences and the archive never disagree about what is taken.
*/
private fun embedPending() {
for (entry in pendingEntries) {
target.addPng(entry.path, entry.pngBytes)
}
pendingEntries.clear()
}
/**
* The art a tile carries, when its binding names a listed file's row and the document holds its
* pixels; null otherwise.
*
* @param AtlasTile tile The edited tile.
* @return Job? The art, as a plain job.
*/
private fun artOf(tile: AtlasTile): Job? {
val ref = tile.source ?: return null
val source = sourceById[ref.sourceId] ?: return null
val row = source.layers.firstOrNull { candidate -> candidate.key == ref.layerKey } ?: return null
val raster = tileRasters(tile.id) ?: return null
return Job(tile.id.lineageRoot.raw, tile, source, row, raster)
}
/**
* The rewrite job for a reloaded tile, or null when the graph cannot take it: no pixels or no row
* for the tile, a model image that composites anything but exactly one layer, or a filtered
* resource with no archive entry to replace.
*
* @param AtlasTile tile The edited tile, a reloaded one.
* @param CModelImage modelImage Its lineage root's model image.
* @return RewriteJob? The job, or null.
*/
fun rewriteJobFor(tile: AtlasTile, modelImage: CModelImage): RewriteJob? {
val art = artOf(tile) ?: return null
val sole = soleLayerInputOf(modelImage) ?: return null
if (sole.input.layer !is CLayer) {
return null
}
// CMO3: CModelImage field _filteredImage - the composite the editor shows; for a single layer
// at identity it is the layer's own pixels, so it takes the new raster too.
val filtered = modelImage._filteredImage as? CImageResource ?: return null
if (filtered.imageFileBuf?.archivePath == null) {
return null
}
if (art.source.id.raw != sole.imageGuid && !canMintFiles) {
// A relink into a file the graph never held needs the file's web minted.
return null
}
return RewriteJob(art.tileId, tile, art.source, art.row, art.raster, modelImage, sole, filtered)
}
/**
* The mint job for a tile with no model image, or null when the tile has no pixels or no row, or
* the graph has no lists to add a file's web to.
*
* @param AtlasTile tile The edited tile.
* @return MintJob? The job, or null.
*/
fun mintJobFor(tile: AtlasTile): MintJob? {
val art = artOf(tile) ?: return null
if (!canMintFiles) {
return null
}
return MintJob(art.tileId, tile, art.source, art.row, art.raster)
}
/**
* One retained or minted layered image with the lists a layer is added through.
*
* @property CLayeredImage image The layered image.
* @property CModelImageGroup group Its model-image group.
* @param Function entryListOf The flat entry list every group and layer joins, resolved
* on first use so a rewrite that adds nothing never creates
* a list the file omitted.
*/
private class ImageSite(
val image: CLayeredImage,
val group: CModelImageGroup,
entryListOf: () -> MutableList<Any?>,
) {
/** The flat entry list every group and layer joins. */
val layerEntryList: MutableList<Any?> by lazy(entryListOf)
/** The folder at each slash-joined path found or minted so far. */
val folderByPath = HashMap<String, CLayerGroup>()
/** The layer minted for each binding key so far, so a second tile on one key shares it. */
val mintedLayerByKey = HashMap<String, CLayer>()
}
/**
* Runs the jobs: every rewrite, then every mint, sharing one set of file sites so two jobs on one
* file mint its web once. Every pixel entry is embedded as its job completes.
*
* @param List rewrites The rewrite jobs.
* @param List mints The mint jobs.
* @return Applied The minted model images.
*/
fun apply(rewrites: List<RewriteJob>, mints: List<MintJob>): Applied {
if (rewrites.isEmpty() && mints.isEmpty()) {
return Applied(emptyMap())
}
val siteBySourceId = HashMap<String, ImageSite>()
val modelImageByTileId = HashMap<String, CModelImage>()
for (job in rewrites) {
rewrite(job, siteBySourceId)
}
for (job in mints) {
modelImageByTileId[job.tileId] = mint(job, siteBySourceId)
}
return Applied(modelImageByTileId, releasedCopy)
}
/**
* A drawable's own icons over its texture patch, embedded now.
*
* @param RasterImage raster The art the drawable samples, in its own frame.
* @param FloatArray? artUvs The drawable's texture coordinates in that frame, or null for the whole art.
* @return Pair The 32px and 16px icons.
*/
fun drawableIcons(raster: RasterImage, artUvs: FloatArray?): Pair<CImageIcon, CImageIcon> {
val patch = Cmo3Icons.patchOf(raster, artUvs)
val icon32 = Cmo3Icons.iconOf(patch, 32, names.nextIconPath(), pendingEntries)
val icon16 = Cmo3Icons.iconOf(patch, 16, names.nextIconPath(), pendingEntries)
embedPending()
return icon32 to icon16
}
/**
* Re-renders a file-side drawable's icons over its (changed) art, in place where the icons have
* entries and minted with their slots recorded where the file carried none.
*
* @param CArtMeshSource mesh The drawable source.
* @param RasterImage raster The art it samples, in its own frame.
* @param FloatArray? artUvs Its texture coordinates in that frame, or null for the whole art.
*/
fun replaceDrawableIcons(mesh: CArtMeshSource, raster: RasterImage, artUvs: FloatArray?) {
val patch = Cmo3Icons.patchOf(raster, artUvs)
// CMO3: ACDrawableSource fields icon32 / icon16, in that order after invertClippingMask.
refreshIcon(mesh.icon32, patch, 32) { icon ->
mesh.icon32 = icon
editor.ensureChildSlot(mesh, "ACDrawableSource", "icon32", "icon16")
}
refreshIcon(mesh.icon16, patch, 16) { icon ->
mesh.icon16 = icon
editor.ensureChildSlot(mesh, "ACDrawableSource", "icon16")
}
}
/**
* Writes the model's three icons as fits of [thumbnail], in place where they have entries and
* minted with their slots recorded where the file carried none.
*
* @param CModelSource modelSource The model root.
* @param RasterImage thumbnail The model's rest-pose thumbnail.
*/
fun replaceModelIcons(modelSource: CModelSource, thumbnail: RasterImage) {
// CMO3: CModelSource fields _icon64 / _icon32 / _icon16, in that order before gameMotionSet.
refreshIcon(modelSource._icon64, thumbnail, 64) { icon ->
modelSource._icon64 = icon
editor.ensureChildSlot(modelSource, "CModelSource", "_icon64", "_icon32")
}
refreshIcon(modelSource._icon32, thumbnail, 32) { icon ->
modelSource._icon32 = icon
editor.ensureChildSlot(modelSource, "CModelSource", "_icon32", "_icon16")
}
refreshIcon(modelSource._icon16, thumbnail, 16) { icon ->
modelSource._icon16 = icon
editor.ensureChildSlot(modelSource, "CModelSource", "_icon16", "gameMotionSet")
}
}
/**
* Re-renders one icon slot: the existing entry's bytes are replaced when the slot names one the
* archive holds, else a fresh icon is minted and handed to [assign] to set and record its slot.
*
* @param Any? current The slot's icon today.
* @param RasterImage raster The art to fit.
* @param Int size The square's edge.
* @param Function assign Sets a minted icon on its owner and records the slot.
*/
private fun refreshIcon(current: Any?, raster: RasterImage, size: Int, assign: (CImageIcon) -> Unit) {
val path = Cmo3Icons.archivePathOf(current)
if (path != null && target.archive.byPath(path) != null) {
target.replacePng(path, Cmo3Icons.iconPngOf(raster, size))
(current as CImageIcon).image.let { image ->
if (image is CWritableImage) {
image.width = size
image.height = size
}
}
return
}
assign(Cmo3Icons.iconOf(raster, size, names.nextIconPath(), pendingEntries))
embedPending()
}
/**
* Re-renders a rewritten layer's icons over its new art.
*
* @param CLayer layer The layer.
* @param RasterImage raster Its new pixels.
*/
private fun replaceLayerIcons(layer: CLayer, raster: RasterImage) {
// CMO3: CLayer fields icon16 / icon64, in that order before layerInfo.
refreshIcon(layer.icon16, raster, 16) { icon ->
layer.icon16 = icon
editor.ensureChildSlot(layer, "CLayer", "icon16", "icon64")
}
refreshIcon(layer.icon64, raster, 64) { icon ->
layer.icon64 = icon
editor.ensureChildSlot(layer, "CLayer", "icon64", "layerInfo")
}
}
/**
* Re-renders a rewritten model image's icon over its new art.
*
* @param CModelImage modelImage The model image.
* @param RasterImage raster Its new pixels.
*/
private fun replaceModelImageIcon(modelImage: CModelImage, raster: RasterImage) {
// CMO3: CModelImage field icon16, before _materialLocalToCanvasTransform.
refreshIcon(modelImage.icon16, raster, 16) { icon ->
modelImage.icon16 = icon
editor.ensureChildSlot(modelImage, "CModelImage", "icon16", "_materialLocalToCanvasTransform")
}
}
/**
* The names object a minted web threads: the archive's own path sequences, and the filter
* definitions of a model image the graph already holds (fresh ones when it holds none, or one
* another writer shaped differently).
*
* @return Cmo3FreshChainNames The names.
*/
private fun namesFor(): Cmo3ImageChainBuilder.Cmo3FreshChainNames {
val retainedFilterSet =
Cmo3Import.elementsOf(textureManager._modelImageGroups)
.filterIsInstance<CModelImageGroup>()
.flatMap { group -> Cmo3Import.elementsOf(group._modelImages).filterIsInstance<CModelImage>() }
.firstNotNullOfOrNull { modelImage -> modelImage.inputFilter as? ModelImageFilterSet }
val filters =
retainedFilterSet?.let { filterSet -> Cmo3ImageChainBuilder.FilterCommons.fromFilterSet(filterSet) }
?: Cmo3ImageChainBuilder.FilterCommons.fresh()
val bufferPaths = Cmo3ImageChainBuilder.FreshPathSequence.continuingFrom("imageFileBuf", target.nextImageFileBufPath())
val iconPaths = Cmo3ImageChainBuilder.FreshPathSequence.continuingFrom("image", target.nextImagePath())
return Cmo3ImageChainBuilder.Cmo3FreshChainNames(filters, bufferPaths::next, iconPaths::next)
}
/**
* Rewrites a reloaded tile's model image to the tile's art: the row's layer (the composited one
* when the binding did not move, else found by key in the row's file or minted) takes the pixels,
* rect, name, and visibility; the image's placement, name, and cache follow.
*
* @param RewriteJob job The job.
* @param MutableMap siteBySourceId The file sites found or minted so far.
*/
private fun rewrite(job: RewriteJob, siteBySourceId: MutableMap<String, ImageSite>) {
val modelImage = job.modelImage
val compositedLayer = job.sole.input.layer as CLayer
val sourceGuid = job.source.id.raw
val site = siteFor(job.source, siteBySourceId)
// The layer the row names: the composited one when the tile was reloaded in place, which is
// the common case and touches no selector; otherwise the relink's target, repointed to below.
val sameFile = sourceGuid == job.sole.imageGuid
val compositedKey = walkLayeredImage(site.image).firstOrNull { walked -> walked.layer === compositedLayer }?.key
val layer =
if (sameFile && compositedKey == job.row.key) {
compositedLayer
} else {
layerFor(site, job.row, job.raster)
}
val pngBytes = PngCodec.write(job.raster)
writeLayer(layer, job.row, job.raster, pngBytes)
replaceLayerIcons(layer, job.raster)
// CMO3: CModelImage field _filteredImage - replaced in place when it is a resource of its own
// rather than the layer's (the fresh web shares one instance; an editor import may not).
val filtered = job.filtered
if (filtered !== layer.imageResource) {
if (filtered.imageFileBuf?.archivePath != null) {
target.replaceLayerPng(filtered, pngBytes)
}
filtered.width = job.raster.width
filtered.height = job.raster.height
}
if (layer !== compositedLayer) {
// CMO3: CLayerInputData field layer - the selector's target, repointed at the row's layer.
job.sole.input.layer = layer
if (!sameFile) {
repointImage(modelImage, job.sole, site.image)
}
}
// CMO3: CModelImage fields name / _materialLocalToCanvasTransform / cachedImageManager - the
// tile's name, the row's origin as a pure translation, and a cache over the new dimensions.
modelImage.name = job.tile.name
val placement = modelImage._materialLocalToCanvasTransform as? CAffine
if (placement == null) {
modelImage._materialLocalToCanvasTransform = Cmo3SourceLayerWeb.layerPlacement(job.row.left, job.row.top)
editor.ensureChildSlot(modelImage, "CModelImage", "_materialLocalToCanvasTransform", "_group")
} else {
placement.setFromAffineArray(job.canvasAffine)
}
modelImage.cachedImageManager = Cmo3ImageChainBuilder.paddedCacheManager(filtered, job.raster.width, job.raster.height)
retargetDrawablesOnto(modelImage, filtered, job.raster.width, job.raster.height)
replaceModelImageIcon(modelImage, job.raster)
embedPending()
}
/**
* Brings every drawable shown from a rewritten model image onto its new raster: the reduced cache copy
* the editor made of the old art no longer shows the art, and a texture over the raster must carry the
* new size's cache scale.
*
* Each texture over the image (its raster, or its copy as the graph was read) samples the raster with
* the scale and mip level the editor writes for one, shared textures once. A drawable whose stored
* coordinates now mean something else - it moved off a copy, or it stores the cache frame and the scale
* changed - stores the edited model's coordinates afresh; every other drawable's are left to the
* property pass. A copy nothing samples any more has its pixels removed, and the pool prune drops it.
*
* @param CModelImage modelImage The rewritten model image.
* @param CImageResource raster Its raster, holding the new art.
* @param Int width The new art's width in pixels.
* @param Int height The new art's height in pixels.
*/
private fun retargetDrawablesOnto(modelImage: CModelImage, raster: CImageResource, width: Int, height: Int) {
val modelSource = target.root as? CModelSource ?: return
// CMO3: CModelSource field drawableSourceSet -> CDrawableSourceSet field _sources.
val drawableSources = Cmo3Import.elementsOf((modelSource.drawableSourceSet as? CDrawableSourceSet)?._sources).filterIsInstance<CArtMeshSource>()
val shownFromImage = drawableSources.filter { source -> textureFrames.isShownFrom(source, modelImage) }
if (shownFromImage.isEmpty()) {
return
}
// The frames as they are before any texture moves: shared textures make a later read stale.
val frameBefore = shownFromImage.associateWith { source -> textureFrames.storedFrameOf(source) }
val scaleBefore = shownFromImage.associateWith { source -> affineValuesOf((source.texture as? GTexture2D)?.transformImageResource01toLogical01) }
val releasedCopies = HashSet<CImageResource>()
val retargeted = HashSet<GTexture2D>()
for (source in shownFromImage) {
val texture = source.texture as? GTexture2D ?: continue
if (!retargeted.add(texture)) {
continue
}
(texture.srcImageResource as? CImageResource)?.takeIf { sampled -> textureFrames.isReducedCopy(sampled) }?.let(releasedCopies::add)
// CMO3: GTexture2D fields srcImageResource / transformImageResource01toLogical01 / mipmapLevel -
// the raster, its cache scale, and the full-resolution level, as every corpus texture over a
// model image's raster writes them.
texture.srcImageResource = raster
texture.transformImageResource01toLogical01 = Cmo3ImageChainBuilder.paddedFrameAffine(width, height)
texture.mipmapLevel = Cmo3ImageChainBuilder.FULL_RESOLUTION_MIPMAP_LEVEL
editor.ensureChildSlot(texture, "GTexture2D", "transformImageResource01toLogical01", "mipmapLevel")
editor.ensureChildSlot(texture, "GTexture2D", "mipmapLevel", "isPremultiplied")
}
for (source in shownFromImage) {
val frameNow = textureFrames.storedFrameOf(source)
val scaleNow = affineValuesOf((source.texture as? GTexture2D)?.transformImageResource01toLogical01)
val meaningChanged = frameNow != frameBefore[source] || (frameNow == Cmo3StoredFrame.Cache && !scaleNow.contentEquals(scaleBefore[source]))
if (!meaningChanged) {
continue
}
val drawableId = (source.id as? Id)?.idstr ?: continue
val editedDrawable = editedDrawableById[drawableId] ?: continue
val editedUvs = editedDrawable.mesh?.uvs ?: continue
val storedToArt = editedDrawable.atlasTileId?.let { tileId -> edited.atlas.storedToArtAffineForTile(tileId) }
// CMO3: CArtMeshSource field uvs.
source.uvs = textureFrames.storedUvsOf(source, editedUvs, storedToArt)
editor.ensureChildSlot(source, "CArtMeshSource", "uvs", "texture")
}
for (copy in releasedCopies) {
val stillSampled = drawableSources.any { source -> (source.texture as? GTexture2D)?.srcImageResource === copy }
if (stillSampled) {
continue
}
if (copy.imageFileBuf?.archivePath != null) {
target.removeLayerPng(copy)
}
releasedCopy = true
}
}
/**
* A CMO3 affine's six values, identity for none, so two can be compared.
*
* @param Any? affine The field value.
* @return FloatArray The values, m00 m01 m02 m10 m11 m12.
*/
private fun affineValuesOf(affine: Any?): FloatArray {
val values = affine as? CAffine ?: return floatArrayOf(1f, 0f, 0f, 0f, 1f, 0f)
return floatArrayOf(values.m00, values.m01, values.m02, values.m10, values.m11, values.m12)
}
/**
* Moves a model image to another file: the selector map's key, the current-image env value, and
* the linked-image list all name the new layered image.
*
* @param CModelImage modelImage The model image.
* @param SoleLayerInput sole Its one layer input, already repointed at the new file's layer.
* @param CLayeredImage image The new file's layered image.
*/
private fun repointImage(modelImage: CModelImage, sole: SoleLayerInput, image: CLayeredImage) {
// CMO3: ModelImageFilterEnv field envValues -> EnvValueSet field value: the CLayerSelectorMap's
// _imageToLayerInput keyed by image guid, and the current-image guid value beside it.
val filterEnv = modelImage.inputFilterEnv as? FilterEnv ?: return
for (valueSet in Cmo3Import.elementsOf(filterEnv.envValues).filterIsInstance<EnvValueSet>()) {
val selectorMap = valueSet.value as? CLayerSelectorMap
if (selectorMap != null) {
selectorMap._imageToLayerInput = LinkedHashMap<Any?, Any?>().apply { put(image.guid, ArrayList<Any?>(mutableListOf(sole.input))) }
valueSet.updateTimeMs = nowMillis
} else if (Cmo3Import.uuidOf(valueSet.value) == sole.imageGuid) {
valueSet.value = image.guid
valueSet.updateTimeMs = nowMillis
}
}
// CMO3: CModelImage field linkedRawImageGuids.
modelImage.linkedRawImageGuids = CArrayList<Any?>(mutableListOf(image.guid))
}
/**
* Writes a tile's art into a layer: the archive entry, the resource dimensions, the rect at the
* row's origin, and the row's name and visibility.
*
* @param CLayer layer The layer.
* @param ArtSourceLayer row The inventory row.
* @param RasterImage raster The pixels.
* @param ByteArray pngBytes The pixels, encoded.
*/
private fun writeLayer(layer: CLayer, row: ArtSourceLayer, raster: RasterImage, pngBytes: ByteArray) {
val resource = layer.imageResource as? CImageResource
if (resource != null && resource.imageFileBuf?.archivePath != null) {
target.replaceLayerPng(resource, pngBytes)
// CMO3: CImageResource fields width / height - corpus-verified to equal the decoded PNG's.
resource.width = raster.width
resource.height = raster.height
}
// CMO3: CLayer field boundsOnImageDoc, written into the existing rect when there is one.
val bounds = layer.boundsOnImageDoc as? CRect
if (bounds == null) {
layer.boundsOnImageDoc = Cmo3SourceLayerWeb.layerBounds(row.left, row.top, raster.width, raster.height)
editor.ensureChildSlot(layer, "CLayer", "boundsOnImageDoc", "layerIdentifier")
} else {
bounds.x = row.left
bounds.y = row.top
bounds.width = raster.width
bounds.height = raster.height
}
// CMO3: ACLayerEntry fields name / isVisible - as the file reads today.
layer.name = row.name
layer.isVisible = row.visible
}
/**
* Mints a tile's layer web: the layer under its file in the row's folder, and a model image over
* it at the row's origin.
*
* @param MintJob job The job.
* @param MutableMap siteBySourceId The file sites found or minted so far.
* @return CModelImage The minted model image.
*/
private fun mint(job: MintJob, siteBySourceId: MutableMap<String, ImageSite>): CModelImage {
val site = siteFor(job.source, siteBySourceId)
val layer = layerFor(site, job.row, job.raster)
// A second tile on one key (a double binding) shares the layer the first minted, pixels
// included, since a model image composites its layer's own resource; only the model image is
// its own.
val resource = layer.imageResource as CImageResource
val modelImage =
Cmo3ImageChainBuilder.modelImageOver(
job.tile.name,
site.image,
layer,
resource,
job.raster,
Cmo3SourceLayerWeb.layerPlacement(job.row.left, job.row.top),
site.group,
names,
pendingEntries,
nowMillis,
)
checkNotNull(mutableGraphListOf(site.group._modelImages)) { "a site's group has a model-image list" }.add(modelImage)
embedPending()
return modelImage
}
/**
* The file's site: its retained layered image and group (the group minted when the image has
* none), or a whole minted web for a file the graph never held.
*
* @param ArtSource source The file.
* @param MutableMap siteBySourceId The sites so far.
* @return ImageSite The site.
*/
private fun siteFor(source: ArtSource, siteBySourceId: MutableMap<String, ImageSite>): ImageSite {
siteBySourceId[source.id.raw]?.let { existing -> return existing }
val rawImages = checkNotNull(mutableGraphListOf(textureManager._rawImages)) { "validated: the raw-image list exists" }
val groups = checkNotNull(mutableGraphListOf(textureManager._modelImageGroups)) { "validated: the group list exists" }
// CMO3: CTextureManager field _rawImages -> LayeredImageWrapper field image -> CLayeredImage
// field guid - the source id a CMO3-origin document carries.
val retainedImage =
rawImages.firstNotNullOfOrNull { wrapper ->
((wrapper as? LayeredImageWrapper)?.image as? CLayeredImage)?.takeIf { image -> Cmo3Import.uuidOf(image.guid) == source.id.raw }
}
val site =
if (retainedImage != null) {
// CMO3: CModelImageGroup field _linkedRawImageGuids - the group a file's images live in.
val retainedGroup =
groups.filterIsInstance<CModelImageGroup>().firstOrNull { group ->
Cmo3Import.elementsOf(group._linkedRawImageGuids).any { guid -> Cmo3Import.uuidOf(guid) == source.id.raw } &&
mutableGraphListOf(group._modelImages) != null
}
val group =
retainedGroup
?: Cmo3SourceLayerWeb.mintModelImageGroup(source.name, retainedImage).also { minted -> groups.add(minted) }
ImageSite(retainedImage, group) { layerEntryListOf(retainedImage) }
} else {
val canvasWidth = edited.canvasWidth.roundToInt()
val canvasHeight = edited.canvasHeight.roundToInt()
val minted = Cmo3SourceLayerWeb.mintLayeredImage(source.name, source.path, source.lastModified, canvasWidth, canvasHeight, names, nowMillis)
rawImages.add(minted.wrapper)
val group = Cmo3SourceLayerWeb.mintModelImageGroup(source.name, minted.image)
groups.add(group)
ImageSite(minted.image, group) { minted.layerEntryList }.also { site -> site.folderByPath[""] = minted.rootGroup }
}
siteBySourceId[source.id.raw] = site
return site
}
/**
* A retained image's flat entry list, created (with its slot recorded) when the file omitted it.
*
* @param CLayeredImage image The layered image.
* @return MutableList The list.
*/
private fun layerEntryListOf(image: CLayeredImage): MutableList<Any?> {
// CMO3: CLayeredImage field layerSet -> LayerSet field _layerEntryList.
val layerSet =
image.layerSet as? LayerSet
?: LayerSet().also { created ->
created._layeredImage = image
image.layerSet = created
editor.ensureChildSlot(image, "CLayeredImage", "layerSet")
}
return mutableGraphListOf(layerSet._layerEntryList)
?: CArrayList<Any?>().also { created ->
layerSet._layerEntryList = created
editor.ensureChildSlot(layerSet, "LayerSet", "_layerEntryList")
}
}
/**
* The row's layer in a site: one minted this pass for the same key, else the file's own layer
* under that key, else a fresh layer with the tile's pixels in the row's folder.
*
* @param ImageSite site The file's site.
* @param ArtSourceLayer row The inventory row.
* @param RasterImage raster The pixels a minted layer takes.
* @return CLayer The layer.
*/
private fun layerFor(site: ImageSite, row: ArtSourceLayer, raster: RasterImage): CLayer {
site.mintedLayerByKey[row.key]?.let { minted -> return minted }
walkLayeredImage(site.image).firstOrNull { walked -> walked.key == row.key }?.let { walked -> return walked.layer }
val folder = folderAt(site, row.groupPath)
val pngBytes = PngCodec.write(raster)
val path = names.nextImageFileBufPath()
pendingEntries.add(Cmo3FreshFile.PngEntry(path, pngBytes))
val resource = Cmo3SourceLayerWeb.layerResource(path, raster, pngBytes.size)
val layer =
Cmo3SourceLayerWeb.layerOver(
name = row.name,
layerKey = row.key,
visible = row.visible,
canvasLeft = row.left,
canvasTop = row.top,
resource = resource,
raster = raster,
layeredImage = site.image,
folder = folder,
names = names,
pngEntries = pendingEntries,
)
childrenOf(folder).add(layer)
site.layerEntryList.add(layer)
site.mintedLayerByKey[row.key] = layer
embedPending()
return layer
}
/**
* The folder at a slash-joined path in a site's tree, walking the retained groups by name and
* minting each missing segment under its parent.
*
* @param ImageSite site The file's site.
* @param String path The folder path, "" for the root.
* @return CLayerGroup The folder.
*/
private fun folderAt(site: ImageSite, path: String): CLayerGroup {
site.folderByPath[path]?.let { known -> return known }
if (path.isEmpty()) {
// CMO3: CLayeredImage field _rootLayer - the tree's root group.
val root =
site.image._rootLayer as? CLayerGroup
?: Cmo3SourceLayerWeb.layerGroup("root", site.image, CArrayList(), names).also { minted ->
site.image._rootLayer = minted
editor.ensureChildSlot(site.image, "CLayeredImage", "_rootLayer", "layerSet")
site.layerEntryList.add(0, minted)
}
site.folderByPath[""] = root
return root
}
val parent = folderAt(site, path.substringBeforeLast('/', ""))
val name = path.substringAfterLast('/')
val siblings = childrenOf(parent)
// CMO3: ACLayerEntry field name - a folder is found by its own name under its parent.
val folder =
siblings.filterIsInstance<CLayerGroup>().firstOrNull { group -> group.name == name }
?: Cmo3SourceLayerWeb.layerGroup(name, site.image, CArrayList(), names).also { minted ->
siblings.add(minted)
site.layerEntryList.add(minted)
}
site.folderByPath[path] = folder
return folder
}
/**
* A group's child list, created (with its slot recorded) when the file omitted it.
*
* @param ACLayerGroup group The group.
* @return MutableList The list.
*/
private fun childrenOf(group: ACLayerGroup): MutableList<Any?> =
// CMO3: ACLayerGroup field _children.
mutableGraphListOf(group._children)
?: CArrayList<Any?>().also { created ->
group._children = created
editor.ensureChildSlot(group, "ACLayerGroup", "_children")
}
}
@@ -0,0 +1,349 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CLabelColor
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CAffecterSourceSet
import org.umamo.format.cmo3.model.gen.CArtPathBrushSetting
import org.umamo.format.cmo3.model.gen.CDeformerSourceSet
import org.umamo.format.cmo3.model.gen.CDrawableSourceSet
import org.umamo.format.cmo3.model.gen.CEffectParameterGroups
import org.umamo.format.cmo3.model.gen.CGameMotionSet
import org.umamo.format.cmo3.model.gen.CGuidesSetting
import org.umamo.format.cmo3.model.gen.CImageCanvas
import org.umamo.format.cmo3.model.gen.CLabelColorType
import org.umamo.format.cmo3.model.gen.CModelInfo
import org.umamo.format.cmo3.model.gen.CParameterGroup
import org.umamo.format.cmo3.model.gen.CParameterGroupSet
import org.umamo.format.cmo3.model.gen.CParameterSourceSet
import org.umamo.format.cmo3.model.gen.CPartForm
import org.umamo.format.cmo3.model.gen.CPartSource
import org.umamo.format.cmo3.model.gen.CPartSourceSet
import org.umamo.format.cmo3.model.gen.CPhysicsSettingsSourceSet
import org.umamo.format.cmo3.model.gen.CPoint
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.EditorEdition
import org.umamo.format.cmo3.model.gen.KeyformGridAccessKey
import org.umamo.format.cmo3.model.gen.KeyformGridSource
import org.umamo.format.cmo3.model.gen.KeyformOnGrid
import org.umamo.format.cmo3.model.gen.ModelViewerSetting
import org.umamo.format.cmo3.model.gen.TextureImageGroup
import org.umamo.format.cmo3.model.identity.Guid
import org.umamo.format.cmo3.model.identity.Id
import org.umamo.format.cmo3.model.type.CColor
import org.umamo.format.cmo3.type.CArrayList
import org.umamo.format.cmo3.type.CHashMap
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
/**
* Builds the blank CModelSource spine a fresh (never-read) CMO3 starts from, mirroring what the
* official editor writes for New -> Save As (BareMinimum.cmo3; docs/format/CMO3.md §3 The
* Blank-Model Skeleton). Everything content-bearing - parameters, parts, deformers, drawables,
* glues, the image chain - is deliberately absent: the reconcile exporter creates the model's own
* entities against this skeleton, and the image-chain builder populates the texture manager.
*
* Fields the modern editor always writes as explicit defaults (useOffscreen=false,
* invertClippingMask=false, an explicit null internalColor_direct_argb) emit on fresh objects
* too - their DontSerializeIfDefault annotations are hand-removed in the generated model, because
* the official reader's custom deserializers reject their absence.
*
* ERA NOTE, unresolved: seeding from BareMinimum means a fresh graph declares fileFormatVersion
* 504000000 (Cubism 5.4) even though a MOC3-origin conversion populates nothing 5.x and its
* targetVersionNo says SDK 4.0. Both files that are known to RENDER for the same model - Cubism's
* own golden (402030000) and a third-party converter's output (401030000) - are 4.x. The standing
* theory for the MOC3-origin render gap (see [Cmo3Conversion]) is that the 5.4 reader composites
* through the model-image web, so a merely shape-correct synthetic web is not enough, while a 4.x
* file draws straight from the atlas. Emitting an era-matched graph (4.x version PIs, dropping
* the 5.x-only fields) would test it; it was not pursued because the art-sourcing pipeline
* supersedes the whole synthetic path.
*/
internal object Cmo3SkeletonBuilder {
/**
* The root parameter group's well-known guid - identical across corpus files, never minted.
* CMO3: CParameterGroup rootParameterGroup guid (constant across eras; see CMO3.md §3).
*/
internal const val ROOT_PARAMETER_GROUP_UUID: String = "e9fe6eff-953b-4ce2-be7c-4a7c3913686b"
/** The synthetic root part's id string. CMO3: CPartSource rootPart, CPartId idstr. */
internal const val ROOT_PART_ID_STR: String = "__RootPart__"
/** The root parameter group's id string. CMO3: CParameterGroupId idstr. */
internal const val ROOT_PARAMETER_GROUP_ID_STR: String = "ParamGroupRoot"
/**
* The editor's root-deformer marker uuid.
*
* CMO3: CDeformerGuid uuid + note "ROOT" - the same fixed uuid in every corpus file, written
* as an affecter's or root-level deformer's targetDeformerGuid.
*/
internal const val ROOT_DEFORMER_SENTINEL_UUID: String = "71fae776-e218-4aee-873e-78e8ac0cb48a"
/**
* A fresh root-deformer sentinel guid (see ROOT_DEFORMER_SENTINEL_UUID).
*
* @return Guid The sentinel CDeformerGuid.
*/
internal fun rootDeformerSentinel(): Guid =
Guid("CDeformerGuid").apply {
uuid = ROOT_DEFORMER_SENTINEL_UUID
note = "ROOT"
}
/** One embedded PNG the skeleton's icons reference: the archive entry path plus its bytes. */
internal class IconEntry(val path: String, val pngBytes: ByteArray)
/** The built spine: the fresh root object plus the icon PNGs its CImageIcons reference. */
internal class BlankSkeleton(val root: CModelSource, val iconEntries: List<IconEntry>)
/**
* Builds the blank spine for a fresh document.
*
* @param String modelName The model's display name (CModelSource field name).
* @param Int canvasWidth The canvas width in pixels (CImageCanvas field pixelWidth).
* @param Int canvasHeight The canvas height in pixels (CImageCanvas field pixelHeight).
* @param Int targetVersionNo The persisted runtime target (CModelSource field targetVersionNo).
* @param RasterImage modelThumbnail The model's rest-pose thumbnail the three model icons fit, or
* null for the blank icons the editor writes for a model it never
* rendered (ModelWithOffscreenPartClipping carries exactly that).
* @return BlankSkeleton The fresh root plus icon PNG entries.
*/
internal fun buildBlank(
modelName: String,
canvasWidth: Int,
canvasHeight: Int,
targetVersionNo: Int,
modelThumbnail: RasterImage? = null,
): BlankSkeleton {
val rootPart = buildRootPart()
val rootGroup = buildRootParameterGroup()
// CMO3: CModelSource fields _icon64 / _icon32 / _icon16 - backed by image.png, image_0.png,
// image_1.png in the blank default, the model's rendered thumbnail at each size.
val iconPaths = listOf("image.png", "image_0.png", "image_1.png")
val icons =
Cmo3Icons.MODEL_ICON_SIZES.mapIndexed { sizeIndex, size ->
IconEntry(iconPaths[sizeIndex], if (modelThumbnail == null) blankPng(size) else Cmo3Icons.iconPngOf(modelThumbnail, size))
}
val root =
CModelSource().apply {
guid = freshGuid("CModelGuid")
name = modelName
// CMO3: CModelSource field editorEdition (BareMinimum writes edition 11).
editorEdition = EditorEdition().apply { edition = 11 }
canvas =
CImageCanvas().apply {
// CMO3: CImageCanvas fields pixelWidth/pixelHeight + empty CColor background.
pixelWidth = canvasWidth
pixelHeight = canvasHeight
background = CColor()
}
parameterSourceSet = CParameterSourceSet().apply { _sources = CArrayList<Any?>() }
textureManager =
CTextureManager().apply {
// CMO3: CTextureManager - mandatory even when empty (BareMinimum).
textureList = TextureImageGroup().apply { children = CArrayList<Any?>() }
_rawImages = CArrayList<Any?>()
_modelImageGroups = CArrayList<Any?>()
_textureAtlases = CArrayList<Any?>()
// CMO3: CTextureManager field isTextureInputModelImageMode - the blank 5.4 document's
// own value. A skeleton has no drawables, so the mode selects nothing; whoever
// populates the image chain writes the document's real one over this.
isTextureInputModelImageMode = true
previewReductionRatio = 1
artPathBrushUsingLayeredImageIds = CArrayList<Any?>()
}
useLegacyDrawOrder__testImpl = false
drawableSourceSet = CDrawableSourceSet().apply { _sources = CArrayList<Any?>() }
deformerSourceSet = CDeformerSourceSet().apply { _sources = CArrayList<Any?>() }
affecterSourceSet = CAffecterSourceSet().apply { _sources = CArrayList<Any?>() }
partSourceSet = CPartSourceSet().apply { _sources = CArrayList<Any?>(mutableListOf(rootPart)) }
physicsSettingsSourceSet =
CPhysicsSettingsSourceSet().apply {
_sourceCubismPhysics = CArrayList<Any?>()
// CMO3: CPhysicsSettingsSourceSet field settingFPS (BareMinimum writes 120).
settingFPS = 120
}
this.rootPart = rootPart
parameterGroupSet = CParameterGroupSet().apply { _groups = CArrayList<Any?>(mutableListOf(rootGroup)) }
rootParameterGroup = rootGroup
modelInfo =
CModelInfo().apply {
pixelsPerUnit = 1f
originInPixels = CPoint()
// CMO3: CEffectParameterGroups field _parameterGroups - a hash_map in every
// corpus file (keyType="string" when empty); the editor's field is Map-typed
// and rejects a list.
_effectParameterGroups = CEffectParameterGroups().apply { _parameterGroups = CHashMap<Any?, Any?>() }
}
modelOptions = CHashMap<String, Any?>()
_icon64 = Cmo3Icons.iconReferencing(64, icons[0].path)
_icon32 = Cmo3Icons.iconReferencing(32, icons[1].path)
_icon16 = Cmo3Icons.iconReferencing(16, icons[2].path)
gameMotionSet =
CGameMotionSet().apply {
gameMotions = CArrayList<Any?>()
gameMotionGroups = CArrayList<Any?>()
}
modelViewerSetting = ModelViewerSetting().apply { trackCursorSettings = ArrayList<Any?>() }
guides = CGuidesSetting().apply { guidesModeling = CArrayList<Any?>() }
this.targetVersionNo = targetVersionNo
// CMO3: CModelSource field latestVersionOfLastModelerNo (BareMinimum writes 5030000).
latestVersionOfLastModelerNo = 5030000
artPathBrushesSetting = CArtPathBrushSetting().apply { brushes = CArrayList<Any?>() }
// CMO3: CModelSource fields randomPoseSetting / motionSyncSettingsSet /
// modelStateSetSet - every 5.4 corpus file writes all three (empty when the
// features are unused), modelStateSetSet as the root's last child; its presence
// also drives the ModelStateSet:1 version PI.
randomPoseSetting =
org.umamo.format.cmo3.model.gen.CRandomPoseSettingManager().apply {
// CMO3: CRandomPoseSettingManager field _settings - array_list, unlike the
// carray_list sibling collections.
_settings = ArrayList<Any?>()
}
motionSyncSettingsSet =
org.umamo.format.cmo3.model.gen.CMotionSyncSettingSourceSet().apply {
_settingSourceSetMotionSync = LinkedHashSet<Any?>()
}
modelStateSetSet =
org.umamo.format.cmo3.model.gen.CModelStateSetSet().apply {
_modelStateSets = CArrayList<Any?>()
}
}
return BlankSkeleton(root, icons)
}
/**
* Builds the synthetic root part with its one-cell keyform grid (a single CPartForm at draw
* order 500, opacity 1), exactly the shape BareMinimum's __RootPart__ carries.
*
* @return CPartSource The fresh root part.
*/
private fun buildRootPart(): CPartSource {
val part = CPartSource()
val formGuid = freshGuid("CFormGuid")
val form =
CPartForm().apply {
guid = formGuid
_source = part
notes = ""
// CMO3: CPartForm fields drawOrder/opacity/multiplyColor/screenColor.
drawOrder = 500
opacity = 1f
multiplyColor = identityMultiplyColor()
screenColor = identityScreenColor()
}
return part.apply {
localName = "Root Part"
isVisible = true
keyformGridSource =
KeyformGridSource().apply {
keyformsOnGrid =
ArrayList<Any?>(
mutableListOf(
KeyformOnGrid().apply {
accessKey = KeyformGridAccessKey().apply { _keyOnParameterList = ArrayList<Any?>() }
keyformGuid = formGuid
},
),
)
keyformBindings = ArrayList<Any?>()
}
keyformMorphTargetSet = emptyMorphTargetSet()
_extensions = CArrayList<Any?>()
labelColor = undefinedLabelColor()
guid = freshGuid("CPartGuid")
id = Id("CPartId").apply { idstr = ROOT_PART_ID_STR }
keyforms = CArrayList<Any?>(mutableListOf(form))
defaultOrder_forEditor = 500
partsEditColor = CColor()
_childGuids = CArrayList<Any?>()
clipGuidList = CArrayList<Any?>()
colorComposition = org.umamo.format.cmo3.model.gen.ColorComposition.NORMAL
alphaComposition = org.umamo.format.cmo3.model.gen.AlphaComposition.OVER
}
}
/**
* Builds the root parameter group with its well-known constant guid.
*
* @return CParameterGroup The fresh root group.
*/
private fun buildRootParameterGroup(): CParameterGroup =
CParameterGroup().apply {
name = "Root Parameter Group"
description = ""
folderIsOpened = false
guid =
Guid("CParameterGroupGuid").apply {
uuid = ROOT_PARAMETER_GROUP_UUID
note = "Root Parameter Group"
}
_childGuids = CArrayList<Any?>()
id = Id("CParameterGroupId").apply { idstr = ROOT_PARAMETER_GROUP_ID_STR }
labelColor = undefinedLabelColor()
}
/**
* Mints a fresh guid of the given kind.
*
* @param String kind The typed guid tag (e.g. "CPartGuid").
* @return Guid The fresh guid.
*/
internal fun freshGuid(kind: String): Guid =
Guid(kind).apply {
uuid = java.util.UUID.randomUUID().toString()
note = "(no debug info)"
}
/**
* An empty morph-target set (empty targets + empty constraint set).
*
* @return Any The fresh KeyFormMorphTargetSet.
*/
internal fun emptyMorphTargetSet(): Any =
org.umamo.format.cmo3.model.gen.KeyFormMorphTargetSet().apply {
_morphTargets = CArrayList<Any?>()
blendWeightConstraintSet =
org.umamo.format.cmo3.model.gen.MorphTargetBlendWeightConstraintSet().apply { _constraints = CArrayList<Any?>() }
}
/**
* The identity multiply tint (white, opaque).
*
* @return CFloatColor The fresh color.
*/
internal fun identityMultiplyColor(): org.umamo.format.cmo3.model.custom.CFloatColor =
org.umamo.format.cmo3.model.custom.CFloatColor().apply {
red = 1f
green = 1f
blue = 1f
alpha = 1f
}
/**
* The identity screen tint (black, opaque).
*
* @return CFloatColor The fresh color.
*/
internal fun identityScreenColor(): org.umamo.format.cmo3.model.custom.CFloatColor =
org.umamo.format.cmo3.model.custom.CFloatColor().apply { alpha = 1f }
/**
* The default label color (uncustomized, UNDEFINED type).
*
* @return CLabelColor The fresh label color.
*/
internal fun undefinedLabelColor(): CLabelColor =
CLabelColor().apply {
// CMO3: CLabelColor attr customizedColorInt (-1 = none) + CLabelColorType labelType.
customizedColorInt = -1
labelType = CLabelColorType.UNDEFINED
}
/**
* A fully transparent square PNG for the model icons.
*
* @param Int size The square dimension in pixels.
* @return ByteArray The encoded PNG.
*/
internal fun blankPng(size: Int): ByteArray = PngCodec.write(RasterImage(size, size, ByteArray(size * size * 4)))
}
@@ -0,0 +1,518 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.custom.CImageResource
import org.umamo.format.cmo3.model.custom.CLayer
import org.umamo.format.cmo3.model.gen.CLayerGroup
import org.umamo.format.cmo3.model.gen.CLayerIdentifier
import org.umamo.format.cmo3.model.gen.CLayeredImage
import org.umamo.format.cmo3.model.gen.CModelImageGroup
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.GTexture2D
import org.umamo.format.cmo3.model.gen.GTransform2
import org.umamo.format.cmo3.model.gen.LayerSet
import org.umamo.format.cmo3.model.gen.LayeredImageWrapper
import org.umamo.format.cmo3.model.identity.Guid
import org.umamo.format.cmo3.model.type.CAffine
import org.umamo.format.cmo3.model.type.CRect
import org.umamo.format.cmo3.model.type.FileRef
import org.umamo.format.cmo3.type.CArrayList
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.AtlasTileId
import org.umamo.runtime.model.PuppetModel
import kotlin.math.roundToInt
/*
* The real-layer half of a fresh image chain: what an artwork-origin document (a PSD, CLIP, or KRA
* the bridge opened) writes in place of the crop stand-in. One CLayeredImage per artwork file with
* the file's folders as CLayerGroups and one CLayer per tile holding the document's own raster for
* it, one CModelImage per tile at the layer's canvas origin, an entry on the tile's page for every
* placed tile, and a binding for every drawable over it - the shape the official editor writes when
* it imports a PSD, so the file reopens in either editor with its real art and, through the Photoshop
* layer ids, re-imports against the PSD by key.
*/
/**
* The real-layer web writer. [inputsOf] routes a puppet's tiles into per-file inputs, and [write]
* mints one file's web into the texture manager the caller is populating.
*/
internal object Cmo3SourceLayerWeb {
/**
* One tile with real art, as the conversion routes it here.
*
* @property String tileId The tile's id.
* @property String name The layer's name, which is the tile's.
* @property String layerKey The binding key; a "lyid:<n>" key writes Photoshop's layer id.
* @property String groupPath The folder path in the file, "" at the root.
* @property Boolean visible The layer's visibility as last read.
* @property Int canvasLeft The art frame's canvas x - the inventory row's origin.
* @property Int canvasTop The art frame's canvas y.
* @property RasterImage raster The tile's pixels, straight alpha.
* @property AtlasPlacement? placement Where the tile sits on its page, or null when unpacked.
* @property List<String> drawableIds The drawables sampling the tile, in document order.
* @property Map artUvsByDrawableId Each drawable's texture coordinates in the tile's
* own frame, for the patch its icon shows; a drawable absent here shows the whole layer.
*/
internal class SourceLayerInput(
val tileId: String,
val name: String,
val layerKey: String,
val groupPath: String,
val visible: Boolean,
val canvasLeft: Int,
val canvasTop: Int,
val raster: RasterImage,
val placement: AtlasPlacement?,
val drawableIds: List<String>,
val artUvsByDrawableId: Map<String, FloatArray> = emptyMap(),
)
/**
* One artwork file with those of its tiles that have real art, in the file's layer order.
*
* @property String name The file's display name.
* @property String? path The file's recorded path, or null when the record has none.
* @property Long? lastModified The file's modification time as last read, or null.
* @property Int width The frame the layers' canvas coordinates live in.
* @property Int height Its height.
* @property List layers The tiles to write as layers.
*/
internal class SourceImageInput(
val name: String,
val path: String?,
val lastModified: Long?,
val width: Int,
val height: Int,
val layers: List<SourceLayerInput>,
)
/**
* What one file's web produced.
*
* @property LayeredImageWrapper wrapper The layered image, for the texture manager's raw-image list.
* @property CModelImageGroup group The file's model-image group.
* @property Map bindingByDrawableId The texture web of every drawable over a placed tile.
*/
internal class Written(
val wrapper: LayeredImageWrapper,
val group: CModelImageGroup,
val bindingByDrawableId: Map<String, Cmo3DrawableTextureBinding>,
)
/**
* Routes [puppet]'s tiles into per-file inputs: every tile bound to a listed file whose binding
* names an inventory row (present or lost - its tile still holds the art) and for which
* [tileRasters] has pixels, in the file's inventory order. A tile nothing samples is still a
* layer of its file; a tile with no row or no raster is left to the crop path.
*
* The layered image's frame is the document canvas: an import sets the canvas from the art, and
* the inventory's canvas coordinates live in that frame - a later file's rows already carry the
* offset it was placed by (ArtSource.offsetX), so they are written as they are. The CMO3 keeps
* no such offset of its own, so a document reopened from the export reads every file at offset 0.
*
* @param PuppetModel puppet The model being converted.
* @param Function tileRasters The document's pixels for a tile, or null.
* @return List<SourceImageInput> One input per file with at least one real tile, in the model's source order.
*/
internal fun inputsOf(puppet: PuppetModel, tileRasters: (AtlasTileId) -> RasterImage?): List<SourceImageInput> {
val drawableIdsByTile = HashMap<AtlasTileId, MutableList<String>>()
val artUvsByTile = HashMap<AtlasTileId, MutableMap<String, FloatArray>>()
for (drawable in puppet.drawables) {
val tileId = drawable.atlasTileId ?: continue
drawableIdsByTile.getOrPut(tileId) { ArrayList() }.add(drawable.id.raw)
Cmo3Icons.artUvsOf(puppet, drawable)?.let { artUvs -> artUvsByTile.getOrPut(tileId) { HashMap() }[drawable.id.raw] = artUvs }
}
val canvasWidth = puppet.canvasWidth.roundToInt()
val canvasHeight = puppet.canvasHeight.roundToInt()
val images = ArrayList<SourceImageInput>()
for (source in puppet.sources) {
val rowIndexByKey = HashMap<String, Int>()
for ((rowIndex, row) in source.layers.withIndex()) {
rowIndexByKey.putIfAbsent(row.key, rowIndex)
}
val ordered = ArrayList<Pair<Int, SourceLayerInput>>()
for (tile in puppet.atlas.tiles) {
val ref = tile.source ?: continue
if (ref.sourceId != source.id) {
continue
}
val rowIndex = rowIndexByKey[ref.layerKey] ?: continue
val row = source.layers[rowIndex]
val raster = tileRasters(tile.id) ?: continue
ordered.add(
rowIndex to
SourceLayerInput(
tileId = tile.id.raw,
name = tile.name,
layerKey = ref.layerKey,
groupPath = row.groupPath,
visible = row.visible,
canvasLeft = row.left,
canvasTop = row.top,
raster = raster,
placement = tile.placement,
drawableIds = drawableIdsByTile[tile.id].orEmpty(),
artUvsByDrawableId = artUvsByTile[tile.id].orEmpty(),
),
)
}
if (ordered.isEmpty()) {
continue
}
// A stable sort: two tiles bound to one row (a double binding) keep their atlas order.
images.add(SourceImageInput(source.name, source.path, source.lastModified, canvasWidth, canvasHeight, ordered.sortedBy { (rowIndex, _) -> rowIndex }.map { (_, layer) -> layer }))
}
return images
}
/**
* Writes one file's web: the layered image with its folder tree and layers, the model-image group
* with one image per layer, an entry on each placed tile's atlas, and the bindings.
*
* @param SourceImageInput image The file and its tiles.
* @param List<CTextureAtlas> atlases The pages' atlas elements, in model page order.
* @param List<GTexture2D> textures The pages' shared textures, index-parallel to [atlases].
* @param Cmo3FreshChainNames names The document's shared definitions and naming counters.
* @param MutableList pngEntries The PNG entry collector.
* @param Long nowMillis The import timestamp the wrapper and env values record, standing in
* for a time the record lacks.
* @return Written The wrapper, the group, and the bindings.
*/
internal fun write(
image: SourceImageInput,
atlases: List<CTextureAtlas>,
textures: List<GTexture2D>,
names: Cmo3ImageChainBuilder.Cmo3FreshChainNames,
pngEntries: MutableList<Cmo3FreshFile.PngEntry>,
nowMillis: Long,
): Written {
val minted = mintLayeredImage(image.name, image.path, image.lastModified, image.width, image.height, names, nowMillis)
val layeredImage = minted.image
val rootChildren = minted.rootChildren
val rootGroup = minted.rootGroup
val layerEntryList = minted.layerEntryList
val group = mintModelImageGroup(image.name, layeredImage)
val groupModelImages = checkNotNull(mutableGraphListOf(group._modelImages)) { "mintModelImageGroup builds a list" }
// Folders are minted on first encounter along each layer's path, so only the folders that
// hold a written layer exist, nested the way the file nests them.
val childrenByPath = HashMap<String, CArrayList<Any?>>()
val groupByPath = HashMap<String, CLayerGroup>()
childrenByPath[""] = rootChildren
groupByPath[""] = rootGroup
fun folderAt(path: String): CLayerGroup {
groupByPath[path]?.let { existing -> return existing }
val parentPath = path.substringBeforeLast('/', "")
folderAt(parentPath)
val children = CArrayList<Any?>()
val folder = layerGroup(path.substringAfterLast('/'), layeredImage, children, names)
childrenByPath.getValue(parentPath).add(folder)
layerEntryList.add(folder)
childrenByPath[path] = children
groupByPath[path] = folder
return folder
}
val bindings = HashMap<String, Cmo3DrawableTextureBinding>()
for (layerInput in image.layers) {
val raster = layerInput.raster
val pngBytes = PngCodec.write(raster)
val path = names.nextImageFileBufPath()
pngEntries.add(Cmo3FreshFile.PngEntry(path, pngBytes))
val resource = layerResource(path, raster, pngBytes.size)
val folder = folderAt(layerInput.groupPath)
val layer =
layerOver(
name = layerInput.name,
layerKey = layerInput.layerKey,
visible = layerInput.visible,
canvasLeft = layerInput.canvasLeft,
canvasTop = layerInput.canvasTop,
resource = resource,
raster = raster,
layeredImage = layeredImage,
folder = folder,
names = names,
pngEntries = pngEntries,
)
childrenByPath.getValue(layerInput.groupPath).add(layer)
layerEntryList.add(layer)
val modelImage = Cmo3ImageChainBuilder.modelImageOver(layerInput.name, layeredImage, layer, resource, raster, layerPlacement(layerInput.canvasLeft, layerInput.canvasTop), group, names, pngEntries, nowMillis)
groupModelImages.add(modelImage)
val tilePlacement = layerInput.placement ?: continue
val atlas = atlases.getOrNull(tilePlacement.pageIndex) ?: continue
val texture = textures[tilePlacement.pageIndex]
// The entry pair: the packing as the placement records it, and the atlas-to-canvas half
// composed so the two compose back to the layer's translation. Every drawable over the
// tile carries the entry's transform as its region input, the official relation - a
// duplicate moved elsewhere keeps sampling the same tile, as a Cubism duplicate does.
val canvasAffine = floatArrayOf(1f, 0f, layerInput.canvasLeft.toFloat(), 0f, 1f, layerInput.canvasTop.toFloat())
val entryHalf = atlasLocalToCanvasFor(canvasAffine, tilePlacement) ?: continue
checkNotNull(mutableGraphListOf(atlas.modelImages)) { "pageAtlas builds a list" }.add(
Cmo3ImageChainBuilder.packedEntry(
atlas = atlas,
modelImageGuid = modelImage.guid,
atlasLocalToCanvas = affineOf(entryHalf),
packing = Cmo3ImageChainBuilder.writePacking(GTransform2(), tilePlacement),
),
)
for (drawableId in layerInput.drawableIds) {
// The drawable's icons show the patch its mesh covers on the layer, one icon per
// drawable like the editor's files.
val patch = Cmo3Icons.patchOf(raster, layerInput.artUvsByDrawableId[drawableId])
bindings[drawableId] =
Cmo3DrawableTextureBinding(
texture,
atlas.guid as Guid,
modelImage.guid as Guid,
affineOf(entryHalf),
icon32 = Cmo3Icons.iconOf(patch, 32, names.nextIconPath(), pngEntries),
icon16 = Cmo3Icons.iconOf(patch, 16, names.nextIconPath(), pngEntries),
)
}
}
return Written(minted.wrapper, group, bindings)
}
/**
* A freshly minted layered image with the lists a layer is added through.
*
* @property LayeredImageWrapper wrapper The wrapper, for the texture manager's raw-image list.
* @property CLayeredImage image The layered image.
* @property CLayerGroup rootGroup Its root folder.
* @property CArrayList rootChildren The root folder's child list.
* @property CArrayList layerEntryList The flat entry list every group and layer joins.
*/
internal class MintedLayeredImage(
val wrapper: LayeredImageWrapper,
val image: CLayeredImage,
val rootGroup: CLayerGroup,
val rootChildren: CArrayList<Any?>,
val layerEntryList: CArrayList<Any?>,
)
/**
* Mints one artwork file's layered image: the document frame, the file reference, an empty root
* folder, and the flat entry list, wrapped for the texture manager's raw-image list. Shared by the
* fresh web and the retained-graph mint, so a file added to a retained document takes the same
* shape as one in a fresh export.
*
* @param String name The file's display name.
* @param String? path The file's recorded path, or null when the record has none.
* @param Long? lastModified The file's modification time as last read, or null.
* @param Int width The frame the layers' canvas coordinates live in.
* @param Int height Its height.
* @param Cmo3FreshChainNames names The document's shared blend and options.
* @param Long nowMillis The import timestamp, standing in for a time the record lacks.
* @return MintedLayeredImage The image and its lists.
*/
internal fun mintLayeredImage(
name: String,
path: String?,
lastModified: Long?,
width: Int,
height: Int,
names: Cmo3ImageChainBuilder.Cmo3FreshChainNames,
nowMillis: Long,
): MintedLayeredImage {
val layeredImage = CLayeredImage()
val rootChildren = CArrayList<Any?>()
val rootGroup = layerGroup("root", layeredImage, rootChildren, names)
val layerEntryList = CArrayList<Any?>(mutableListOf<Any?>(rootGroup))
layeredImage.apply {
this.name = name
memo = ""
// CMO3: CLayeredImage fields width / height - the source document's own frame; the
// inventory's canvas coordinates live in the document canvas, so that is the frame here.
this.width = width
this.height = height
// CMO3: CLayeredImage field psdFile - the external-reference <file> shape whose text is the
// source's path on the importing machine; the name stands in when the record has none.
psdFile = FileRef().apply { textPath = path ?: name }
description = ""
guid = Cmo3SkeletonBuilder.freshGuid("CLayeredImageGuid")
// CMO3: CLayeredImage field psdFileLastModified - the source's modification time as last read.
psdFileLastModified = lastModified ?: nowMillis
_rootLayer = rootGroup
layerSet =
LayerSet().apply {
_layeredImage = layeredImage
_layerEntryList = layerEntryList
}
}
val wrapper =
LayeredImageWrapper().apply {
image = layeredImage
importedTimeMSec = nowMillis
lastModifiedTimeMSec = lastModified ?: nowMillis
}
return MintedLayeredImage(wrapper, layeredImage, rootGroup, rootChildren, layerEntryList)
}
/**
* A file's model-image group, linked to its layered image and empty of images.
*
* @param String name The file's display name, which the group takes.
* @param CLayeredImage layeredImage The file's layered image.
* @return CModelImageGroup The group.
*/
internal fun mintModelImageGroup(name: String, layeredImage: CLayeredImage): CModelImageGroup =
CModelImageGroup().apply {
// CMO3: CModelImageGroup fields groupName / _linkedRawImageGuids / _modelImages.
memo = ""
groupName = name
_linkedRawImageGuids = CArrayList<Any?>(mutableListOf(layeredImage.guid))
_modelImages = CArrayList<Any?>()
}
/**
* A layer's own image resource: the raster's dimensions, type, and archive link.
*
* @param String path The archive path the layer PNG is stored under.
* @param RasterImage raster The layer's pixels.
* @param Int pngSize The encoded PNG's byte size.
* @return CImageResource The resource.
*/
internal fun layerResource(path: String, raster: RasterImage, pngSize: Int): CImageResource =
CImageResource().apply {
// CMO3: CImageResource - the layer's own pixels, the document's raster for the tile.
width = raster.width
height = raster.height
type = "INT_ARGB"
imageFileBuf = FileRef().apply { archivePath = path }
imageFileBuf_size = pngSize
}
/**
* A tile's layer on its file's document: the name, visibility, resource, rect, identifier, and
* icons the official editor writes for a PSD layer. Shared by the fresh web and the
* retained-graph mint, so a layer minted into a retained file is field-for-field the fresh shape.
*
* @param String name The layer's name.
* @param String layerKey The binding key; a "lyid:<n>" key writes Photoshop's layer id.
* @param Boolean visible The layer's visibility.
* @param Int canvasLeft The art frame's canvas x.
* @param Int canvasTop The art frame's canvas y.
* @param CImageResource resource The layer's own resource.
* @param RasterImage raster The resource's pixels, which the icons show fitted.
* @param CLayeredImage layeredImage The owning layered image.
* @param CLayerGroup folder The folder the layer sits in.
* @param Cmo3FreshChainNames names The document's shared blend, options, and icon paths.
* @param MutableList pngEntries The PNG entry collector, for the icons.
* @return CLayer The layer, not yet added to any list.
*/
internal fun layerOver(
name: String,
layerKey: String,
visible: Boolean,
canvasLeft: Int,
canvasTop: Int,
resource: CImageResource,
raster: RasterImage,
layeredImage: CLayeredImage,
folder: CLayerGroup,
names: Cmo3ImageChainBuilder.Cmo3FreshChainNames,
pngEntries: MutableList<Cmo3FreshFile.PngEntry>,
): CLayer =
CLayer().apply {
// CMO3: CLayer - the tile's layer on the file's document.
this.name = name
memo = ""
isVisible = visible
blend = names.sharedBlend
guid = Cmo3SkeletonBuilder.freshGuid("CLayerGuid")
opacity255 = 255
_optionOfIOption = names.sharedOptions
_layeredImage = layeredImage
imageResource = resource
// CMO3: CLayer field boundsOnImageDoc - the layer's rect on the document: the art frame's
// canvas origin, the raster's size (the two invariants every corpus layer obeys: origin =
// the model image's canvas placement, size = the resource dims).
boundsOnImageDoc = layerBounds(canvasLeft, canvasTop, resource.width, resource.height)
layerIdentifier = identifierOf(name, layerKey)
// CMO3: CLayer fields icon16 / icon64 - thumbnails on every corpus layer, the whole
// layer fitted into each square.
icon16 = Cmo3Icons.iconOf(raster, 16, names.nextIconPath(), pngEntries)
icon64 = Cmo3Icons.iconOf(raster, 64, names.nextIconPath(), pngEntries)
layerInfo = LinkedHashMap<String, Any?>()
this.group = folder
}
/**
* A layer's rect on its document.
*
* @param Int left The origin x.
* @param Int top The origin y.
* @param Int width The width.
* @param Int height The height.
* @return CRect The rect.
*/
internal fun layerBounds(left: Int, top: Int, width: Int, height: Int): CRect =
CRect().apply {
x = left
y = top
this.width = width
this.height = height
}
/**
* A model image's canvas placement for a layer: upright canvas-space art, a pure translation to
* the layer's origin - the invariant every corpus model image carries; the packer's work rides the
* entry.
*
* @param Int canvasLeft The layer's canvas x.
* @param Int canvasTop The layer's canvas y.
* @return CAffine The placement, an independent instance.
*/
internal fun layerPlacement(canvasLeft: Int, canvasTop: Int): CAffine =
CAffine().apply {
m02 = canvasLeft.toFloat()
m12 = canvasTop.toFloat()
}
/**
* A folder of the layered image: a group element over [children].
*
* @param String name The folder's name (one path segment, "root" for the root).
* @param CLayeredImage layeredImage The owning layered image.
* @param CArrayList children The list the folder's layers and sub-folders go into.
* @param Cmo3FreshChainNames names The document's shared blend and options.
* @return CLayerGroup The group.
*/
internal fun layerGroup(name: String, layeredImage: CLayeredImage, children: CArrayList<Any?>, names: Cmo3ImageChainBuilder.Cmo3FreshChainNames): CLayerGroup =
CLayerGroup().apply {
// CMO3: CLayerGroup - a folder of the decomposed file; ACLayerGroup field _children.
this.name = name
memo = ""
isVisible = true
blend = names.sharedBlend
guid = Cmo3SkeletonBuilder.freshGuid("CLayerGuid")
opacity255 = 255
_optionOfIOption = names.sharedOptions
_layeredImage = layeredImage
_children = children
}
/**
* The layer's identifier: its name, and Photoshop's layer id when the binding key carries one.
*
* @param String name The layer's name.
* @param String layerKey The binding key.
* @return CLayerIdentifier The identifier.
*/
internal fun identifierOf(name: String, layerKey: String): CLayerIdentifier =
CLayerIdentifier().apply {
layerName = name
val photoshopId = layerKey.takeIf { key -> key.startsWith("lyid:") }?.removePrefix("lyid:")?.toIntOrNull()
if (photoshopId == null) {
// A CLIP or KRA uuid has no home in a CMO3, so a reopened export keys the layer by name.
layerIdValue_testImpl = -1
} else {
// CMO3: CLayerIdentifier field layerId - Photoshop's lyid as four dash-separated hex
// bytes, big-endian (the form the atlas ingest parses); layerIdValue_testImpl mirrors
// it in decimal.
layerId = (3 downTo 0).joinToString("-") { shift -> ((photoshopId ushr (shift * 8)) and 0xFF).toString(16).padStart(2, '0') }
layerIdValue_testImpl = photoshopId
}
}
}
@@ -0,0 +1,821 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.Cmo3GraphEditor
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.custom.GEditableMesh2
import org.umamo.format.cmo3.model.gen.CArtMeshSource
import org.umamo.format.cmo3.model.gen.CEditableMeshExtension
import org.umamo.format.cmo3.model.gen.CParameterGroup
import org.umamo.format.cmo3.model.gen.CParameterGroupSet
import org.umamo.format.cmo3.model.gen.CParameterSource
import org.umamo.format.cmo3.model.gen.CParameterSourceSet
import org.umamo.format.cmo3.model.gen.CTextureInputExtension
import org.umamo.format.cmo3.model.gen.CTextureInput_ModelImage
import org.umamo.format.cmo3.model.gen.Type
import org.umamo.format.cmo3.model.identity.Guid
import org.umamo.format.cmo3.model.identity.Id
import org.umamo.format.cmo3.model.type.CAffine
import org.umamo.format.cmo3.type.CArrayList
import org.umamo.interop.ExportEntityCategory
import org.umamo.interop.ExportNotice
import org.umamo.interop.ExportNoticeReason
import org.umamo.runtime.model.Drawable
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.Glue
import org.umamo.runtime.model.Parameter
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.ParameterKind
import org.umamo.runtime.model.ParameterNode
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.partByDrawable
import org.umamo.runtime.model.storedToArtAffineForTile
/*
* The structural half of the CMO3 export reconcile: set membership. Creations synthesize an
* IDENTITY SHELL only (fresh guid/id, the texture/extension chain a duplicate shares with its
* source) and are appended to their source set; the caller then routes the new entity through the
* ordinary Changed lowering with every field flagged, so field writes flow through the one tested
* path rather than a parallel synthesis copy. Deletions remove the source AND strip its guid from
* every parts-panel child list (a removed guid the org rebuild would otherwise preserve as an
* unknown entry); the dangling cross-references (masks, axes, glues) fall out of the model-driven
* Changed diffs, and the shared pool is pruned once at the end.
*
* Topology rewrites and glue vertex re-binding also live here: they regenerate the GEditableMesh2
* identity surface (point mirror, fresh vertex uids, the triangle edge set) that the rest of the
* document hangs off.
*/
internal class Cmo3StructureLowering(
private val modelSource: CModelSource,
private val index: Cmo3GraphIndex,
private val editor: Cmo3GraphEditor,
private val edited: PuppetModel,
private val notices: MutableList<ExportNotice>,
// The document's texture frames, taken from the graph before the export changed it.
private val textureFrames: Cmo3TextureFrames,
private val drawableBindings: Map<String, Cmo3DrawableTextureBinding> = emptyMap(),
) {
/** True once any deletion ran - the caller prunes the shared pool exactly once at the end. */
var deletedAnything: Boolean = false
private set
private fun unsupported(
category: ExportEntityCategory,
subject: String?,
reason: ExportNoticeReason,
) {
notices.add(ExportNotice.UnsupportedChange(category, subject, reason))
}
private fun freshGuidLike(template: Guid?, fallbackKind: String): Guid =
Guid(template?.kind ?: fallbackKind).apply {
uuid = java.util.UUID.randomUUID().toString()
note = template?.note ?: "(no debug info)"
}
/**
* The shared CoordType every fresh editable mesh gets.
*
* CMO3: GEditableMesh2 field coordType - corpus meshes always carry a CoordType with coordName
* "Basic Coord"; one instance is reused so the writer hoists a single shared def.
*/
private val basicCoordType: org.umamo.format.cmo3.model.drawable.CoordType by lazy {
org.umamo.format.cmo3.model.drawable.CoordType().apply { coordName = "Basic Coord" }
}
private fun freshIdLike(template: Id?, fallbackKind: String, idStr: String): Id =
Id(template?.kind ?: fallbackKind).apply { idstr = idStr }
private fun appendToCollection(owner: Any, ownerTag: String, property: String, current: Any?, assign: (MutableList<Any?>) -> Unit, element: Any) {
val mutable = mutableGraphListOf(current)
if (mutable != null) {
mutable.add(element)
return
}
// Every field this helper serves (_sources, _groups, _childGuids) is carray_list in every
// corpus model; the official editor's deserializers cast such fields to CArrayList, so an
// array_list tag fails its load.
val fresh: MutableList<Any?> = CArrayList()
fresh.add(element)
assign(fresh)
editor.ensureChildSlot(owner, ownerTag, property)
}
private fun removeFromCollection(current: Any?, matches: (Any?) -> Boolean): Boolean {
val mutable = mutableGraphListOf(current) ?: return false
return mutable.removeAll(matches)
}
/** Strips [uuid] from every parts-panel child list (all user parts plus the synthetic root). */
private fun stripFromChildLists(uuid: String?) {
if (uuid == null) {
return
}
val parts = index.userPartSources + listOfNotNull(index.rootPartSource)
for (part in parts) {
mutableGraphListOf(part._childGuids)?.removeAll { entry -> Cmo3Import.uuidOf(entry) == uuid }
}
}
/**
* Synthesizes the identity shell for a created parameter and appends it in document order (the
* PARAMETER_ORDER lowering re-sorts afterwards).
*
* @param Parameter editedParameter The created parameter.
* @return Boolean True on success.
*/
fun synthesizeParameter(editedParameter: Parameter): Boolean {
val sourceSet = modelSource.parameterSourceSet as? CParameterSourceSet
if (sourceSet == null) {
unsupported(ExportEntityCategory.Parameter, editedParameter.id.raw, ExportNoticeReason.NoSourceSetToCreateInto)
return false
}
val template = index.parameterSources.firstOrNull()
val fresh =
CParameterSource().apply {
// CMO3: CParameterSource - identity plus the editor conventions cloned from a sibling
// (decimal places, snap epsilon, the explicit paramType).
guid = freshGuidLike(template?.guid as? Guid, "CParameterGuid")
id = freshIdLike(template?.id as? Id, "CParameterId", editedParameter.id.raw)
decimalPlaces = template?.decimalPlaces ?: 3 // Documented default from surveying 50+ CMO3 files.
snapEpsilon = template?.snapEpsilon ?: 0.001f // Documented default from surveying 50+ CMO3 files.
minValue = editedParameter.min
maxValue = editedParameter.max
defaultValue = editedParameter.default
isRepeat = false
// CMO3: CParameterSource fields paramType / description - a Type element plus the
// (possibly empty) description string on every corpus parameter, never null.
paramType = if (editedParameter.kind == ParameterKind.BLEND_SHAPE) Type.MORPH_TARGET else template?.paramType ?: Type.NORMAL
description = ""
name = editedParameter.name
combined = false
parentGroupGuid = index.rootParameterGroup?.guid
}
appendToCollection(sourceSet, "CParameterSourceSet", "_sources", sourceSet._sources, { sourceSet._sources = it }, fresh)
return true
}
/** Removes a deleted parameter's source. */
fun deleteParameter(parameterId: ParameterId) {
val sourceSet = modelSource.parameterSourceSet as? CParameterSourceSet ?: return
if (removeFromCollection(sourceSet._sources) { entry ->
entry is CParameterSource && Cmo3Import.idStrOf(entry.id) == parameterId.raw
}
) {
deletedAnything = true
}
}
/**
* Synthesizes the identity shell for a created parameter group.
*
* @param ParameterGroupId groupId The created group's id.
* @return Boolean True on success.
*/
fun synthesizeParameterGroup(groupId: ParameterGroupId): Boolean {
val groupSet = modelSource.parameterGroupSet as? CParameterGroupSet
if (groupSet == null) {
unsupported(ExportEntityCategory.ParameterGroup, groupId.raw, ExportNoticeReason.NoSourceSetToCreateInto)
return false
}
val editedGroup = findEditedGroup(groupId)
if (editedGroup == null) {
unsupported(ExportEntityCategory.ParameterGroup, groupId.raw, ExportNoticeReason.CreatedGroupIsNotInTheEditedTree)
return false
}
val template = index.groupSources.firstOrNull() ?: index.rootParameterGroup
val fresh =
CParameterGroup().apply {
// CMO3: CParameterGroup - identity shell; name/open state/children flow through the
// ordinary group lowering.
guid = freshGuidLike(template?.guid as? Guid, "CParameterGroupGuid")
id = freshIdLike(template?.id as? Id, "CParameterGroupId", groupId.raw)
name = editedGroup.name
// CMO3: CParameterGroup fields description / labelColor - present on every corpus
// group, never null.
description = ""
labelColor = Cmo3SkeletonBuilder.undefinedLabelColor()
folderIsOpened = editedGroup.initiallyOpen
_childGuids = CArrayList<Any?>()
parentGroupGuid = index.rootParameterGroup?.guid
}
appendToCollection(groupSet, "CParameterGroupSet", "_groups", groupSet._groups, { groupSet._groups = it }, fresh)
return true
}
/** Removes a deleted parameter group's source. */
fun deleteParameterGroup(groupId: ParameterGroupId) {
val groupSet = modelSource.parameterGroupSet as? CParameterGroupSet ?: return
if (removeFromCollection(groupSet._groups) { entry ->
entry is CParameterGroup && Cmo3Import.idStrOf(entry.id) == groupId.raw
}
) {
deletedAnything = true
}
}
/**
* Synthesizes the identity shell for a session-created drawable (an Object-mode duplicate):
* fresh guid/id and editable mesh, the texture binding SHARED with its texture source (the
* atlas slot both render from; no new CAFF entry). Geometry, keyforms, and every flat field
* flow through the ordinary Changed lowering afterwards.
*
* @param Drawable editedDrawable The created drawable.
* @return Boolean True on success.
*/
fun synthesizeDrawable(editedDrawable: Drawable): Boolean {
val subject = editedDrawable.id.raw
val sourceSet = modelSource.drawableSourceSet as? org.umamo.format.cmo3.model.gen.CDrawableSourceSet
if (sourceSet == null) {
unsupported(ExportEntityCategory.Drawable, subject, ExportNoticeReason.NoSourceSetToCreateInto)
return false
}
val textureSource = editedDrawable.textureSourceId?.let { index.drawableByIdStr[it.raw] }
val binding = drawableBindings[subject]
if (textureSource == null && binding == null) {
unsupported(ExportEntityCategory.Drawable, subject, ExportNoticeReason.CreatedDrawableHasNoTextureSource)
return false
}
val templateMesh = textureSource?.let(Cmo3Import::editableMeshOf)
val ownerPartId = edited.partByDrawable()[editedDrawable.id]
val ownerGuid = ownerPartId?.let { index.partByIdStr[it.raw]?.guid } ?: index.rootPartSource?.guid
val fresh = CArtMeshSource()
fresh.apply {
guid = freshGuidLike(textureSource?.guid as? Guid, "CDrawableGuid")
id = freshIdLike(textureSource?.id as? Id, "CDrawableId", subject)
parentGuid = ownerGuid
// CMO3: ACParameterControllableSource fields keyformMorphTargetSet / labelColor and
// CArtMeshSource field userData - present on every corpus drawable, never omitted.
keyformMorphTargetSet = Cmo3SkeletonBuilder.emptyMorphTargetSet()
labelColor = Cmo3SkeletonBuilder.undefinedLabelColor()
userData = ""
// CMO3: ACDrawableSource fields icon32 / icon16 - the drawable's own thumbnails of its
// texture patch, minted by whoever built the binding; a drawable with no binding (a clone
// of a source with no art of its own) carries none.
icon32 = binding?.icon32
icon16 = binding?.icon16
if (textureSource != null) {
// CMO3: CArtMeshSource identity shell. The texture and texture-input extension are
// the SOURCE drawable's own objects (the writer hoists the shared references), so the
// duplicate samples the same atlas slot without new image-chain entries.
texture = textureSource.texture
textureState = textureSource.textureState
} else {
// CMO3: the fresh-graph binding - the page's SHARED GTexture2D plus a per-drawable
// CTextureInput_TextureAtlasRegion, so UVs stay in the atlas frame (hasAtlasRegion).
texture = binding!!.texture
textureState = org.umamo.format.cmo3.model.gen.TextureState.TEXTURE_ATLAS
}
_extensions =
CArrayList<Any?>().apply {
if (textureSource != null) {
Cmo3Import.elementsOf(textureSource._extensions)
.filterIsInstance<CTextureInputExtension>()
.firstOrNull()
?.let(::add)
} else {
add(freshTextureInputExtension(fresh, binding!!, editedDrawable.name))
}
add(
CEditableMeshExtension().apply {
guid = freshGuidLike(null, "CExtensionGuid")
// CMO3: ACExtension field _owner - the owning drawable source; every
// corpus extension carries the backref.
_owner = fresh
editableMesh =
GEditableMesh2().apply {
// CMO3: GEditableMesh2 field meshGuid - kind GEditableMeshGuid
// (com.live2d.type.GEditableMeshGuid); no corpus file ever emits a
// CMeshGuid tag, so that kind would author an unimportable class.
meshGuid = freshGuidLike(templateMesh?.meshGuid as? Guid, "GEditableMeshGuid")
// CMO3: GEditableMesh2 field coordType - corpus meshes always
// carry "Basic Coord" (never null).
coordType = templateMesh?.coordType ?: basicCoordType
useDelaunayTriangulation = false
}
},
)
}
}
appendToCollection(sourceSet, "CDrawableSourceSet", "_sources", sourceSet._sources, { sourceSet._sources = it }, fresh)
return true
}
/**
* Builds the per-drawable texture-input extension for a fresh-graph binding: both input kinds
* (model image + atlas region), with the one the document's display mode samples made active,
* mirroring the editor's packed drawables.
*
* @param CArtMeshSource owner The drawable source under construction.
* @param Cmo3DrawableTextureBinding binding The drawable's texture web (page texture + patch).
* @param String subjectName The drawable's display name, naming it in the display-mode notice.
* @return CTextureInputExtension The fresh extension.
*/
private fun freshTextureInputExtension(
owner: CArtMeshSource,
binding: Cmo3DrawableTextureBinding,
subjectName: String,
): CTextureInputExtension {
val extension = CTextureInputExtension()
val atlasRegion =
org.umamo.format.cmo3.model.gen.CTextureInput_TextureAtlasRegion().apply {
// CMO3: CTextureInput_TextureAtlasRegion fields textureAtlasGuid +
// inputImageLocalToCanvasTransform (ACTextureInput super carries the owner backref).
// The transform places the atlas page's pixel frame on the canvas so this drawable's
// texture patch coincides with its base mesh - the editor inverts it to draw the mesh
// over the texture in the atlas and mesh-edit views.
optionalTransformOnCanvas = CAffine()
_owner = extension
textureAtlasGuid = binding.textureAtlasGuid
inputImageLocalToCanvasTransform = binding.inputImageLocalToCanvasTransform
}
val modelImage =
binding.modelImageGuid?.let { imageGuid ->
org.umamo.format.cmo3.model.gen.CTextureInput_ModelImage().apply {
// CMO3: CTextureInput_ModelImage field _modelImageGuid.
optionalTransformOnCanvas = CAffine()
_owner = extension
_modelImageGuid = imageGuid
}
}
// A layer-mode document whose created drawable has no model image keeps the atlas region active:
// it is the only input such a drawable has, and leaving the live pointer there is what keeps the
// file self-consistent. The notice names the gap, matching what the property lowering reports
// for an EXISTING drawable in the same state - one reason, reported the same way from both paths.
if (edited.rendersFromSourceLayers && modelImage == null) {
unsupported(ExportEntityCategory.Drawable, subjectName, ExportNoticeReason.NoTextureInputForDisplayMode)
}
return extension.apply {
guid = freshGuidLike(null, "CExtensionGuid")
_owner = owner
_textureInputs =
CArrayList<Any?>().apply {
modelImage?.let(::add)
add(atlasRegion)
}
// CMO3: CTextureInputExtension field currentTextureInputData - which input the document's
// display mode samples. A drawable created in a layer-mode document must point at its model
// image, or the file's flag and its drawables disagree.
currentTextureInputData =
if (edited.rendersFromSourceLayers) {
modelImage ?: atlasRegion
} else {
atlasRegion
}
}
}
/**
* Synthesizes the identity shell for a created part: the super web plus a one-cell keyform grid
* with a single CPartForm, so static draw-order/opacity/composite writes have a form to land in
* (the field lowering only fills EXISTING part forms). Panel placement flows from the parent's
* CHILDREN rebuild.
*
* @param Part editedPart The created part.
* @return Boolean True on success.
*/
fun synthesizePart(editedPart: org.umamo.runtime.model.Part): Boolean {
val sourceSet = modelSource.partSourceSet as? org.umamo.format.cmo3.model.gen.CPartSourceSet
if (sourceSet == null) {
unsupported(ExportEntityCategory.Part, editedPart.id.raw, ExportNoticeReason.NoSourceSetToCreateInto)
return false
}
val template = index.userPartSources.firstOrNull() ?: index.rootPartSource
val part = org.umamo.format.cmo3.model.gen.CPartSource()
val formGuid = freshGuidLike(null, "CFormGuid")
val form =
org.umamo.format.cmo3.model.gen.CPartForm().apply {
// CMO3: CPartForm - the one default-cell form (drawOrder/opacity/colors).
guid = formGuid
_source = part
notes = ""
drawOrder = editedPart.drawOrder
opacity = 1f
multiplyColor = Cmo3SkeletonBuilder.identityMultiplyColor()
screenColor = Cmo3SkeletonBuilder.identityScreenColor()
}
part.apply {
localName = editedPart.name
isVisible = true
keyformGridSource =
org.umamo.format.cmo3.model.gen.KeyformGridSource().apply {
// CMO3: KeyformGridSource - one unkeyed cell (empty access key) like the blank's parts.
keyformsOnGrid =
ArrayList<Any?>(
mutableListOf(
org.umamo.format.cmo3.model.gen.KeyformOnGrid().apply {
accessKey =
org.umamo.format.cmo3.model.gen.KeyformGridAccessKey().apply {
_keyOnParameterList = ArrayList<Any?>()
}
keyformGuid = formGuid
},
),
)
keyformBindings = ArrayList<Any?>()
}
keyformMorphTargetSet = Cmo3SkeletonBuilder.emptyMorphTargetSet()
_extensions = CArrayList<Any?>()
labelColor = Cmo3SkeletonBuilder.undefinedLabelColor()
guid = freshGuidLike(template?.guid as? Guid, "CPartGuid")
id = freshIdLike(template?.id as? Id, "CPartId", editedPart.id.raw)
keyforms = CArrayList<Any?>(mutableListOf(form))
defaultOrder_forEditor = editedPart.drawOrder
partsEditColor = org.umamo.format.cmo3.model.type.CColor()
_childGuids = CArrayList<Any?>()
clipGuidList = CArrayList<Any?>()
colorComposition = org.umamo.format.cmo3.model.gen.ColorComposition.NORMAL
alphaComposition = org.umamo.format.cmo3.model.gen.AlphaComposition.OVER
}
appendToCollection(sourceSet, "CPartSourceSet", "_sources", sourceSet._sources, { sourceSet._sources = it }, part)
return true
}
/**
* Synthesizes the identity shell for a created deformer (warp or rotation). Lattice/angle
* fields, parent/part wiring, and the whole keyform web flow through the Changed lowering.
*
* @param Deformer editedDeformer The created deformer.
* @return Boolean True on success.
*/
fun synthesizeDeformer(editedDeformer: org.umamo.runtime.model.Deformer): Boolean {
val sourceSet = modelSource.deformerSourceSet as? org.umamo.format.cmo3.model.gen.CDeformerSourceSet
if (sourceSet == null) {
unsupported(ExportEntityCategory.Deformer, editedDeformer.id.raw, ExportNoticeReason.NoSourceSetToCreateInto)
return false
}
val fresh: org.umamo.format.cmo3.model.gen.ACDeformerSource =
when (editedDeformer) {
is org.umamo.runtime.model.Deformer.Warp -> {
val template =
index.deformerSources.filterIsInstance<org.umamo.format.cmo3.model.gen.CWarpDeformerSource>().firstOrNull()
org.umamo.format.cmo3.model.gen.CWarpDeformerSource().apply {
guid = freshGuidLike(template?.guid as? Guid, "CDeformerGuid")
id = freshIdLike(template?.id as? Id, "CDeformerId", editedDeformer.id.raw)
keyforms = CArrayList<Any?>()
}
}
is org.umamo.runtime.model.Deformer.Rotation -> {
val template =
index.deformerSources.filterIsInstance<org.umamo.format.cmo3.model.gen.CRotationDeformerSource>().firstOrNull()
org.umamo.format.cmo3.model.gen.CRotationDeformerSource().apply {
guid = freshGuidLike(template?.guid as? Guid, "CDeformerGuid")
id = freshIdLike(template?.id as? Id, "CDeformerId", editedDeformer.id.raw)
keyforms = CArrayList<Any?>()
// CMO3: CRotationDeformerSource fields handleLengthOnCanvas /
// circleRadiusOnCanvas - editor gizmo sizing only; cloned from a sibling when
// one exists, else nominal defaults (no runtime consumes them).
handleLengthOnCanvas = template?.handleLengthOnCanvas ?: 100f
circleRadiusOnCanvas = template?.circleRadiusOnCanvas ?: 20f
}
}
}
fresh.apply {
localName = editedDeformer.name
isVisible = true
isLocked = !editedDeformer.isSelectable
keyformMorphTargetSet = Cmo3SkeletonBuilder.emptyMorphTargetSet()
_extensions = CArrayList<Any?>()
labelColor = Cmo3SkeletonBuilder.undefinedLabelColor()
}
appendToCollection(sourceSet, "CDeformerSourceSet", "_sources", sourceSet._sources, { sourceSet._sources = it }, fresh)
return true
}
/**
* Synthesizes the identity shell for a created glue. Pair weights/uids and the intensity
* track flow through the Changed lowering (lowerGluePairsFor + lowerGlue).
*
* @param Glue editedGlue The created glue.
* @param Int ordinal The glue's ordinal among same-pair glues (the diff key).
* @return Boolean True on success.
*/
fun synthesizeGlue(editedGlue: Glue, ordinal: Int): Boolean {
val subject = "${editedGlue.meshA.raw}~${editedGlue.meshB.raw}"
val sourceSet = modelSource.affecterSourceSet as? org.umamo.format.cmo3.model.gen.CAffecterSourceSet
if (sourceSet == null) {
unsupported(ExportEntityCategory.Glue, subject, ExportNoticeReason.NoSourceSetToCreateInto)
return false
}
val meshAGuid = index.drawableByIdStr[editedGlue.meshA.raw]?.guid as? Guid
val meshBGuid = index.drawableByIdStr[editedGlue.meshB.raw]?.guid as? Guid
if (meshAGuid == null || meshBGuid == null) {
unsupported(ExportEntityCategory.Glue, subject, ExportNoticeReason.GluedDrawableHasNoSource)
return false
}
val template = index.glueSources.firstOrNull()
val ownerPartId = edited.partByDrawable()[editedGlue.meshA]
val ownerPart = ownerPartId?.let { index.partByIdStr[it.raw] } ?: index.rootPartSource
val ownerGuid = ownerPart?.guid
val fresh = org.umamo.format.cmo3.model.gen.CGlueSource()
val glueGuid = freshGuidLike(template?.guid as? Guid, "CAffecterGuid")
val formGuid = freshGuidLike(null, "CFormGuid")
val form =
org.umamo.format.cmo3.model.gen.CGlueForm().apply {
// CMO3: CGlueForm - the one default-cell form; every corpus glue carries at least
// this cell, and the intensity lowering writes only into existing forms.
guid = formGuid
isAnimatedForm = false
isLocalAnimatedForm = false
_source = fresh
notes = ""
intensity = 1f
}
fresh.apply {
localName = ""
isVisible = true
// CMO3: ACParameterControllableSource field parentGuid - the owning part, like the
// glued drawables' own panel parent (corpus glues always sit under a part).
parentGuid = ownerGuid
keyformGridSource =
org.umamo.format.cmo3.model.gen.KeyformGridSource().apply {
// CMO3: KeyformGridSource - one unkeyed cell (empty access key), the corpus
// glue default; an intensity track later rebuilds this web via writeGridWeb.
keyformsOnGrid =
ArrayList<Any?>(
mutableListOf(
org.umamo.format.cmo3.model.gen.KeyformOnGrid().apply {
accessKey =
org.umamo.format.cmo3.model.gen.KeyformGridAccessKey().apply {
_keyOnParameterList = ArrayList<Any?>()
}
keyformGuid = formGuid
},
),
)
keyformBindings = ArrayList<Any?>()
}
keyformMorphTargetSet = Cmo3SkeletonBuilder.emptyMorphTargetSet()
_extensions = CArrayList<Any?>()
labelColor = Cmo3SkeletonBuilder.undefinedLabelColor()
guid = glueGuid
// The model keys glues by mesh pair + ordinal (they carry no id of their own), so the
// minted idstr only needs uniqueness within the document.
id = freshIdLike(template?.id as? Id, "CAffecterId", "Glue_${editedGlue.meshA.raw}_${editedGlue.meshB.raw}_$ordinal")
// CMO3: ACAffecterSource field targetDeformerGuid - the editor's fixed root-deformer
// sentinel (uuid identical in every corpus file; the editor writes it even for glues
// whose meshes have real deformer parents).
targetDeformerGuid = Cmo3SkeletonBuilder.rootDeformerSentinel()
// CMO3: CGlueSource fields targetArtMeshA_guid / targetArtMeshB_guid - identity refs
// to the glued drawables' own guid objects.
targetArtMeshA_guid = meshAGuid
targetArtMeshB_guid = meshBGuid
// CMO3: CGlueSource field tabPosOnCanvas - the glue tab marker, never null; the editor
// stacks them at x = -100 down the canvas's left margin.
tabPosOnCanvas =
org.umamo.format.cmo3.model.type.GVector2().apply {
x = -100f
y = 100f * (ordinal + 1)
}
keyforms = CArrayList<Any?>(mutableListOf(form))
}
appendToCollection(sourceSet, "CAffecterSourceSet", "_sources", sourceSet._sources, { sourceSet._sources = it }, fresh)
// CMO3: CPartSource field _childGuids - the owning part lists the glue's CAffecterGuid
// after its drawables and deformers; the editor's load-time verify repairs (and 5.4
// crashes on) an affecter absent from the part hierarchy.
if (ownerPart != null) {
appendToCollection(ownerPart, "CPartSource", "_childGuids", ownerPart._childGuids, { ownerPart._childGuids = it }, glueGuid)
}
return true
}
/** Removes a deleted drawable's source and strips its guid from every panel child list. */
fun deleteDrawable(drawableId: DrawableId) {
val sourceSet = modelSource.drawableSourceSet as? org.umamo.format.cmo3.model.gen.CDrawableSourceSet ?: return
val source = index.drawableByIdStr[drawableId.raw]
if (removeFromCollection(sourceSet._sources) { entry -> entry === source }) {
stripFromChildLists(Cmo3Import.uuidOf(source?.guid))
deletedAnything = true
}
}
/** Removes a deleted part's source and strips its guid from every panel child list. */
fun deletePart(partIdRaw: String) {
val sourceSet = modelSource.partSourceSet as? org.umamo.format.cmo3.model.gen.CPartSourceSet ?: return
val source = index.partByIdStr[partIdRaw]
if (removeFromCollection(sourceSet._sources) { entry -> entry === source }) {
stripFromChildLists(Cmo3Import.uuidOf(source?.guid))
deletedAnything = true
}
}
/** Removes a deleted deformer's source and strips its guid from every panel child list. */
fun deleteDeformer(deformerIdRaw: String) {
val sourceSet = modelSource.deformerSourceSet as? org.umamo.format.cmo3.model.gen.CDeformerSourceSet ?: return
val source = index.deformerByIdStr[deformerIdRaw]
if (removeFromCollection(sourceSet._sources) { entry -> entry === source }) {
stripFromChildLists(Cmo3Import.uuidOf(source?.guid))
deletedAnything = true
}
}
/** Removes a deleted glue's source, resolved by mesh pair plus ordinal. */
fun deleteGlue(meshA: DrawableId, meshB: DrawableId, ordinal: Int) {
val sourceSet = modelSource.affecterSourceSet as? org.umamo.format.cmo3.model.gen.CAffecterSourceSet ?: return
val matching =
index.glueSources.filter { glueSource ->
index.drawableIdStrByUuid[Cmo3Import.uuidOf(glueSource.targetArtMeshA_guid)] == meshA.raw &&
index.drawableIdStrByUuid[Cmo3Import.uuidOf(glueSource.targetArtMeshB_guid)] == meshB.raw
}
val victim = matching.getOrNull(ordinal) ?: return
if (removeFromCollection(sourceSet._sources) { entry -> entry === victim }) {
stripFromChildLists(Cmo3Import.uuidOf(victim.guid))
deletedAnything = true
}
}
/**
* Rewrites a drawable's topology surface: indices, base positions, UVs, and the full
* GEditableMesh2 rebuild (point mirror, freshly minted vertex uids, the unique triangle-edge
* set), then re-binds every glue touching the drawable to the new uid table.
*
* @param CArtMeshSource source The drawable's graph source.
* @param Drawable editedDrawable The edited drawable.
* @return Boolean True on success.
*/
fun lowerMeshTopology(source: CArtMeshSource, editedDrawable: Drawable): Boolean {
val subject = editedDrawable.id.raw
val mesh = editedDrawable.mesh
if (mesh == null) {
unsupported(ExportEntityCategory.Drawable, subject, ExportNoticeReason.DrawableHasNoMesh)
return false
}
// CMO3: CArtMeshSource fields indices / positions / uvs. The positions are CANVAS-frame
// in every official file, and mesh.positions is canvas-frame by the runtime's contract:
// the MOC3 document loader normalizes parent-local rest meshes through :render's
// restMeshesToCanvasSpace at import (rendering never notices the base's frame - grids sum
// to one - but the editor's atlas and mesh-edit views read this field as canvas geometry).
source.indices = mesh.indices.copyOf()
editor.ensureChildSlot(source, "CArtMeshSource", "indices", "keyforms")
source.positions = mesh.positions.copyOf()
editor.ensureChildSlot(source, "CArtMeshSource", "positions", "uvs")
source.uvs = storedUvsFor(source, mesh.uvs, editedDrawable)
editor.ensureChildSlot(source, "CArtMeshSource", "uvs", "texture")
val editableMesh = Cmo3Import.editableMeshOf(source)
if (editableMesh != null) {
val vertexCount = mesh.vertexCount
// CMO3: GEditableMesh2 - point mirrors the positions as its own array; pointUid gets a
// freshly minted 0..n-1 table (glues re-bind below, so re-minting is safe); edge is the
// unique undirected triangle-edge set; the Delaunay flag drops (the triangulation is
// authored by the indices now).
editableMesh.point = mesh.positions.copyOf()
editor.ensureChildSlot(editableMesh, "GEditableMesh2", "point", "pointPriority")
editableMesh.pointUid = IntArray(vertexCount) { vertexOrdinal -> vertexOrdinal }
editor.ensureChildSlot(editableMesh, "GEditableMesh2", "pointUid", "meshGuid")
editableMesh.nextPointUid = vertexCount
editor.ensurePresentAttr(editableMesh, "GEditableMesh2", "nextPointUid")
editableMesh.useDelaunayTriangulation = false
editor.ensurePresentAttr(editableMesh, "GEditableMesh2", "useDelaunayTriangulation")
if (vertexCount <= Short.MAX_VALUE.toInt()) {
editableMesh.edge = triangleEdges(mesh.indices)
editor.ensureChildSlot(editableMesh, "GEditableMesh2", "edge", "edgePriority")
} else {
unsupported(
ExportEntityCategory.Drawable,
subject,
ExportNoticeReason.VertexCountExceedsEdgeTable(vertexCount, Short.MAX_VALUE.toInt()),
)
}
// Priority arrays resize to the new counts, keeping whichever array type was stored.
editableMesh.pointPriority = resizedPriorityArray(editableMesh.pointPriority, vertexCount, freshDefault = 10)
editor.ensureChildSlot(editableMesh, "GEditableMesh2", "pointPriority", "edge")
(editableMesh.edge as? ShortArray)?.let { edges ->
editableMesh.edgePriority = resizedPriorityArray(editableMesh.edgePriority, edges.size / 2, freshDefault = 30)
editor.ensureChildSlot(editableMesh, "GEditableMesh2", "edgePriority", "pointUid")
}
}
for (glue in edited.glues) {
if (glue.meshA != editedDrawable.id && glue.meshB != editedDrawable.id) {
continue
}
// A partner whose uid table is still missing is a fresh shell whose own topology pass is
// later in this same export - ITS re-bind loop covers this glue with both tables minted,
// so a premature attempt here would only raise a spurious notice.
if (uidTableOf(glue.meshA) == null || uidTableOf(glue.meshB) == null) {
continue
}
lowerGluePairsFor(glue)
}
return true
}
/**
* Rewrites a glue's vertex binding (weights + bindVertexUids) from the edited model's
* index-based pairs against both meshes' CURRENT uid tables.
*
* @param Glue editedGlue The edited glue.
* @return Boolean True on success.
*/
fun lowerGluePairsFor(editedGlue: Glue): Boolean {
val subject = "${editedGlue.meshA.raw}+${editedGlue.meshB.raw}"
val editedByPair = edited.glues.filter { it.meshA == editedGlue.meshA && it.meshB == editedGlue.meshB }
val ordinal = editedByPair.indexOfFirst { it === editedGlue }.coerceAtLeast(0)
val glueSource =
index.glueSources.filter { candidate ->
index.drawableIdStrByUuid[Cmo3Import.uuidOf(candidate.targetArtMeshA_guid)] == editedGlue.meshA.raw &&
index.drawableIdStrByUuid[Cmo3Import.uuidOf(candidate.targetArtMeshB_guid)] == editedGlue.meshB.raw
}.getOrNull(ordinal)
if (glueSource == null) {
unsupported(ExportEntityCategory.Glue, subject, ExportNoticeReason.NoMatchingSourceToReconcile)
return false
}
val uidTableA = uidTableOf(editedGlue.meshA)
val uidTableB = uidTableOf(editedGlue.meshB)
if (uidTableA == null || uidTableB == null) {
unsupported(ExportEntityCategory.Glue, subject, ExportNoticeReason.GluedMeshHasNoUidTable)
return false
}
val pairCount = editedGlue.pairs.size
val weights = FloatArray(pairCount * 2)
val uids = LongArray(pairCount * 2)
for (pairIndex in 0 until pairCount) {
val pair = editedGlue.pairs[pairIndex]
val uidA = uidTableA.getOrNull(pair.indexA)
val uidB = uidTableB.getOrNull(pair.indexB)
if (uidA == null || uidB == null) {
unsupported(ExportEntityCategory.Glue, subject, ExportNoticeReason.GluePairIndexesPastUidTable)
return false
}
// CMO3: CGlueSource fields weights / bindVertexUids - [A, B]-interleaved per pair.
weights[pairIndex * 2] = pair.weightA
weights[pairIndex * 2 + 1] = pair.weightB
uids[pairIndex * 2] = uidA.toLong()
uids[pairIndex * 2 + 1] = uidB.toLong()
}
glueSource.weights = weights
editor.ensureChildSlot(glueSource, "CGlueSource", "weights", "keyforms")
glueSource.bindVertexUids = uids
editor.ensureChildSlot(glueSource, "CGlueSource", "bindVertexUids", "tabPosOnCanvas")
return true
}
private fun uidTableOf(drawableId: DrawableId): IntArray? =
index.drawableByIdStr[drawableId.raw]?.let { source -> Cmo3Import.editableMeshOf(source)?.pointUid as? IntArray }
/** The unique undirected triangle edges as the editable mesh's short-indexed pair list. */
private fun triangleEdges(indices: IntArray): ShortArray {
val seen = LinkedHashSet<Int>()
var triangleStart = 0
while (triangleStart + 2 < indices.size) {
for (cornerIndex in 0 until 3) {
val endpointA = indices[triangleStart + cornerIndex]
val endpointB = indices[triangleStart + (cornerIndex + 1) % 3]
val low = minOf(endpointA, endpointB)
val high = maxOf(endpointA, endpointB)
seen.add(low shl 16 or high)
}
triangleStart += 3
}
val edges = ShortArray(seen.size * 2)
var writeIndex = 0
for (packed in seen) {
edges[writeIndex++] = (packed shr 16).toShort()
edges[writeIndex++] = (packed and 0xFFFF).toShort()
}
return edges
}
/**
* A priority array of [count] entries matching [existing]'s stored type, or a fresh byte
* array filled with [freshDefault] when none was stored.
*
* CMO3: GEditableMesh2 fields pointPriority / edgePriority - byte arrays on every corpus
* mesh, never null (the editor NPEs on a null); points carry 10, triangle edges 30.
*/
private fun resizedPriorityArray(existing: Any?, count: Int, freshDefault: Byte): Any? =
when (existing) {
is IntArray -> IntArray(count)
is ShortArray -> ShortArray(count)
is FloatArray -> FloatArray(count)
is ByteArray -> ByteArray(count) { freshDefault }
else -> ByteArray(count) { freshDefault }
}
/**
* The UVs as CMO3 stores them, in the frame the drawable stores ([Cmo3TextureFrames.storedUvsOf]), off
* its tile's page through the edited placement when the tile has one.
*
* @param CArtMeshSource source The drawable's graph source.
* @param FloatArray uvs The model-frame UVs.
* @param Drawable editedDrawable The edited drawable, whose tile the UVs address.
* @return FloatArray The stored-frame UVs.
*/
private fun storedUvsFor(source: CArtMeshSource, uvs: FloatArray, editedDrawable: Drawable): FloatArray =
textureFrames.storedUvsOf(source, uvs, editedDrawable.atlasTileId?.let { tileId -> edited.atlas.storedToArtAffineForTile(tileId) })
private fun findEditedGroup(groupId: ParameterGroupId): ParameterNode.Group? {
fun walk(nodes: List<ParameterNode>): ParameterNode.Group? {
for (node in nodes) {
if (node is ParameterNode.Group) {
if (node.id == groupId) {
return node
}
walk(node.children)?.let { return it }
}
}
return null
}
return walk(edited.parameterTree)
}
}
@@ -0,0 +1,252 @@
package org.umamo.interop
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.model.RotationDeformer
import org.umamo.format.moc3.model.WarpDeformer
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.export.Moc3Export
import org.umamo.runtime.model.PuppetModel
import org.umamo.runtime.model.partByDrawable
import java.io.File
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* A CMO3 exported to MOC3 describes the same rig as the editor's own bake of that model.
*
* The corpus holds TWINS - the same model saved as `.cmo3` and baked to `.moc3` by the official
* editor - which makes this the only test that can check the export against something other than our
* own reading of it. Every other MOC3 gate starts from a moc: import it, write it back, compare.
* That proves self-consistency and nothing about whether our lowering agrees with Cubism's.
*
* STRUCTURE is compared as equality, and by id: object sets, kinds, parentage, mesh topology, mask
* lists, parameter ranges. Those are decisions, not arithmetic - if the editor put a drawable under a
* warp, so must we.
*
* The TEXTURE PAGE is not compared, and cannot be: a CMO3 has no atlas. Its pixels are
* embedded per drawable, and the packed pages a moc indexes into are produced BY the bake - so the
* editor's page numbers describe a packing this file does not contain. What the export writes is its
* own page set (one per embedded image, or the retained atlas for a MOC3-origin document), and the
* family it writes is self-consistent with it.
*
* GEOMETRY is not compared here at all. The two files are separate authoring artifacts: the CMO3
* holds the editor's source-space values and the moc holds its baked ones, and the transform between
* them is the editor's own, not a spec. `Cmo3ToMoc3OracleTest` compares the EVALUATED result through
* the official core instead, which is the question that actually matters and the only one with a
* defensible tolerance.
*
* Gated on `cmo3.probe` + `moc3.samples`, joined by base name; self-skips whenever the two sets share
* no base name, which includes either property being absent.
*/
class Cmo3ToMoc3CrossFormatTest {
/**
* The corpus twins, keyed by base name.
*
* @return List Each (base name, cmo3, moc3) triple the corpus can pair.
*/
private fun twins(): List<Triple<String, File, File>> {
val cmo3Files =
System.getProperty("cmo3.probe")
?.split(',')
?.map { path -> File(path.trim()) }
?.filter { file -> file.isFile }
?.associateBy { file -> file.nameWithoutExtension }
.orEmpty()
val moc3Files =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { directory -> directory.isDirectory }
?.walkTopDown()
?.filter { file -> file.isFile && file.extension == "moc3" && file.parentFile?.name != "work" }
?.associateBy { file -> file.nameWithoutExtension }
.orEmpty()
return cmo3Files.keys
.intersect(moc3Files.keys)
.sorted()
.map { name -> Triple(name, cmo3Files.getValue(name), moc3Files.getValue(name)) }
}
/**
* Exports [cmo3File]'s rig at [baked]'s own version, so the comparison is version-for-version.
*
* @param File cmo3File The source CMO3.
* @param MocDocument baked The editor's bake of the same model.
* @return MocDocument Our lowering of the CMO3.
*/
private fun exportedFrom(cmo3File: File, baked: MocDocument): Pair<PuppetModel, MocDocument> {
val model = Cmo3.read(cmo3File)
val root = model.root as? CModelSource ?: error("${cmo3File.name}: root is not a CModelSource")
val imported = Cmo3Import.fromModelSource(root)
return imported to Moc3Export.toMocDocument(imported, baked.version).document
}
@Test
fun everyTwinLowersToTheSameStructure() {
val twins = twins()
if (twins.isEmpty()) {
println("no cmo3/moc3 twins in the corpus; skipping cross-format comparison")
return
}
val failures = ArrayList<String>()
val differentRevisions = ArrayList<String>()
var compared = 0
for ((name, cmo3File, moc3File) in twins) {
val baked = Moc3.read(moc3File.readBytes())
val (source, ours) =
runCatching { exportedFrom(cmo3File, baked) }.getOrElse { failure ->
failures.add("$name: the CMO3 would not lower to a moc ($failure)")
continue
}
// A twin pair is only an oracle when the two files are the same REVISION of the model. The
// corpus has one pair that is not - the moc was baked from a different edit of the project, and
// it disagrees about meshes, parameters, and the deformer tree alike - so comparing them would
// report dozens of "divergences" that say nothing about the lowering. Detected rather than
// named, so the rule survives a corpus change, and counted in the summary so a pair that
// silently stops comparing cannot hide.
val bakedMeshIds = baked.artMeshes.map { it.id }.toSet()
val missingMeshes = bakedMeshIds - ours.artMeshes.map { it.id }.toSet()
if (missingMeshes.size > bakedMeshIds.size / 10) {
differentRevisions.add("$name (${missingMeshes.size}/${bakedMeshIds.size} art meshes absent)")
continue
}
compared++
// What the editor's bake omits and ours keeps: HIDDEN objects. The official bake deletes them
// unless "export invisible drawable" is ticked; Umamo asks the same through Moc3ExportOptions,
// but this test lowers with the options-less API default, which keeps them (flag clear) -
// deleting something the rigger can still see in the outliner is a silent destructive edit.
// That makes an unexpected id acceptable ONLY when the source says it is hidden - anything
// else is a bug.
val hiddenParts = source.parts.filterNot { part -> part.isVisible }.mapTo(HashSet()) { it.id.raw }
val hiddenDrawables =
source.drawables
.filterNot { drawable -> drawable.isVisible }
.mapTo(HashSet()) { drawable -> drawable.id.raw }
val partByDrawable = source.partByDrawable()
val hiddenByPart =
source.drawables
.filter { drawable -> partByDrawable[drawable.id]?.raw in hiddenParts }
.mapTo(HashSet()) { drawable -> drawable.id.raw }
/**
* Records a divergence against this twin.
*
* @param String what What differed.
* @param Any? expected The editor's bake.
* @param Any? actual Our lowering.
*/
fun check(what: String, expected: Any?, actual: Any?) {
if (expected != actual) {
failures.add("$name: $what editor=$expected umamo=$actual")
}
}
/**
* Compares two id sets, reporting only what differs.
*
* Dumping both sets whole is what a plain equality assert does, and on a real model that is a
* thousand ids of which two matter.
*
* @param String what The object category.
* @param Set expected The editor's ids.
* @param Set actual Ours.
* @param Set keptWhenHidden Ids ours may carry that the bake drops for being hidden.
*/
fun checkIds(what: String, expected: Set<String>, actual: Set<String>, keptWhenHidden: Set<String>) {
val missing = (expected - actual).sorted()
val extra = (actual - expected - keptWhenHidden).sorted()
if (missing.isNotEmpty() || extra.isNotEmpty()) {
failures.add(
"$name: $what differ - ${missing.size} missing ${missing.take(4)}, " +
"${extra.size} unexpected ${extra.take(4)}",
)
}
}
checkIds(
"art mesh ids",
baked.artMeshes.map { it.id }.toSet(),
ours.artMeshes.map { it.id }.toSet(),
hiddenDrawables + hiddenByPart,
)
checkIds("part ids", baked.parts.map { it.id }.toSet(), ours.parts.map { it.id }.toSet(), hiddenParts)
checkIds("parameter ids", baked.parameters.map { it.id }.toSet(), ours.parameters.map { it.id }.toSet(), emptySet())
checkIds("deformer ids", baked.deformers.map { it.id }.toSet(), ours.deformers.map { it.id }.toSet(), emptySet())
val ourMeshes = ours.artMeshes.associateBy { it.id }
val ourParts = ours.parts.associateBy { it.id }
val ourDeformers = ours.deformers.associateBy { it.id }
val ourParameters = ours.parameters.associateBy { it.id }
for (mesh in baked.artMeshes) {
val mine = ourMeshes[mesh.id] ?: continue
check("${mesh.id} vertex count", mesh.vertexCount, mine.vertexCount)
check("${mesh.id} triangle indices", mesh.triangleIndices.size, mine.triangleIndices.size)
// Resolved to IDS: the two files number their objects independently, so an index compare
// would report every model with a different authoring order as wrong.
check(
"${mesh.id} parent deformer",
baked.deformers.getOrNull(mesh.parentDeformerIndex)?.id,
ours.deformers.getOrNull(mine.parentDeformerIndex)?.id,
)
check(
"${mesh.id} owning part",
baked.parts.getOrNull(mesh.parentPartIndex)?.id,
ours.parts.getOrNull(mine.parentPartIndex)?.id,
)
check(
"${mesh.id} clip masks",
mesh.maskDrawableIndices.filter { it >= 0 }.mapNotNull { baked.artMeshes.getOrNull(it)?.id }.sorted(),
mine.maskDrawableIndices.filter { it >= 0 }.mapNotNull { ours.artMeshes.getOrNull(it)?.id }.sorted(),
)
}
for (part in baked.parts) {
val mine = ourParts[part.id] ?: continue
check(
"part ${part.id} parent",
baked.parts.getOrNull(part.parentPartIndex)?.id,
ours.parts.getOrNull(mine.parentPartIndex)?.id,
)
}
for (deformer in baked.deformers) {
val mine = ourDeformers[deformer.id] ?: continue
check("deformer ${deformer.id} kind", deformer::class.simpleName, mine::class.simpleName)
check(
"deformer ${deformer.id} parent",
baked.deformers.getOrNull(deformer.parentDeformerIndex)?.id,
ours.deformers.getOrNull(mine.parentDeformerIndex)?.id,
)
if (deformer is WarpDeformer && mine is WarpDeformer) {
check("deformer ${deformer.id} lattice", deformer.rows to deformer.columns, mine.rows to mine.columns)
}
if (deformer is RotationDeformer && mine is RotationDeformer) {
check("deformer ${deformer.id} base angle", deformer.baseAngle, mine.baseAngle)
}
}
for (parameter in baked.parameters) {
val mine = ourParameters[parameter.id] ?: continue
check("parameter ${parameter.id} minimum", parameter.minimumValue, mine.minimumValue)
check("parameter ${parameter.id} maximum", parameter.maximumValue, mine.maximumValue)
check("parameter ${parameter.id} default", parameter.defaultValue, mine.defaultValue)
check("parameter ${parameter.id} type", parameter.type, mine.type)
}
}
assertTrue(compared > 0, "no twin could be lowered")
assertTrue(
differentRevisions.size < twins.size / 2,
"most corpus twins are no longer the same revision, so this gate has stopped testing anything: " +
differentRevisions,
)
println(
"[cross-format] $compared cmo3/moc3 twins compared, ${failures.size} structural divergences" +
(if (differentRevisions.isEmpty()) "" else "; skipped as different revisions: $differentRevisions"),
)
assertEquals(emptyList(), failures.take(25), "our lowering disagrees with the editor's bake")
}
}
@@ -0,0 +1,225 @@
package org.umamo.interop
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.runtime.model.AlphaBlendMode
import org.umamo.runtime.model.BlendMode
import org.umamo.runtime.model.ChannelGrids
import org.umamo.runtime.model.ChannelValue
import org.umamo.runtime.model.ColorRgb
import org.umamo.runtime.model.FormChannel
import org.umamo.runtime.model.PartComposite
import org.umamo.runtime.model.PuppetModel
import java.io.File
import kotlin.math.abs
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
// The MultiplyScreenColors sample's authored colors: multiply #677CD1, screen #95C068 (editor hex,
// each channel serialized as hex / 255 in f32 on both formats - verified channel-exact in the
// extraction, docs/plan/offscreen-support.md).
private val AUTHORED_MULTIPLY = ColorRgb(103f / 255f, 124f / 255f, 209f / 255f)
private val AUTHORED_SCREEN = ColorRgb(149f / 255f, 192f / 255f, 104f / 255f)
private const val COLOR_TOLERANCE = 1e-6f
/**
* Corpus-gated offscreen ingest anchors over the authored extraction family (see
* docs/plan/offscreen-support.md § corpus evidence): part offscreen state, clip lists, invert,
* static and keyformed colors, and the drawable-level extended blend + culling - on BOTH import
* paths. Skips gracefully without the corpus.
*/
class CompositeImportTest {
private fun probeFiles(): Map<String, File> =
System.getProperty("cmo3.probe")
?.split(',')
?.map(::File)
?.filter { it.isFile }
?.associateBy { it.name }
?: emptyMap()
private fun mocFiles(): Map<String, File> =
System.getProperty("moc3.samples")
?.let(::File)
?.takeIf { it.isDirectory }
?.walkTopDown()
?.filter { it.isFile && it.extension == "moc3" }
?.associateBy { it.name }
?: emptyMap()
private fun importCmo3(file: File): PuppetModel {
val root = Cmo3.read(file).root as? CModelSource ?: error("${file.name}: root is not a CModelSource")
return Cmo3Import.fromModelSource(root)
}
private fun importMoc3(file: File): PuppetModel = Moc3Import.fromMocDocument(Moc3.read(file.readBytes()), null)
private fun assertColorClose(expected: ColorRgb, actual: ColorRgb, label: String) {
assertTrue(
abs(expected.red - actual.red) < COLOR_TOLERANCE &&
abs(expected.green - actual.green) < COLOR_TOLERANCE &&
abs(expected.blue - actual.blue) < COLOR_TOLERANCE,
"$label: expected $expected, got $actual",
)
}
@Test
fun cmo3BaseFamilyPinsCompositionEnums() {
val file = probeFiles()["ModelWithOffscreen.cmo3"] ?: return println("ModelWithOffscreen.cmo3 not present; skipping")
val puppet = importCmo3(file)
// Authored: Face = Normal/Over, Eye = Multiply (Before 5.3)/Disjoint, both offscreen.
val isolatedParts = puppet.parts.filter { it.activeComposite != null }
assertEquals(2, isolatedParts.size, "isolated part count")
val face = assertNotNull(puppet.parts.find { it.name == "Face" }?.activeComposite, "Face offscreen")
assertEquals(BlendMode.Normal, face.blendMode, "Face color blend")
assertEquals(AlphaBlendMode.Over, face.alphaBlendMode, "Face alpha blend")
val eye = assertNotNull(puppet.parts.find { it.name == "Eye" }?.activeComposite, "Eye offscreen")
assertEquals(BlendMode.MultiplyPremultiplied, eye.blendMode, "Eye color blend (bare legacy token)")
assertEquals(AlphaBlendMode.Disjoint, eye.alphaBlendMode, "Eye alpha blend")
}
@Test
fun cmo3ClippingReverseMaskPinsClipAndLatentFields() {
val file =
probeFiles()["ModelWithOffscreenClippingIDReverseMask.cmo3"]
?: return println("ModelWithOffscreenClippingIDReverseMask.cmo3 not present; skipping")
val puppet = importCmo3(file)
val drawableIds = puppet.drawables.mapTo(HashSet()) { it.id }
// The authored clip: an offscreen part with Reverse mask on and one drawable as Clipping ID.
val clipped = assertNotNull(puppet.parts.mapNotNull { it.activeComposite }.find { it.maskedBy.isNotEmpty() }, "clipped offscreen part")
assertTrue(clipped.invertMask, "reverse mask on")
assertEquals(1, clipped.maskedBy.size, "one clip source")
assertTrue(clipped.maskedBy.all { it in drawableIds }, "clip sources resolve to drawables")
// The fields-survive-uncheck evidence: latent composition values on a NON-offscreen part must
// not materialize an Isolated group mode.
assertTrue(puppet.parts.any { it.activeComposite == null }, "non-offscreen parts stay non-isolated")
// Latent capture: those authored composition values are now stored on the part regardless of mode
// (for UMA to track), so a non-isolated part carries a non-default composite while activeComposite
// stays null.
assertTrue(
puppet.parts.any { it.activeComposite == null && it.composite != PartComposite() },
"a non-offscreen part captured its latent composite settings",
)
}
@Test
fun cmo3PartClippingPinsDrawableExtendedBlendAndCulling() {
val file =
probeFiles()["ModelWithOffscreenPartClipping.cmo3"]
?: return println("ModelWithOffscreenPartClipping.cmo3 not present; skipping")
val puppet = importCmo3(file)
// The authored drawable: color blend Screen, alpha blend Out, Culling on.
val screenDrawable = assertNotNull(puppet.drawables.find { it.blendMode == BlendMode.Screen }, "Screen drawable")
assertEquals(AlphaBlendMode.Out, screenDrawable.alphaBlendMode, "Out alpha blend")
assertTrue(puppet.drawables.any { it.culling }, "a drawable has culling on")
// The part-as-clip-source expansion: the offscreen part's clip list resolves to the OTHER
// part's constituent drawables (never a part id).
val drawableIds = puppet.drawables.mapTo(HashSet()) { it.id }
val clipped = assertNotNull(puppet.parts.mapNotNull { it.activeComposite }.find { it.maskedBy.isNotEmpty() }, "clipped offscreen part")
assertTrue(clipped.maskedBy.all { it in drawableIds }, "part clip expanded to drawables")
}
@Test
fun cmo3MultiplyScreenColorsPinsAuthoredColors() {
val file = probeFiles()["MultiplyScreenColors.cmo3"] ?: return println("MultiplyScreenColors.cmo3 not present; skipping")
val puppet = importCmo3(file)
val composite = assertNotNull(puppet.parts.mapNotNull { it.activeComposite }.firstOrNull(), "an offscreen part")
assertColorClose(AUTHORED_MULTIPLY, composite.multiplyColor, "multiply color")
assertColorClose(AUTHORED_SCREEN, composite.screenColor, "screen color")
}
@Test
fun moc3PartClippingPinsDrawableExtendedBlendAndCulling() {
val file =
mocFiles()["ModelWithOffscreenPartClipping.moc3"]
?: return println("ModelWithOffscreenPartClipping.moc3 not present; skipping")
val puppet = importMoc3(file)
// MOC3 v6 §5.6 s153: the authored drawable stored packed 522 = Screen or (Out shl 8).
val screenDrawable = assertNotNull(puppet.drawables.find { it.blendMode == BlendMode.Screen }, "Screen drawable")
assertEquals(AlphaBlendMode.Out, screenDrawable.alphaBlendMode, "Out alpha blend")
// Culling = the inverse of drawable constant-flags bit 2 (double-sided).
assertTrue(puppet.drawables.any { it.culling }, "a drawable has culling on")
assertTrue(puppet.drawables.any { !it.culling }, "default drawables stay double-sided")
val drawableIds = puppet.drawables.mapTo(HashSet()) { it.id }
val clipped = assertNotNull(puppet.parts.mapNotNull { it.activeComposite }.find { it.maskedBy.isNotEmpty() }, "clipped offscreen part")
assertTrue(clipped.maskedBy.all { it in drawableIds }, "offscreen mask indices resolve to drawables")
}
@Test
fun moc3MultiplyScreenColorsPinsAuthoredColors() {
val file = mocFiles()["MultiplyScreenColors.moc3"] ?: return println("MultiplyScreenColors.moc3 not present; skipping")
val puppet = importMoc3(file)
val composite = assertNotNull(puppet.parts.mapNotNull { it.activeComposite }.firstOrNull(), "an offscreen part")
assertColorClose(AUTHORED_MULTIPLY, composite.multiplyColor, "multiply color")
assertColorClose(AUTHORED_SCREEN, composite.screenColor, "screen color")
}
@Test
fun moc3ModelAPinsOrganicOffscreenCount() {
val file = mocFiles()["modelA.moc3"] ?: return println("modelA.moc3 not present; skipping")
val puppet = importMoc3(file)
// Model A's 24 offscreen parts (== the moc's CountInfo[35]); the organic cross-check that the
// owner-part join holds beyond the authored extraction family.
assertEquals(24, puppet.parts.count { it.activeComposite != null }, "isolated part count")
// The keyformed-opacity evidence: at least one offscreen part carries a grid whose opacity
// varies across cells (the ParamHologram crossfade).
val hasKeyformedOpacity =
puppet.parts.any { part ->
part.activeComposite != null && (opacityValues(part.channelGrids).distinct().size) > 1
}
assertTrue(hasKeyformedOpacity, "an offscreen part has keyformed opacity")
}
@Test
fun pre53PartOpacityDefaultsToOpaque() {
// Erica Tamamo is a pre-5.3 model whose parts never author the float CPartForm.opacity, so the
// @DontSerializeIfDefault field parses as 0f = "unset -> fully opaque" (Cubism's semantic default),
// NOT 0%. Without the ingest remap the part-opacity cascade renders the whole part subtree invisible
// (every drawable under a part goes to opacity 0); only the two root-level drawables stayed visible.
val file = probeFiles()["EricaTamamo.cmo3"] ?: return println("EricaTamamo.cmo3 not present; skipping")
val model = importCmo3(file)
assertTrue(model.parts.isNotEmpty(), "EricaTamamo carries parts")
assertTrue(model.parts.none { it.composite.opacity == 0f }, "no pre-5.3 part is spuriously transparent")
assertTrue(
model.parts.none { part -> opacityValues(part.channelGrids).any { opacity -> opacity == 0f } },
"no pre-5.3 part keyform cell is spuriously transparent",
)
}
@Test
fun staticCmo3PartCarriesNoKeyformGrid() {
// A CMO3 part with no parameter binding must NOT keep a single-cell channel track: the eval samples
// the track OVER the static PartComposite, so a lingering track would shadow an edited composite
// opacity/color and an isolated static part's edit would never render (Moc3Import already yields
// empty channel grids for an unbound part - this keeps CMO3 consistent). A part with real
// animation keeps its tracks (below).
probeFiles()["EricaTamamo.cmo3"]?.let { file ->
val model = importCmo3(file)
val frontHair = model.parts.firstOrNull { it.name.equals("Front hair", ignoreCase = true) }
assertNotNull(frontHair, "EricaTamamo has a Front hair part")
assertTrue(frontHair.channelGrids.isEmpty, "a static (unbound) part carries no keyform tracks")
} ?: println("EricaTamamo.cmo3 not present; skipping")
// An animated part - keyformed part draw order / opacity - keeps its tracks (non-empty axes).
probeFiles()["modelA.cmo3"]?.let { file ->
val model = importCmo3(file)
assertTrue(
model.parts.any { part -> part.channelGrids.gridsByChannel.values.any { track -> track.axes.isNotEmpty() } },
"a parameter-bound CMO3 part keeps its keyform tracks",
)
} ?: println("modelA.cmo3 not present; skipping")
}
/**
* Every opacity value stored across a part's opacity track (empty when it has none).
*
* @param ChannelGrids channels The part's per-channel tracks.
* @return List<Float> The stored opacities, in cell order.
*/
private fun opacityValues(channels: ChannelGrids): List<Float> =
channels[FormChannel.OPACITY]?.cells?.mapNotNull { cell -> (cell.form as? ChannelValue.Scalar)?.value } ?: emptyList()
}
@@ -0,0 +1,81 @@
package org.umamo.interop.art
import org.umamo.format.FormatRegistry
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.art.analyzeAlpha
import java.io.File
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
/**
* Runs the bridge over every real layered file in the local corpus (PSD, CLIP, KRA), which is the
* only way to see what a reader actually emits - folder paths no group describes, weak keys that
* collide, text and empty layers - land on the model as the synthetic test says they should.
*
* Corpus-gated the way the readers' own tests are: every sample under `test/corpus/{psd,clip,krita}`
* found by walking up from the working directory, self-skipping with a printed line when none exist.
*/
class SourceArtImportCorpusTest {
private fun locateSamples(): List<File> {
var directory: File? = File(System.getProperty("user.dir"))
while (directory != null) {
val corpus = File(directory, "test/corpus")
if (corpus.isDirectory) {
return listOf("psd", "clip", "krita")
.flatMap { folder -> File(corpus, folder).listFiles { file -> file.isFile }.orEmpty().toList() }
.filter { file -> file.extension.lowercase() in setOf("psd", "clip", "kra") }
.sortedBy { file -> file.name }
}
directory = directory.parentFile
}
return emptyList()
}
@Test
fun everyCorpusArtworkImportsToARig() {
val samples = locateSamples()
if (samples.isEmpty()) {
println("no test/corpus artwork samples; skipping the artwork import corpus test")
return
}
for (sample in samples) {
checkSample(sample)
}
}
private fun checkSample(sample: File) {
val bytes = sample.readBytes()
val codec = assertNotNull(FormatRegistry.detect(bytes, sample.name), "${sample.name}: detected")
val art = codec.read(bytes) as SourceArt
val result = SourceArtImport.fromSourceArt(art, ArtSourceDescriptor(sample.name, sample.path, codec.kind.extension))
val puppet = result.puppet
// One drawable per raster layer with art in it, named after the layer, top-most first.
val expectedNames =
art.layers
.sortedBy { layer -> layer.order }
.filter { layer -> layer.kind == SourceLayerKind.Raster && layer.analyzeAlpha() != null }
.map { layer -> layer.name }
assertEquals(expectedNames, puppet.drawables.map { drawable -> drawable.name }, "${sample.name}: drawables")
assertEquals(puppet.drawables.size, puppet.drawables.map { drawable -> drawable.id }.toSet().size, "${sample.name}: drawable ids are unique")
assertEquals(puppet.atlas.tiles.size, puppet.atlas.tiles.map { tile -> tile.id }.toSet().size, "${sample.name}: tile ids are unique")
// Every drawable samples a tile whose size is its layer's raster, bound to that layer's key.
for (drawable in puppet.drawables) {
val tile = assertNotNull(puppet.atlas.tileById[assertNotNull(drawable.atlasTileId)], "${sample.name}: ${drawable.name} has a tile")
val raster = assertNotNull(result.rasterByTile[tile.id], "${sample.name}: ${drawable.name} has pixels")
assertEquals(raster.width, tile.width, "${sample.name}: ${drawable.name} tile width")
assertEquals(raster.height, tile.height, "${sample.name}: ${drawable.name} tile height")
val source = assertNotNull(tile.source, "${sample.name}: ${drawable.name} is bound to its source layer")
assertEquals(puppet.sources.single().id, source.sourceId)
assertTrue(puppet.sources.single().layers.any { entry -> entry.key == source.layerKey }, "${sample.name}: the binding names an inventory layer")
}
assertEquals(art.layers.size, puppet.sources.single().layers.size, "${sample.name}: the inventory lists every layer")
assertTrue(puppet.parts.size >= art.groups.size, "${sample.name}: every described folder is a part")
assertEquals(art.widthPx.toFloat(), puppet.canvasWidth, "${sample.name}: canvas width")
println("imported ${sample.name}: ${puppet.drawables.size} drawables, ${puppet.parts.size} parts, ${result.notices.size} notes")
}
}
@@ -0,0 +1,500 @@
package org.umamo.interop.cmo3
import org.junit.Assume
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.model.custom.CModelImage
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.cmo3.model.gen.CModelImageGroup
import org.umamo.format.cmo3.model.gen.CTextureAtlas
import org.umamo.format.cmo3.model.gen.CTextureManager
import org.umamo.format.cmo3.model.gen.GTransform2
import org.umamo.format.cmo3.model.gen.ModelImageEntry
import org.umamo.format.cmo3.model.identity.Guid
import org.umamo.format.cmo3.model.type.CAffine
import org.umamo.format.cmo3.model.type.GVector2
import org.umamo.format.psd.PsdReader
import org.umamo.runtime.model.AtlasPlacement
import org.umamo.runtime.model.atlasBindingFor
import org.umamo.runtime.model.atlasPixelOf
import org.umamo.runtime.model.layerUvsFromAtlasUvs
import java.io.File
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
/**
* Validates the atlas-placement recovery convention against real files, which is what keeps a sign or
* ordering error from passing unnoticed: a wrong rotation sign still round-trips (the synthetic tests
* in SourceArtRastersTest cannot catch it), and it is invisible on the axis-aligned majority - only the
* corpus's genuinely rotated packings expose it.
*
* The check is the format's own documented composition (docs/format/CMO3.md §6): a model image is
* upright canvas-space art, so `atlasLocalToCanvasTransform` composed with
* `materialLocalToAtlasTransform` must reproduce `_materialLocalToCanvasTransform` exactly. Reading
* our AtlasPlacement out of the entry and pushing a point through [atlasPixelOf] must therefore land
* where the file's own two affines say it lands.
*
* Gated on `cmo3.probe` (the whole corpus, comma-separated; the build defaults it to the local corpus,
* and an explicit `-D` overrides that); self-skips by JUnit assumption when it names no readable file, so
* an unfed run reports skipped rather than green.
*/
class Cmo3AtlasIngestCorpusTest {
private companion object {
/**
* How much of a drawable's recovered mapping must land on its layer's frame. Generous, because
* an authored mesh reaching well past its art is normal; a mis-wired recovery overlaps by nothing
* at all, so anything short of total displacement still fails this decisively.
*/
const val MINIMUM_FRAME_OVERLAP = 0.25f
/**
* How far past its art a mesh may reach before that counts against the overlap, in layer pixels.
* The auto-mesh rings outside the opaque region (CMO3.md §6 measures ~20px per side on Erica) and
* authored meshes extend further for deformation coverage. A pixel quantity, deliberately: as a
* fraction the same margin is nothing on a 1021x1405 layer and everything on a 14x10 one.
*/
const val MESH_MARGIN_PIXELS = 32f
}
/**
* The fraction of a mapping's own bounding box that falls inside the layer's frame, that frame
* widened by [MESH_MARGIN_PIXELS] so a normal mesh margin does not read as a miss.
*
* @param FloatArray layerUvs The recovered layer-frame texture coordinates, interleaved (u, v).
* @param Int layerWidth The layer's width in pixels (converts the margin into this uv frame).
* @param Int layerHeight The layer's height in pixels.
* @return Float The overlapping fraction, 0 when the mapping misses the frame entirely.
*/
private fun frameOverlapFractionOf(layerUvs: FloatArray, layerWidth: Int, layerHeight: Int): Float {
var minU = Float.MAX_VALUE
var maxU = -Float.MAX_VALUE
var minV = Float.MAX_VALUE
var maxV = -Float.MAX_VALUE
var componentIndex = 0
while (componentIndex + 1 < layerUvs.size) {
minU = minOf(minU, layerUvs[componentIndex])
maxU = maxOf(maxU, layerUvs[componentIndex])
minV = minOf(minV, layerUvs[componentIndex + 1])
maxV = maxOf(maxV, layerUvs[componentIndex + 1])
componentIndex += 2
}
val spanU = maxU - minU
val spanV = maxV - minV
if (spanU <= 0f || spanV <= 0f) {
return 0f
}
val marginU = MESH_MARGIN_PIXELS / layerWidth
val marginV = MESH_MARGIN_PIXELS / layerHeight
val insideU = minOf(maxU, 1f + marginU) - maxOf(minU, -marginU)
val insideV = minOf(maxV, 1f + marginV) - maxOf(minV, -marginV)
if (insideU <= 0f || insideV <= 0f) {
return 0f
}
return (insideU * insideV) / (spanU * spanV)
}
/**
* Whether the mapping's bounding box fully covers the layer's frame, each edge allowed to fall
* short by [MESH_MARGIN_PIXELS].
*
* The second acceptance shape beside the overlap fraction: a converted document's layer is the
* crop TRIMMED to its opaque pixels, so a mesh with a wide transparent reach maps to a box many
* times the layer's area and the landing fraction goes small - while the box still sits squarely
* OVER the art. A mis-wired recovery displaces the box off the layer entirely and satisfies
* neither shape.
*
* @param FloatArray layerUvs The recovered layer-frame texture coordinates, interleaved (u, v).
* @param Int layerWidth The layer's width in pixels (converts the margin into this uv frame).
* @param Int layerHeight The layer's height in pixels.
* @return Boolean True when the mapping's box covers the layer's frame within the margin.
*/
private fun mappingCoversLayer(layerUvs: FloatArray, layerWidth: Int, layerHeight: Int): Boolean {
var minU = Float.MAX_VALUE
var maxU = -Float.MAX_VALUE
var minV = Float.MAX_VALUE
var maxV = -Float.MAX_VALUE
var componentIndex = 0
while (componentIndex + 1 < layerUvs.size) {
minU = minOf(minU, layerUvs[componentIndex])
maxU = maxOf(maxU, layerUvs[componentIndex])
minV = minOf(minV, layerUvs[componentIndex + 1])
maxV = maxOf(maxV, layerUvs[componentIndex + 1])
componentIndex += 2
}
val marginU = MESH_MARGIN_PIXELS / layerWidth
val marginV = MESH_MARGIN_PIXELS / layerHeight
return minU <= marginU && minV <= marginV && maxU >= 1f - marginU && maxV >= 1f - marginV
}
private fun elements(collection: Any?): List<Any?> =
when (collection) {
is Map<*, *> -> collection.values.toList()
is Iterable<*> -> collection.toList()
is Array<*> -> collection.toList()
else -> emptyList()
}
private fun corpusFiles(): List<File> =
(System.getProperty("cmo3.probe") ?: "")
.split(",")
.map { path -> path.trim() }
.filter { path -> path.isNotEmpty() }
.map { path -> File(path) }
.filter { file -> file.isFile }
/** Applies a CMO3 affine (m00 m01 m02 / m10 m11 m12) to a point. */
private fun applyAffine(affine: CAffine, x: Float, y: Float): FloatArray =
floatArrayOf(
affine.m00 * x + affine.m01 * y + affine.m02,
affine.m10 * x + affine.m11 * y + affine.m12,
)
/** Our AtlasPlacement as read out of one atlas entry, matching cmo3AtlasIngest's own reading. */
private fun placementOf(entry: ModelImageEntry, pageIndex: Int): AtlasPlacement? {
// CMO3: ModelImageEntry field materialLocalToAtlasTransform
val transform = entry.materialLocalToAtlasTransform as? GTransform2 ?: return null
val position = transform.position as? GVector2
val scale = transform.scale as? GVector2
return AtlasPlacement(
pageIndex = pageIndex,
positionX = position?.x ?: 0f,
positionY = position?.y ?: 0f,
scaleX = scale?.x ?: 1f,
scaleY = scale?.y ?: 1f,
rotationDegrees = transform.eulerAngle,
)
}
/**
* The store builder end to end on real documents: an art-bearing model must surface an inventory,
* bind its drawables to it, and land each bound drawable's recovered mapping ON its layer's art.
*
* Overlap, not containment, is the invariant. A mesh legitimately reaches past the art it samples -
* the auto-mesh rings outside the opaque region and an authored mesh often extends further still so
* deformation has coverage (the corpus's forearms reach ~140px past a 576x646 layer) - and the UV
* editor draws unclipped for exactly that reason. What a mis-wired recovery does instead is land the
* mesh somewhere else entirely: applying a page-space placement to uvs that already address their art
* threw modelA's meshes thousands of pixels off, overlapping their layer not at all.
*/
@Test
fun storeBindsCorpusDrawablesToArtTheirMappingsLandOn() {
val files = corpusFiles()
Assume.assumeTrue("[layer-store] no cmo3.probe corpus models", files.isNotEmpty())
var filesWithLayers = 0
var boundDrawables = 0
var checkedMappings = 0
var worstOverlap = 1f
var missedMappings = 0
val failures = mutableListOf<String>()
for (file in files) {
val root = Cmo3.read(file).root as? CModelSource ?: continue
val puppet = Cmo3Import.fromModelSource(root)
if (puppet.atlas.isEmpty) {
continue
}
filesWithLayers++
for (drawable in puppet.drawables) {
val binding = puppet.atlasBindingFor(drawable) ?: continue
boundDrawables++
val layer = puppet.atlas.tileById[drawable.atlasTileId] ?: continue
val uvs = drawable.mesh?.uvs ?: continue
if (uvs.isEmpty()) {
continue
}
val layerUvs = layerUvsFromAtlasUvs(uvs, binding, layer.width, layer.height) ?: continue
checkedMappings++
val overlap = frameOverlapFractionOf(layerUvs, layer.width, layer.height)
// Either shape says the mapping lands ON its art: mostly inside the layer, or fully
// covering it (a trim-tight converted crop under a wide-reaching mesh).
val landsOnLayer = overlap >= MINIMUM_FRAME_OVERLAP || mappingCoversLayer(layerUvs, layer.width, layer.height)
worstOverlap = minOf(worstOverlap, overlap)
if (!landsOnLayer) {
missedMappings++
}
if (!landsOnLayer && failures.size < 10) {
failures.add(
"${file.name} ${drawable.id.raw} -> ${layer.name}: only $overlap of its mapping lands on the " +
"layer (${layer.width}x${layer.height}) on a ${binding.pageWidth}x${binding.pageHeight} " +
"page, placement=${binding.placement}",
)
}
}
}
println(
"[layer-store] $filesWithLayers art-bearing files, $boundDrawables bound drawables, " +
"$checkedMappings mappings checked, $missedMappings below the $MINIMUM_FRAME_OVERLAP overlap bound, " +
"least overlap $worstOverlap",
)
assertTrue(filesWithLayers > 0, "no corpus file surfaced any source layers; the builder walk is broken")
assertTrue(boundDrawables > 0, "no drawable bound to a source layer; the drawable join is broken")
assertTrue(checkedMappings > 0, "no uv mapping was checked; the recovery is untested against real meshes")
assertTrue(failures.isEmpty(), "recovered mappings do not land on their layer:\n" + failures.joinToString("\n"))
}
/**
* Toggling the source-artwork display changes nothing about how coordinates are read.
*
* The display mode picks which texture is sampled; the frame the stored coordinates live in is a
* fact of the file. Deriving the frame from the mode passed every import-time check - the two agree
* there - and broke the moment a rigger flipped the switch, drawing every mesh in the layer view at
* its atlas position instead of on its artwork. Checked on real documents in BOTH modes, because
* the corpus carries files saved each way.
*/
@Test
fun theDisplayModeNeverReinterpretsCorpusCoordinates() {
val files = corpusFiles()
Assume.assumeTrue("[layer-toggle] no cmo3.probe corpus models", files.isNotEmpty())
var checkedFiles = 0
var checkedBindings = 0
var placedBindings = 0
val failures = mutableListOf<String>()
for (file in files) {
val root = Cmo3.read(file).root as? CModelSource ?: continue
val asSaved = Cmo3Import.fromModelSource(root)
if (asSaved.atlas.isEmpty) {
continue
}
checkedFiles++
val toggled = asSaved.copy(rendersFromSourceLayers = !asSaved.rendersFromSourceLayers)
for (drawable in asSaved.drawables) {
val before = asSaved.atlasBindingFor(drawable)
val after = toggled.atlasBindingFor(drawable)
checkedBindings++
if (before?.placement != null) {
placedBindings++
}
if (before != after && failures.size < 10) {
failures.add("${file.name} ${drawable.id.raw}: $before became $after when the display flipped")
}
}
}
println(
"[layer-toggle] $checkedFiles art-bearing files, $checkedBindings bindings held across the toggle, " +
"$placedBindings of them placed",
)
assertTrue(checkedFiles > 0, "no corpus file surfaced an atlas; the walk is broken")
assertTrue(placedBindings > 0, "no placed binding was checked; the toggle guard would pass vacuously")
assertTrue(failures.isEmpty(), "the display mode reinterpreted coordinates:\n" + failures.joinToString("\n"))
}
@Test
fun placementForwardMatchesTheFormatsOwnComposition() {
val files = corpusFiles()
Assume.assumeTrue("[layer-recovery] no cmo3.probe corpus models", files.isNotEmpty())
// Sample points spanning a plausible layer extent, so a rotation error shows up as a mismatch
// rather than cancelling at the origin.
val samplePoints = listOf(0f to 0f, 137f to 0f, 0f to 251f, 137f to 251f)
val sampleExtent = 251f
// The composition cannot be exact: the entry's scale and the atlas-to-canvas fit are separately
// rounded floats, so their product misses identity by a small relative epsilon that the art's own
// extent multiplies up (modelA's worst case measures ~1e-3 relative). A model image is upright
// canvas-space art - its material-to-canvas is a pure translation - so layer units ARE canvas
// units here and the bound is simply proportional to the sample extent. This stays a razor-sharp
// convention check regardless: a wrong rotation sign or operand order displaces a sample by the
// extent itself (hundreds of units), three orders of magnitude past this.
val tolerance = 0.05f + 2e-3f * sampleExtent
var checkedEntries = 0
var checkedRotated = 0
var checkedScaled = 0
var worstResidual = 0f
var worstRotatedResidual = 0f
val failures = mutableListOf<String>()
for (file in files) {
val root = Cmo3.read(file).root as? CModelSource ?: continue
val textureManager = root.textureManager as? CTextureManager ?: continue
val modelImagesByGuid =
elements(textureManager._modelImageGroups)
.filterIsInstance<CModelImageGroup>()
.flatMap { group -> elements(group._modelImages).filterIsInstance<CModelImage>() }
.mapNotNull { image -> (image.guid as? Guid)?.uuid?.let { uuid -> uuid to image } }
.toMap()
for ((pageIndex, atlas) in elements(textureManager._textureAtlases).filterIsInstance<CTextureAtlas>().withIndex()) {
for (entry in elements(atlas.modelImages).filterIsInstance<ModelImageEntry>()) {
val guid = (entry.modelImageGuid as? Guid)?.uuid ?: continue
val modelImage = modelImagesByGuid[guid] ?: continue
// CMO3: ModelImageEntry field atlasLocalToCanvasTransform / CModelImage field
// _materialLocalToCanvasTransform - the two halves of the documented composition.
val atlasToCanvas = entry.atlasLocalToCanvasTransform as? CAffine ?: continue
val materialToCanvas = modelImage._materialLocalToCanvasTransform as? CAffine ?: continue
val placement = placementOf(entry, pageIndex) ?: continue
checkedEntries++
if (placement.rotationDegrees != 0f) {
checkedRotated++
}
if (placement.scaleX != 1f || placement.scaleY != 1f) {
checkedScaled++
}
for ((layerX, layerY) in samplePoints) {
val viaPlacement = atlasPixelOf(placement, layerX, layerY)
val throughFile = applyAffine(atlasToCanvas, viaPlacement[0], viaPlacement[1])
val expected = applyAffine(materialToCanvas, layerX, layerY)
val residual =
maxOf(
kotlin.math.abs(throughFile[0] - expected[0]),
kotlin.math.abs(throughFile[1] - expected[1]),
)
worstResidual = maxOf(worstResidual, residual)
if (placement.rotationDegrees != 0f) {
worstRotatedResidual = maxOf(worstRotatedResidual, residual)
}
if (residual > tolerance && failures.size < 10) {
failures.add(
"${file.name} guid=$guid angle=${placement.rotationDegrees} " +
"scale=(${placement.scaleX}, ${placement.scaleY}) at ($layerX, $layerY): " +
"placement->file (${throughFile[0]}, ${throughFile[1]}) vs " +
"declared (${expected[0]}, ${expected[1]}), residual $residual",
)
}
}
}
}
}
println(
"[layer-recovery] composed $checkedEntries placements ($checkedRotated rotated, $checkedScaled scaled) " +
"across ${files.size} corpus files; worst residual $worstResidual (rotated: $worstRotatedResidual), " +
"tolerance $tolerance",
)
assertTrue(checkedEntries > 0, "no atlas placements were checked; the corpus walk is broken")
// Non-vacuity: an axis-aligned-only run would pass under EITHER rotation sign, so the rotated
// packings must actually be present for this test to mean anything.
assertTrue(checkedRotated > 0, "no rotated placement was checked; the rotation convention is unverified")
assertTrue(
failures.isEmpty(),
"placement composition disagrees with the file's own affines:\n" + failures.joinToString("\n"),
)
// The rotated packings are what the convention actually hinges on, so hold them to the same bound
// explicitly rather than letting them hide inside an aggregate that the axis-aligned majority passes.
assertTrue(
worstRotatedResidual <= tolerance,
"a rotated placement composes to $worstRotatedResidual, past the $tolerance bound",
)
}
/**
* Every CMO3-origin tile that recovers a source binding names one of the layered images the texture
* manager lists, keyed the way the inventory walk keys the decomposed tree: by the Photoshop layer
* id the editor recorded ("lyid:", stable unless suffixed for a duplicate), else by name ("name:",
* never stable) - and the model must say which, rather than pass a name off as a stable key.
*/
@Test
fun corpusTilesBindToTheLayeredImagesTheEditorDecomposed() {
val files = corpusFiles()
Assume.assumeTrue("cmo3.probe names no readable file", files.isNotEmpty())
for (file in files) {
val puppet = Cmo3Import.fromModelSource(Cmo3.read(file.readBytes()).root as CModelSource)
if (puppet.atlas.tiles.isEmpty()) {
// The blank skeleton: no PSD was ever imported into it, so there is nothing to bind.
println("${file.name}: no tiles, nothing to bind")
continue
}
val sourceIds = puppet.sources.map { source -> source.id }.toSet()
assertTrue(puppet.sources.isNotEmpty(), "${file.name}: the layered images the editor imported are listed")
assertTrue(puppet.sources.all { source -> source.format.isNotEmpty() }, "${file.name}: every source records its format")
var bound = 0
for (tile in puppet.atlas.tiles) {
val source = tile.source ?: continue
bound++
assertTrue(source.sourceId in sourceIds, "${file.name}: tile '${tile.name}' binds to a listed source")
val byLayerId = source.layerKey.startsWith("lyid:")
assertTrue(byLayerId || source.layerKey.startsWith("name:"), "${file.name}: tile '${tile.name}' is keyed by Photoshop layer id or by name")
assertEquals(byLayerId && '#' !in source.layerKey, source.stableKey, "${file.name}: a layer-id key is stable, a name or suffixed key is not")
}
assertTrue(bound > 0, "${file.name}: at least one tile recovers its source layer")
// The inventory walk lists the decomposed layer tree, and every binding names one of its rows
// under the same key - the Sources space shows a stray binding otherwise.
val inventoryKeysBySource = puppet.sources.associate { source -> source.id to source.layers.mapTo(HashSet()) { layer -> layer.key } }
assertTrue(puppet.sources.any { source -> source.layers.isNotEmpty() }, "${file.name}: the layered images list their layers")
for (source in puppet.sources) {
// The Sources space keys its rows on the layer key; Erica alone has twenty layers named "1".
assertEquals(source.layers.size, inventoryKeysBySource.getValue(source.id).size, "${file.name}: '${source.name}' lists one key per layer")
}
var stray = 0
for (tile in puppet.atlas.tiles) {
val source = tile.source ?: continue
if (source.layerKey !in inventoryKeysBySource[source.sourceId].orEmpty()) {
stray++
}
}
assertEquals(0, stray, "${file.name}: bindings that name no inventory row")
println("${file.name}: ${puppet.sources.size} source(s), ${puppet.sources.sumOf { source -> source.layers.size }} inventory rows, $bound of ${puppet.atlas.tiles.size} tiles bound")
}
}
/**
* The walk's layer-id keys are the PSD reader's own: for every corpus CMO3 with a same-named PSD
* beside it (test/corpus/psd/<name>.psd), the layered image the editor decomposed from that PSD
* shares its "lyid:" keys with a fresh read of the file, and each shared key names the same layer in
* both. That is the identity a CMO3-origin document re-imports against its PSD on, so a numeric
* coincidence would be caught by the name check and a wrong byte order by the share count.
*/
@Test
fun cmo3LayerIdsAreThePsdReadersKeys() {
val pairs =
corpusFiles().mapNotNull { cmo3File ->
val psdFile = File(cmo3File.parentFile?.parentFile, "psd/${cmo3File.nameWithoutExtension}.psd")
if (psdFile.isFile) cmo3File to psdFile else null
}
Assume.assumeTrue("no corpus CMO3 has a same-named PSD beside it", pairs.isNotEmpty())
for ((cmo3File, psdFile) in pairs) {
val puppet = Cmo3Import.fromModelSource(Cmo3.read(cmo3File.readBytes()).root as CModelSource)
val psdNameByKey = PsdReader.read(psdFile.readBytes()).layers.associate { layer -> layer.id.raw to layer.name }
// The decomposed image with the most layers is the model's main PSD; its recorded name is the
// artist's file name, not the corpus's, so it cannot be matched by name.
val source = assertNotNull(puppet.sources.filter { source -> source.format == "psd" }.maxByOrNull { source -> source.layers.size }, "${cmo3File.name}: a decomposed PSD is listed")
val layerIdRows = source.layers.filter { layer -> layer.key.startsWith("lyid:") }
assertTrue(layerIdRows.isNotEmpty(), "${cmo3File.name}: the editor recorded Photoshop layer ids")
var shared = 0
for (row in layerIdRows) {
val psdName = psdNameByKey[row.key] ?: continue
shared++
assertEquals(psdName, row.name, "${cmo3File.name}: ${row.key} names the same layer in the CMO3 and the PSD")
}
assertTrue(shared * 2 >= layerIdRows.size, "${cmo3File.name}: the PSD shares most of the CMO3's layer ids ($shared of ${layerIdRows.size})")
println("${cmo3File.name} vs ${psdFile.name}: ${layerIdRows.size} layer-id rows, $shared shared with the PSD reader, every name agrees")
}
}
/**
* The decomposed layer tree reads back as source art keyed exactly as the bindings are: every
* listed file yields a document whose layer keys are the inventory's, and each raster layer's
* pixels decode at its recorded bounds - the pixels a relink pulls when the file itself is gone.
*/
@Test
fun decomposedLayersReadBackAsSourceArt() {
val files = corpusFiles()
Assume.assumeTrue("cmo3.probe names no readable file", files.isNotEmpty())
var decodedLayers = 0
for (file in files) {
val cmo3 = Cmo3.read(file.readBytes())
val root = cmo3.root as CModelSource
val puppet = Cmo3Import.fromModelSource(root)
for (source in puppet.sources) {
val art = assertNotNull(cmo3SourceArtOf(root, source.id) { resource -> cmo3.extractLayerPng(resource) }, "${file.name}: '${source.name}' reads back")
assertEquals(source.layers.map { layer -> layer.key }, art.layers.map { layer -> layer.id.raw }, "${file.name}: '${source.name}' keys as the inventory does")
for ((row, layer) in source.layers.zip(art.layers)) {
assertEquals(row.left, layer.bounds.left)
assertEquals(row.top, layer.bounds.top)
if (layer.kind != SourceLayerKind.Raster) {
continue
}
assertEquals(row.width, layer.raster.width, "${file.name}: '${layer.name}' decodes at its bounds' width")
assertEquals(row.height, layer.raster.height, "${file.name}: '${layer.name}' decodes at its bounds' height")
decodedLayers++
}
}
}
assertTrue(decodedLayers > 0, "some raster layer decoded")
println("decomposed art: $decodedLayers layer(s) decoded across ${files.size} file(s)")
}
}
@@ -0,0 +1,133 @@
package org.umamo.interop.cmo3
import org.umamo.format.cmo3.model.type.CAffine
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
/**
* The atlas-page-to-canvas placement fit behind CTextureInput_TextureAtlasRegion's
* inputImageLocalToCanvasTransform: a least-squares affine from uv*pageSize onto base positions,
* recovered exactly for Cubism-authored (exactly affine) mappings and degraded gracefully for
* degenerate meshes.
*/
class Cmo3AtlasPlacementFitTest {
/**
* Applies the affine to a page-frame point.
*
* @param CAffine transform The fitted transform.
* @param Double pageX Page-frame x.
* @param Double pageY Page-frame y.
* @return Pair The mapped canvas point.
*/
private fun apply(transform: CAffine, pageX: Double, pageY: Double): Pair<Double, Double> =
Pair(
transform.m00 * pageX + transform.m01 * pageY + transform.m02,
transform.m10 * pageX + transform.m11 * pageY + transform.m12,
)
@Test
fun recoversAnExactAffineMappingIncludingAFlip() {
// canvasX = 0.002*pageX - 1.5; canvasY = -0.002*pageY + 3.25 (a y-flip, the MOC3 case).
val uvs = floatArrayOf(0.1f, 0.2f, 0.6f, 0.2f, 0.1f, 0.9f, 0.6f, 0.9f, 0.35f, 0.55f)
val pageWidth = 4096
val pageHeight = 2048
val positions =
FloatArray(uvs.size) { index ->
val vertexIndex = index / 2
if (index % 2 == 0) {
(0.002 * uvs[2 * vertexIndex] * pageWidth - 1.5).toFloat()
} else {
(-0.002 * uvs[2 * vertexIndex + 1] * pageHeight + 3.25).toFloat()
}
}
val transform = fitAtlasPageToCanvasTransform(uvs, positions, pageWidth, pageHeight)
assertEquals(0.002f, transform.m00, 1e-6f, "x scale")
assertEquals(0f, transform.m01, 1e-6f, "x shear")
assertEquals(-1.5f, transform.m02, 1e-4f, "x offset")
assertEquals(0f, transform.m10, 1e-6f, "y shear")
assertEquals(-0.002f, transform.m11, 1e-6f, "y scale (flip)")
assertEquals(3.25f, transform.m12, 1e-4f, "y offset")
}
@Test
fun recoversAQuarterTurnPackingFarFromThePageOrigin() {
// The packer rotated this patch a quarter turn, and it sits ~12000 px out on a 16384-square
// page while spanning only ~700. Both halves matter: an origin-referenced normal system is
// swamped by the offset and reads as singular, and what it degrades to - a per-axis
// regression - has no off-diagonal term to put the rotation in, so the patch comes back
// squashed onto the wrong axis (the misplaced-FACE report, off by ~380 px).
val pageWidth = 16384
val pageHeight = 16384
val patchOriginX = 12.0
val patchOriginY = 11782.0
// canvas = rotate(-90 deg) * (page - patchOrigin) + canvasOrigin.
val canvasOriginX = 1937.0
val canvasOriginY = 1166.0
val uvs = FloatArray(2 * 16)
val positions = FloatArray(2 * 16)
var vertexIndex = 0
for (columnIndex in 0 until 4) {
for (rowIndex in 0 until 4) {
val pageX = patchOriginX + columnIndex * 247.0
val pageY = patchOriginY + rowIndex * 187.0
uvs[2 * vertexIndex] = (pageX / pageWidth).toFloat()
uvs[2 * vertexIndex + 1] = (pageY / pageHeight).toFloat()
positions[2 * vertexIndex] = (canvasOriginX + (pageY - patchOriginY)).toFloat()
positions[2 * vertexIndex + 1] = (canvasOriginY - (pageX - patchOriginX)).toFloat()
vertexIndex += 1
}
}
val transform = fitAtlasPageToCanvasTransform(uvs, positions, pageWidth, pageHeight)
assertEquals(0f, transform.m00, 1e-3f, "x from page x (a quarter turn decouples them)")
assertEquals(1f, transform.m01, 1e-3f, "x from page y")
assertEquals(-1f, transform.m10, 1e-3f, "y from page x")
assertEquals(0f, transform.m11, 1e-3f, "y from page y")
for (checkedVertex in 0 until 16) {
val (canvasX, canvasY) =
apply(transform, uvs[2 * checkedVertex] * pageWidth.toDouble(), uvs[2 * checkedVertex + 1] * pageHeight.toDouble())
assertEquals(positions[2 * checkedVertex].toDouble(), canvasX, 1.0, "x of vertex $checkedVertex")
assertEquals(positions[2 * checkedVertex + 1].toDouble(), canvasY, 1.0, "y of vertex $checkedVertex")
}
}
@Test
fun degenerateVerticalSpanStillFitsTheHorizontalAxis() {
// All v identical: the page cloud spans one direction, so the second column is unconstrained;
// x must still fit exactly and y must land on the centroid.
val uvs = floatArrayOf(0.0f, 0.5f, 0.25f, 0.5f, 1.0f, 0.5f)
val positions = floatArrayOf(10f, 7f, 12.5f, 7f, 20f, 7f)
val transform = fitAtlasPageToCanvasTransform(uvs, positions, 100, 100)
for (vertexIndex in 0 until 3) {
val (canvasX, canvasY) = apply(transform, uvs[2 * vertexIndex] * 100.0, uvs[2 * vertexIndex + 1] * 100.0)
assertEquals(positions[2 * vertexIndex].toDouble(), canvasX, 1e-3, "x of vertex $vertexIndex")
assertEquals(7.0, canvasY, 1e-3, "y of vertex $vertexIndex")
}
// The unconstrained direction takes its identity value, never zero: the editor inverts this
// transform to draw the mesh over its patch, and a singular one has no inverse.
val determinant = transform.m00 * transform.m11 - transform.m01 * transform.m10
assertTrue(kotlin.math.abs(determinant) > 1e-6f, "the fitted affine stays invertible, got determinant $determinant")
}
@Test
fun singlePointMapsByCentroidTranslation() {
val transform = fitAtlasPageToCanvasTransform(floatArrayOf(0.5f, 0.25f), floatArrayOf(42f, -7f), 200, 400)
val (canvasX, canvasY) = apply(transform, 100.0, 100.0)
assertEquals(42.0, canvasX, 1e-3)
assertEquals(-7.0, canvasY, 1e-3)
}
@Test
fun emptyMeshYieldsIdentity() {
val transform = fitAtlasPageToCanvasTransform(FloatArray(0), FloatArray(0), 1024, 1024)
assertTrue(
transform.m00 == 1f &&
transform.m01 == 0f &&
transform.m02 == 0f &&
transform.m10 == 0f &&
transform.m11 == 1f &&
transform.m12 == 0f,
"identity for an empty mesh",
)
}
}
@@ -0,0 +1,238 @@
package org.umamo.interop.cmo3
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
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.PuppetModel
import org.umamo.runtime.model.RuntimeTarget
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertNotEquals
import kotlin.test.assertTrue
class Cmo3AtlasUndedupTest {
private val pageSize = 32
private val uvs = floatArrayOf(4f / 32f, 4f / 32f, 28f / 32f, 4f / 32f, 4f / 32f, 28f / 32f, 28f / 32f, 28f / 32f)
private val indices = intArrayOf(0, 1, 2, 1, 2, 3)
private fun page(): Cmo3Conversion.AtlasPage {
val rgba = ByteArray(pageSize * pageSize * 4)
for (rowIndex in 12 until 19) {
for (columnIndex in 10 until 15) {
rgba.fill(0xFF.toByte(), (rowIndex * pageSize + columnIndex) * 4, (rowIndex * pageSize + columnIndex) * 4 + 4)
}
}
return Cmo3Conversion.AtlasPage(PngCodec.write(RasterImage(pageSize, pageSize, rgba)), pageSize, pageSize)
}
private fun drawable(id: String, positions: FloatArray): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions = positions, uvs = uvs.copyOf(), indices = indices.copyOf()),
geometryGrid = null,
)
private fun puppet(drawables: List<Drawable>): PuppetModel =
PuppetModel(
parameters = emptyList(),
parts = emptyList(),
deformers = emptyList(),
drawables = drawables,
rootChildren = drawables.map { OrgChild.Drawable(it.id) },
rootPartId = null,
canvasWidth = 200f,
canvasHeight = 200f,
worldOriginX = 100f,
worldOriginZ = -100f,
runtimeTarget = RuntimeTarget.Cubism53,
)
@Test
fun mirroredTwinsGetOwnSlots() {
val straightPositions = FloatArray(uvs.size) { index -> uvs[index] * pageSize }
val shiftedPositions = FloatArray(uvs.size) { index -> uvs[index] * pageSize + if (index % 2 == 0) 50f else 0f }
val model = puppet(listOf(drawable("TwinA", straightPositions), drawable("TwinB", shiftedPositions)))
val pageIndexByDrawableId = mapOf("TwinA" to 0, "TwinB" to 0)
val result = Cmo3AtlasUndedup.undeduplicate(model, listOf(page()), pageIndexByDrawableId)
assertEquals(listOf("TwinB"), result.duplicatedDrawableIds, "the second placement duplicates")
assertEquals(2, result.pages.size, "a synthesized page is appended")
assertEquals(0, result.pageIndexByDrawableId.getValue("TwinA"), "the first placement keeps its page")
assertEquals(1, result.pageIndexByDrawableId.getValue("TwinB"), "the duplicate moves to the new page")
val twinA = result.puppet.drawables.single { it.id.raw == "TwinA" }
assertContentEquals(uvs, twinA.mesh?.uvs, "the first placement keeps its uvs")
// The remapped uvs must sample the same pixels on the new page as the originals did on the
// old page.
val twinB = result.puppet.drawables.single { it.id.raw == "TwinB" }
val newUvs = twinB.mesh?.uvs ?: error("twin B lost its mesh")
val sourcePage = PngCodec.read(page().pngBytes)
val extraPage = PngCodec.read(result.pages[1].pngBytes)
var componentIndex = 0
while (componentIndex + 1 < uvs.size) {
// Sample just inside the quad corner so both lookups stay in range.
val sourceX = (uvs[componentIndex] * pageSize).toInt().coerceIn(0, pageSize - 1)
val sourceY = (uvs[componentIndex + 1] * pageSize).toInt().coerceIn(0, pageSize - 1)
val newX = (newUvs[componentIndex] * extraPage.width).toInt().coerceIn(0, extraPage.width - 1)
val newY = (newUvs[componentIndex + 1] * extraPage.height).toInt().coerceIn(0, extraPage.height - 1)
// Compare a pixel INSIDE the block region via the same offset from the quad corner.
val insideSourceX = sourceX + (12 - 4)
val insideSourceY = sourceY + (14 - 4)
val insideNewX = newX + (12 - 4)
val insideNewY = newY + (14 - 4)
if (insideSourceX in 0 until pageSize &&
insideSourceY in 0 until pageSize &&
insideNewX in 0 until extraPage.width &&
insideNewY in 0 until extraPage.height
) {
assertEquals(
sourcePage.rgba[(insideSourceY * pageSize + insideSourceX) * 4 + 3],
extraPage.rgba[(insideNewY * extraPage.width + insideNewX) * 4 + 3],
"pixel content under the remapped uvs matches",
)
}
componentIndex += 2
}
// The block itself must be present somewhere opaque on the synthesized page.
assertTrue(extraPage.rgba.indices.step(4).any { offset -> extraPage.rgba[offset + 3].toInt() != 0 }, "the extra page carries pixels")
}
@Test
fun coLocatedDuplicatesAreNotSplit() {
val positions = FloatArray(uvs.size) { index -> uvs[index] * pageSize }
val model = puppet(listOf(drawable("VariantA", positions), drawable("VariantB", positions.copyOf())))
val result = Cmo3AtlasUndedup.undeduplicate(model, listOf(page()), mapOf("VariantA" to 0, "VariantB" to 0))
assertTrue(result.duplicatedDrawableIds.isEmpty(), "co-located duplicates share their slot")
assertEquals(1, result.pages.size, "no synthesized page")
assertEquals(model, result.puppet, "the puppet passes through untouched")
}
/**
* A 64 x 64 page with two slots - one block in each - so two independent twin pairs share one
* synthesized page.
*/
private val wideSize = 64
private val slotAUvs = floatArrayOf(4f / 64f, 4f / 64f, 28f / 64f, 4f / 64f, 4f / 64f, 28f / 64f, 28f / 64f, 28f / 64f)
private val slotBUvs = floatArrayOf(36f / 64f, 36f / 64f, 60f / 64f, 36f / 64f, 36f / 64f, 60f / 64f, 60f / 64f, 60f / 64f)
private fun widePage(blocks: List<IntArray>): Cmo3Conversion.AtlasPage {
val rgba = ByteArray(wideSize * wideSize * 4)
for (block in blocks) {
for (rowIndex in block[1] until block[3]) {
for (columnIndex in block[0] until block[2]) {
val offset = (rowIndex * wideSize + columnIndex) * 4
rgba[offset] = block[4].toByte()
rgba[offset + 1] = (columnIndex * 3).toByte()
rgba[offset + 2] = (rowIndex * 5).toByte()
rgba[offset + 3] = 0xFF.toByte()
}
}
}
return Cmo3Conversion.AtlasPage(PngCodec.write(RasterImage(wideSize, wideSize, rgba)), wideSize, wideSize)
}
private fun drawableOver(id: String, slotUvs: FloatArray, shiftX: Float): Drawable =
Drawable(
id = DrawableId(id),
name = id,
parentDeformerId = null,
blendMode = BlendMode.Normal,
maskedBy = emptyList(),
mesh = DrawableMesh(positions = FloatArray(slotUvs.size) { index -> slotUvs[index] * wideSize + if (index % 2 == 0) shiftX else 0f }, uvs = slotUvs.copyOf(), indices = indices.copyOf()),
geometryGrid = null,
)
/**
* Every pixel of a duplicated drawable's patch rect, transparent margin included, sits under its
* remapped uvs exactly as it sat under the originals: the reserve keeps the margin clear and
* nothing is extruded into it.
*/
private fun assertPatchCarriedWhole(drawableId: String, result: Cmo3AtlasUndedup.Result, sourcePage: Cmo3Conversion.AtlasPage, slotUvs: FloatArray) {
val drawable = result.puppet.drawables.single { candidate -> candidate.id.raw == drawableId }
val newUvs = drawable.mesh?.uvs ?: error("$drawableId lost its mesh")
val newPage = PngCodec.read(result.pages[result.pageIndexByDrawableId.getValue(drawableId)].pngBytes)
val source = PngCodec.read(sourcePage.pngBytes)
val rect = Cmo3ImageChainBuilder.patchRectOf(slotUvs, sourcePage.width, sourcePage.height)!!
// The remap is a whole-pixel translation: read it off the first vertex.
val deltaX = Math.round(newUvs[0] * newPage.width - slotUvs[0] * sourcePage.width)
val deltaY = Math.round(newUvs[1] * newPage.height - slotUvs[1] * sourcePage.height)
for (rowIndex in rect[1] until rect[3]) {
for (columnIndex in rect[0] until rect[2]) {
val sourceOffset = (rowIndex * source.width + columnIndex) * 4
val newOffset = ((rowIndex + deltaY) * newPage.width + columnIndex + deltaX) * 4
for (channel in 0 until 4) {
assertEquals(source.rgba[sourceOffset + channel], newPage.rgba[newOffset + channel], "$drawableId pixel ($columnIndex, $rowIndex) channel $channel")
}
}
}
}
@Test
fun severalTwinsPackOntoOnePageAndEachKeepsItsWholePatch() {
val page = widePage(listOf(intArrayOf(10, 12, 15, 19, 40), intArrayOf(44, 40, 50, 47, 90)))
val model =
puppet(
listOf(
drawableOver("A1", slotAUvs, 0f),
drawableOver("A2", slotAUvs, 50f),
drawableOver("B1", slotBUvs, 0f),
drawableOver("B2", slotBUvs, 70f),
),
)
val pageIndexByDrawableId = mapOf("A1" to 0, "A2" to 0, "B1" to 0, "B2" to 0)
val result = Cmo3AtlasUndedup.undeduplicate(model, listOf(page), pageIndexByDrawableId)
assertEquals(listOf("A2", "B2"), result.duplicatedDrawableIds.sorted())
assertTrue(result.sharedDrawableIds.isEmpty())
assertEquals(2, result.pages.size, "both further placements share one synthesized page")
assertEquals(1, result.pageIndexByDrawableId.getValue("A2"))
assertEquals(1, result.pageIndexByDrawableId.getValue("B2"))
assertEquals(0, result.pageIndexByDrawableId.getValue("A1"))
assertEquals(0, result.pageIndexByDrawableId.getValue("B1"))
assertPatchCarriedWhole("A2", result, page, slotAUvs)
assertPatchCarriedWhole("B2", result, page, slotBUvs)
val a2 = result.puppet.drawables.single { drawable -> drawable.id.raw == "A2" }.mesh!!.uvs
val b2 = result.puppet.drawables.single { drawable -> drawable.id.raw == "B2" }.mesh!!.uvs
assertNotEquals(a2[0] to a2[1], b2[0] to b2[1], "the two patches landed apart")
val synthesized = PngCodec.read(result.pages[1].pngBytes)
assertTrue(synthesized.width <= wideSize && synthesized.height <= wideSize, "the page shrinks to its content")
// Deterministic: the same inputs pack to the same bytes and the same remaps.
val again = Cmo3AtlasUndedup.undeduplicate(model, listOf(page), pageIndexByDrawableId)
assertContentEquals(result.pages[1].pngBytes, again.pages[1].pngBytes)
assertContentEquals(a2, again.puppet.drawables.single { drawable -> drawable.id.raw == "A2" }.mesh!!.uvs)
assertContentEquals(b2, again.puppet.drawables.single { drawable -> drawable.id.raw == "B2" }.mesh!!.uvs)
}
@Test
fun aTransparentTwinSharesItsSlotSilently() {
// Slot A has no opaque pixel at all (a hit area's): the packer has nothing to place, so the
// further placement stays on the source slot with its uvs as they were, and nothing is
// reported - nothing shows at either placement.
val page = widePage(listOf(intArrayOf(44, 40, 50, 47, 90)))
val model =
puppet(
listOf(
drawableOver("GhostA", slotAUvs, 0f),
drawableOver("GhostB", slotAUvs, 50f),
drawableOver("B1", slotBUvs, 0f),
drawableOver("B2", slotBUvs, 70f),
),
)
val result = Cmo3AtlasUndedup.undeduplicate(model, listOf(page), mapOf("GhostA" to 0, "GhostB" to 0, "B1" to 0, "B2" to 0))
assertTrue(result.sharedDrawableIds.isEmpty(), "a transparent twin is not the export notice's case")
assertEquals(listOf("B2"), result.duplicatedDrawableIds)
assertEquals(2, result.pages.size, "one synthesized page, for the twin with art")
assertEquals(0, result.pageIndexByDrawableId.getValue("GhostB"), "the transparent twin stays on the source page")
assertContentEquals(slotAUvs, result.puppet.drawables.single { drawable -> drawable.id.raw == "GhostB" }.mesh?.uvs, "with its uvs untouched")
assertPatchCarriedWhole("B2", result, page, slotBUvs)
}
}

Some files were not shown because too many files have changed in this diff Show More