Each image-map type converts pixels into heights, categories, or mask weights. This page explains that conversion. For accepted PNG formats, see 37 - Image Maps. For fields and coordinate rules, see 43 - Image Map Configuration & Coordinates.

Iris reads raw sRGB channel numbers with no gamma, ICC, display, or perceptual conversion, so export your source with profile conversion, dithering, antialiasing, and palette quantization disabled. See Raw sample rules.

A grayscale heightmap stores one normalized elevation per pixel. Black maps to minimumHeight, white maps to maximumHeight, and Iris preserves native 8-bit or 16-bit source precision before applying the configured curve and spatial sampling.

Save images/maps/terrain.png, then create image-maps/terrain.json:

{
  "source": "maps/terrain",
  "type": "GRAYSCALE_HEIGHT",
  "minimumHeight": -64,
  "maximumHeight": 320,
  "blocksPerPixel": 1,
  "sampling": "BILINEAR"
}

For a source bit depth b, Iris reads the unsigned grayscale sample without color correction:

maximumSample = 2^b - 1
normalized = sample / maximumSample
height = minimumHeight + normalized × (maximumHeight - minimumHeight)

For minimumHeight: -64 and maximumHeight: 320, black is Y -64 and white is Y 320. The integer midpoint sample lies just above the mathematical midpoint because both unsigned ranges contain an even number of representable values.

1. Read the raw unsigned grayscale sample and normalize it to 0 through 1.
2. Apply inverted as 1 - normalized when enabled.
3. Apply curveExponent as a power curve.
4. Apply the configured alpha policy.
5. Apply load-time box smoothing when smoothingRadius is above zero.
6. Spatially sample the decoded scalar with NEAREST, BILINEAR, or BICUBIC.
7. Map the scalar into minimumHeight through maximumHeight.
8. Add verticalOffset.
9. Clamp to the configured height interval when clamp is true.
10. Apply the dimension binding's composed masks.

Interpolation acts on decoded scalar values, not packed image bytes or final rounded block heights, which preserves continuous slopes while keeping the height-range mapping explicit.

minimumHeight and maximumHeight are absolute world Y values for a TERRAIN_HEIGHT binding. Validation evaluates the effective endpoints after verticalOffset and clamp; an output outside the owning dimension's build range is a blocking error rather than being silently clipped. Studio's clipped-pixel count instead identifies source pixels whose offset result was clamped to the map's own configured height interval.

An 8-bit map spanning 384 blocks has steps of about 1.506 blocks before interpolation; a 16-bit map over the same range has steps of about 0.00586 blocks. Bilinear or bicubic sampling smooths spatial transitions but cannot restore precision removed during export.

An RGB heightmap stores one unsigned 24-bit elevation across three 8-bit channels, using one fixed red-green-blue formula.

encoded = (red << 16) | (green << 8) | blue
normalized = encoded / 16777215
height = minimumHeight + normalized × (maximumHeight - minimumHeight)

Red is the most significant byte, green the middle, blue the least. 0x000000 is the minimum, 0xFFFFFF the maximum, and the encoding has 16,777,216 representable values.

Only this unsigned normalized encoding is accepted by RGB_HEIGHT. Signed displacement, little-endian BGR, Mapbox Terrain-RGB, Terrarium, meters encoded with a scale and bias, and any other formula require an explicitly different map type — Iris does not identify them from pixel values. {.is-warning}

Save an 8-bit RGB or RGBA PNG at images/maps/terrain-rgb.png, then create image-maps/terrain-rgb.json:

{
  "source": "maps/terrain-rgb",
  "type": "RGB_HEIGHT",
  "minimumHeight": -64,
  "maximumHeight": 320,
  "blocksPerPixel": 1,
  "sampling": "BILINEAR",
  "alpha": "IGNORE",
  "clamp": true
}

An RGB source must have exactly 8 bits per color channel. A 16-bit-per-channel RGB PNG is not a larger version of this encoding and is rejected.

The scalar is decoded per source pixel, so bilinear and bicubic filters interpolate decoded scalars rather than the three color channels independently. That prevents channel carry boundaries from producing false elevations: adjacent encoded values 0x00FFFF and 0x010000 are numerically consecutive even though all three displayed channels change.

RGBA sources use the same RGB formula, and the separate alpha setting decides what alpha does. An RGB source without alpha behaves as fully opaque.

With minimumHeight: -64 and maximumHeight: 320:

Keep clamp: true unless values outside the configured range are an intentional downstream input.

Color maps assign authored raw RGB values to Iris resources or Minecraft blocks. Exact nearest-neighbor matching is the default, and any unknown or ambiguous color configured as an error blocks the pack before generation.

Create image-maps/biomes.json:

{
  "source": "maps/biomes",
  "type": "COLOR_MAP",
  "sampling": "NEAREST",
  "outOfBounds": "CLAMP",
  "colorTolerance": 0,
  "unknownColor": "ERROR",
  "colors": {
    "#2D6A4F": "iris:temperate_forest",
    "#DDB892": "iris:desert",
    "#1D4ED8": "iris:ocean"
  }
}

Legend keys are six-digit #RRGGBB raw sRGB values. The target namespace is interpreted by the dimension application: biome keys for BIOME, region keys for REGION, block keys for SURFACE_BLOCK.

COLOR_MAP requires NEAREST. Bilinear and bicubic filters create colors that are absent from the legend and fail validation for categorical maps.

colorTolerance is a radius in raw 8-bit sRGB channel space, from 0 through approximately 441.672956 — the distance between black and white. For a source color (r, g, b) and legend color (R, G, B):

distance = sqrt((r - R)^2 + (g - G)^2 + (b - B)^2)

• 0 requires an exact RGB match and is the default.
• An exact legend match wins immediately.
• With no exact match and tolerance above zero, a legend color is eligible when its distance is at most the configured tolerance.
• No eligible entry is an unknown color.
• More than one eligible entry is a blocking validation error. Configure exactly one matching entry.

Tolerance uses raw sRGB channel values. It is not Delta E, HSV distance, gamma-linear distance, or a display-profile comparison. Keep it at zero for authored data maps whenever possible, and keep legend colors far enough apart that the selected tolerance cannot overlap their acceptance radii.

With FALLBACK, fallbackTarget must be valid for the binding application. Studio reports the unknown-pixel count, and ambiguous tolerance matches are blocking validation errors that identify their source pixel coordinates, so the source or legend can be repaired without searching visually.

The alpha policy applies independently from RGB matching:

Use ALPHA_MASK when alpha is a named reusable mask rather than an attribute of one map, or when its transform, reuse, threshold, or composition needs to be configured independently.

Region targets must load from the pack. Biome targets must load and occur in exactly one land, sea, or shore role across the dimension. Surface-block targets must exist in the live block registry.

Masks produce zero-through-one weights that restrict another binding.

For a BINARY_MASK resource, threshold is the lower edge and falloff is the soft transition width above it; falloff: 0 creates a hard edge. smoothingRadius may average the compiled result afterward, so keep it at zero for an exact binary footprint. Resource-level inverted: true exchanges 0 and 1 before the map is compiled.

ALPHA_MASK requires 8-bit RGBA and alpha: IGNORE, because alpha itself is the map data.

Exact binary boundaries require NEAREST. Continuous grayscale and alpha masks may use BILINEAR or BICUBIC when a spatially smooth weight is intended.

Add mask bindings to the dimension, then reference their binding keys from another entry:

{
  "imageMaps": [
    {
      "key": "land",
      "map": "masks/land",
      "application": "MASK"
    },
    {
      "key": "exclude",
      "map": "masks/exclude",
      "application": "MASK"
    },
    {
      "key": "terrain-height",
      "map": "terrain/height",
      "application": "TERRAIN_HEIGHT",
      "masks": [
        { "map": "land", "operation": "MULTIPLY" },
        { "map": "exclude", "operation": "SUBTRACT", "inverted": false }
      ]
    }
  ]
}

Masks are sampled and combined in declaration order after the primary map's scalar or target has been decoded. Each reference may apply its own inverted, threshold, and falloff without changing the reusable mask resource.

The final weight has application-specific meaning. TERRAIN_HEIGHT linearly blends from the ordinary procedural height at weight 0 to the mapped height at weight 1. BIOME, REGION, and SURFACE_BLOCK use the mapped categorical target at weights of at least 0.5 and leave the ordinary pipeline in control below 0.5.

A mask reference must name a dimension binding whose application is MASK, and a MASK binding cannot itself contain mask references. Missing keys, duplicate binding keys, references to non-mask applications, and nested mask composition are blocking errors.

Use a separate mask resource when several maps share the same footprint, and preview unknown, ambiguous, transparent, and uncovered pixels before export.