colormesh

lq.colormesh(x, y, z, map: color.map.viridis, min: auto, max: auto, excess: "clamp", norm: "linear", align: center + horizon, interpolation: "pixelated", label: none, z-index: 2)(source)

Plots a rectangular color mesh, e.g., a heatmap.

#lq.diagram(
  width: 4cm, height: 4cm,
  lq.colormesh(
    lq.linspace(-4, 4, num: 10),
    lq.linspace(-4, 4, num: 10),
    (x, y) => x * y,
    map: color.map.magma
  )
)

When the input x and y coordinate arrays are both evenly spaced, an image is drawn instead of individual rectangles. This reduces the file size and improves rendering in most cases. When either array is not evenly spaced, the entire color mesh is drawn with individual rectangles.

Parameters

x : array

A one-dimensional array of $x$ coordinates.

y : array

A one-dimensional array of $y$ coordinates.

z : array | function

Specifies the $z$ coordinates (height) for all combinations of $x$ and $y$ coordinates. This can be one of the following:

• A two-dimensional array with $z$ coordinates consisting of one row per $y$ coordinate (row-major order).

  If the array has dimensions y.len() × x.len(), the $x$ and $y$ coordinates are mapped one-to-one to the $z$ values and the alignment if the mesh rectangles is controlled through colormesh.align.

  Example

  #lq.diagram(
    width: 3cm, height: 3cm,
    lq.colormesh(
      (1, 2, 3),
      (1, 2, 3),
      ((1, 2, 3), (2, 3, 4), (5, 5, 5))
    )
  )

  

  If the array has dimensions (y.len()-1) × (x.len()-1), the $x$ and $y$ coordinates are treated as edges for the mesh rectangles and colormesh.align is ignored.

  Example

  #lq.diagram(
    width: 3cm, height: 3cm,
    yaxis: (tick-distance: 1),
    lq.colormesh(
      (1, 2, 3),
      (1, 2, 3),
      ((1, 2), (2, 3))
    )
  )

  

  Also see the function mesh that can be used to generate rectangular meshes.

• A function that takes an x and a y value and returns a corresponding z coordinate.

• Some content, e.g., an image created with a third-party tool. In this case, colormesh.min, colormesh.max, and colormesh.map need to be set manually to match the data if a colorbar shall be created. Both colormesh.x and colormesh.y are allowed to just contain the first and last coordinate, respectively.

  Example

  #let mesh = lq.colormesh(
    (0, 20), (0, 20),
    image("image.png"),
    map: (black, white),
    min: 2, max: 7
  )
  
  #lq.diagram(mesh)
  #lq.colorbar(mesh)

  

For the purpose of masking, you can use float.nan values to hide individual cells of the color mesh.

map : array | gradient    default: color.map.viridis

A color map in the form of a gradient or an array of colors to sample from.

min : auto | int | float    default: auto

Sets the data value that corresponds to the first color of the color map. If set to auto, it defaults to the minimum $z$ value.

max : auto | int | float    default: auto

Sets the data value that corresponds to the last color of the color map. If set to auto, it defaults to the maximum $z$ value.

excess : "clamp" | "mask"    default: "clamp"

Determines how values outside the range defined by colormesh.min and colormesh.max are handled.

• "clamp": Values below colormesh.min are mapped to the first color of the color map, values above colormesh.max are mapped to the last color.
• "mask": Values outside the range are not drawn and appear transparent.

norm : lq.scale | str | function    default: "linear"

The normalization method used to scale $z$ coordinates to the range $[0,1]$ before mapping them to colors using the color map. This can be a scale, a string that is the identifier of a built-in scale or a function that takes one argument (for example the argument x => calc.log(x) would be equivalent to passing "log"). Note that the function does not actually need to map the values to the interval $[0,1]$. Instead it describes a scaling that is applied before the data set is linearly scaled to the interval $[0,1]$.

align : alignment    default: center + horizon

How to align mesh rectangles at the given $x$ and $y$ coordinates.

Example

#show: lq.set-diagram(width: 3cm, height: 3cm)

#lq.diagram(
  lq.colormesh(
    align: center + horizon,
    (0, 1, 2),
    (0, 1, 2),
    ((1, 2, 3), (2, 3, 4), (5, 5, 5))
  )
)

#lq.diagram(
  lq.colormesh(
    align: left + bottom,
    (0, 1, 2),
    (0, 1, 2),
    ((1, 2, 3), (2, 3, 4), (5, 5, 5))
  )
)

This parameter does not apply when the coordinate arrays are one larger than the $z$ mesh so that they are treated as edges, see colormesh.z.

interpolation : "pixelated" | "smooth"    default: "pixelated"

Whether to apply smoothing or leave the color mesh pixelated. This is currently only supported when colormesh.x and colormesh.y are evenly spaced.

label : content    default: none

The legend label for this plot. See plot.label.

z-index : int | float    default: 2

Determines the $z$ position of this plot in the order of rendered diagram objects. See plot.z-index.