oim_flutter library
@license Copyright (c) 2026 Xue Studios LLC SPDX-License-Identifier: Apache-2.0
Classes
- GeoShapeClipper
- GeoShapePainter
- InfiniteLayerConfig
- Configuration of an infinite moving background or parallax layer.
- InfiniteLayerPlan
- Render and layout plan for an infinite layer.
- InfiniteParallaxTrack
- An animated horizontal track that loops child pieces infinitely.
- LottieSlot
-
Renders embedded vector Lottie animations for slots with
type: "lottie". - OimExtractionResult
- OimFilter
- A parsed CSS filter chain: a Gaussian blur sigma and one color matrix (Flutter's 4x5 layout, offsets in the 0-255 scale).
- OimImageFillWidget
- Widget that displays an image with crop, flip, and shape clipping according to OIM canonical specification (contract 1.15.0 & 1.17.0).
- OimPlayer
- Interactive native Flutter widget to render OIM files.
- OimPublicKey
-
A public key the SDK trusts. Mirrors
PlayerKeyin@oim-media/player-oim. - PathDrawing
- PolygonDrawing
- ShapeDrawing
Enums
- OimSecurityStatus
-
What the SDK can say about a file, from strongest to weakest claim.
Same vocabulary as
SecurityStatusin@oim-media/player-oim, plus unknownKey: the player asks the server for a key it does not carry, the SDK never phones home, so an unknownkey_versionis reported, not guessed at. - ReeditPermission
Constants
- clockSkew → const Duration
- A device clock a few days off must not switch valid works off.
-
dynamicColorRoles
→ const List<
String> -
filterPresetCss
→ const Map<
String, String> -
Same table and order as
mediaFilterCssin@oim-media/core(media-filters.ts): preset, blur, brightness, contrast, saturation, hue-rotate. Neutral values produce no CSS, so a slot with no adjustments pays for no filter at all. -
geoShapes
→ const Map<
String, ShapeDrawing> - Geometry of the 24 catalogue shapes in the editor's viewBox 0 0 100 100. Copied directly from packages/core/src/geoShapes.ts to guarantee exact parity.
- imageHashAlg → const String
-
The seal scheme the backend writes in
image_hash_alg: SHA-256 of the IDAT payloads. - maxCanonicalNumber → const int
- Largest magnitude a signed number may have (2^53 - 1): every JSON parser reads it exactly.
- maxDecompressedMetadataBytes → const int
- oimDefaultLanguage → const String
- Language used when the caller does not set one, as in the web player (1.26.0).
-
oimEmbeddedKeys
→ const List<
OimPublicKey> -
Same key set as
EMBEDDED_KEYSinpackages/player-oim/src/render/keys.ts. -
pngSignature
→ const List<
int>
Functions
-
blendModeOf(
dynamic name) → BlendMode? -
CSS
mix-blend-modenames to Flutter blend modes.normaland unknown names return null. -
buildShapePath(
{ShapeDrawing? drawing, String? svgPath, required Size size, Rect viewBox = const Rect.fromLTWH(0, 0, 100, 100)}) → Path -
Builds a Path scaled to
sizefromdrawingorsvgPath. -
childrenByGroup(
List? slots) → Map< String, List< String> > -
Which slots go inside which group.
Matches
@oim-media/corechildrenByGroup. -
composeMatrices(
List< double> a, List<double> b) → List<double> -
Applies
afirst and thenb. -
computeInfiniteLayerPlan(
InfiniteLayerConfig cfg, double pieceWidthPx, [double? canvasWidthPx, double canvasScale = 1]) → InfiniteLayerPlan - Computes the exact infinite parallax plan for a moving layer.
-
decodeAndDecompressJSON(
String base64Str, {int maxBytes = maxDecompressedMetadataBytes}) → dynamic - Decodes base64 string and decompresses zlib/raw-deflate metadata into parsed JSON.
-
decodeDataUri(
String? uri) → Uint8List? -
Decodes an embedded base64 data URL (
data:image/...;base64,...), memoised. -
decompressAndParseBytes(
Uint8List bytes, {int maxBytes = maxDecompressedMetadataBytes}) → dynamic - Decompresses raw/deflate bytes and parses as JSON.
-
embeddedKey(
String kid, [List< OimPublicKey> keys = oimEmbeddedKeys]) → OimPublicKey? -
extractOIM(
Uint8List pngBytes) → OimExtractionResult - Extracts OIM metadata JSON and IDAT hash from raw PNG bytes.
-
hasEffectsStack(
Map< String, dynamic> style) → bool -
Web: a non-empty
style.effectsreplaces the legacy shadow, layer blur and grain fields. -
hasNumberOutOfRange(
dynamic value) → bool -
Whether
valuecarries, at any depth, a number with no canonical form. Beyond 2^53 - 1 parsers disagree on the value they read, so such a file's signature is invalid (BINARY_SPEC 5.1 rule 3). -
isGroup(
dynamic slot) → bool - Is this slot a group?
-
isKnownGeoShape(
dynamic geoShape) → bool -
isRefused(
OimSecurityStatus status) → bool - Altered files are refused outright: neither their image nor their layers are shown.
-
isValidDynamicColorRole(
dynamic role) → bool -
keyExpiredAt(
OimPublicKey key, DateTime now) → bool -
Whether this SDK no longer trusts
key, judged by the device clock. -
layerEffects(
Widget child, Map< String, dynamic> style, OimPalette? palette, {required bool isText, double unit = 1}) → Widget -
style.effectsas a CSS filter chain on the whole layer (web ImageEngine, unified effects stack), applied in file order:blurblurs, and on non-text layersdrop-shadowandglowcast the layer's own silhouette (CSSdrop-shadow()), not its box. On text layers those two are text shadows (textEffectShadows) and are skipped here. -
mediaFilterCss(
Map< String, dynamic> style) → String? - The CSS filter chain a slot's style asks for, or null when everything is neutral.
-
oimLanguages(
Map< String, dynamic> metadata) → List<String> -
The languages of a file's texts, lower-case and sorted (the web player's
languages). -
parseBorderRadius(
dynamic rawRadius, double containerWidth, double containerHeight) → BorderRadius - Parses CSS border-radius (e.g. "10px", "10px 25px 50px 0px") into BorderRadius.
-
parseCssColor(
dynamic rawColor) → Color? - Parses CSS-style hex colors (#RGB, #RRGGBB, #RRGGBBAA, transparent) into Flutter Color.
-
parseCssFilter(
String? css) → OimFilter? -
Parses the chain
mediaFilterCsswrites. Unknown functions are ignored. -
parseInfiniteParallax(
Map< String, dynamic> slot, Map<String, dynamic> style, {Map<String, dynamic> ? parentSceneLoop}) → InfiniteLayerConfig? -
Parses a layer's own infinite parallax. Like the web, a group's
sceneLoopmoves nothing by itself (it only makes the group clip);parentSceneLoopis accepted and ignored. -
parseSvgPath(
String d) → Path -
Parses an SVG path data string (
d) into a Flutter Path. -
permissionOf(
Map< String, dynamic> metadata) → ReeditPermission -
Who may re-edit a file. An unknown value falls back to ReeditPermission.authorOnly,
never to public: corrupt or tampered data must not loosen a permission.
Mirrors
permissionOfandnormalizeLegacyKeysin@oim-media/core. -
resolveColor(
dynamic role, dynamic fallback, OimPalette? palette) → Color? - Resolves a color given a semantic role, fallback raw value, and active palette.
-
resolveContent(
Object? content, String lang) → String -
A layer's content in
lang. MirrorsresolveContentin@oim-media/player-oimso both players show the same text. -
resolveCssUnit(
dynamic rawVal, double containerWidth, double containerHeight) → double? - Resolves CSS units (e.g. "62.5cqw", "10.0cqh", "24px", 24) to logical pixels given container dimensions.
-
resolvePalette(
Map< String, dynamic> metadata, {String? requested, bool? prefersDark}) → OimPalette? - Resolves the document's active palette from its metadata.
-
serializeCanonical(
Map< String, dynamic> metadata) → Uint8List -
The same rules as
serializeCanonicalin@oim-media/core(canonical.ts): root exclusion, numeric normalization, key ordering by Unicode code point, compact output, non-ASCII emitted raw, UTF-8. -
serializeLegacyCanonical(
Map< String, dynamic> metadata) → Uint8List -
Files published before
creator_user_idwas excluded were signed keeping it at the root. Mirrors the legacy fallback in the player: only the three transport keys are dropped, keys are sorted, numbers are left as they came. -
shadowOf(
Map< String, dynamic> style, {double unit = 1}) → BoxShadow? -
The slot's drop shadow. The player uses CSS
drop-shadow, whose blur radius is twice the Gaussian sigma, which is what Flutter'sblurRadiusmeans too.unitturns design px into canvas px: the web's shadow lives in the scaled stage. -
shapeDrawing(
dynamic geoShape) → ShapeDrawing? -
Returns the ShapeDrawing for
geoShape, or null if rectangle or unknown. -
signatureIsWithinKeyWindow(
OimPublicKey key, String? signedAt) → bool -
A file with no
signed_atcannot be judged: it predates signed dates. -
slotParent(
dynamic slot) → String? -
A slot's parent group id, as the editor writes it in
style.groupId. -
slotShownIn(
Map raw, String lang) → bool -
A layer with
languages(other than["*"]) shows only in those languages. -
textEffectShadows(
Map< String, dynamic> style, OimPalette? palette, {double unit = 1}) → List<Shadow> -
style.effectson a text layer, as the web paints it (ImageEngine, unified effects stack):drop-shadowis one text-shadow andglowtwo (blur radius*0.4, then radius).bluris in layerEffects;textureis not drawn yet. -
verifyMetadataSignature(
Map< String, dynamic> metadata, {List<OimPublicKey> keys = oimEmbeddedKeys}) → bool? -
Whether the ECDSA signature in
metadatais valid over its canonical bytes. Returns null when the key is not one this SDK carries. -
verifyOim(
OimExtractionResult result, {DateTime? now, List< OimPublicKey> keys = oimEmbeddedKeys}) → OimSecurityStatus -
The single place that decides a file's security status. Mirrors
securityVerdictin the player: the signature coversimage_hash, so once it is valid the seal can be trusted, and what is checked here is that the image shipped in the file is the one that was sealed.
Typedefs
-
OimPalette
= Map<
String, Color> - Resolved colors for a palette: map of role -> Color.