Skip to content

PyModel/pythinker-code / .agents/skills/opentui

opentui

Verified

Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.

FileKindSize
SKILL.mdskill md5.4 KB
docs/bindings/react.mdxmarkdown11.0 KB
docs/bindings/solid.mdxmarkdown15.0 KB
docs/components/ascii-font.mdxmarkdown4.3 KB
docs/components/box.mdxmarkdown5.5 KB
docs/components/code.mdxmarkdown10.2 KB
docs/components/diff.mdxmarkdown4.2 KB
docs/components/frame-buffer.mdxmarkdown6.7 KB
docs/components/input.mdxmarkdown5.6 KB
docs/components/line-number.mdxmarkdown4.0 KB
docs/components/markdown.mdxmarkdown10.6 KB
docs/components/qr-code.mdxmarkdown4.3 KB
docs/components/scrollbar.mdxmarkdown2.3 KB
docs/components/scrollbox.mdxmarkdown7.5 KB
docs/components/select.mdxmarkdown6.2 KB
docs/components/slider.mdxmarkdown2.2 KB
docs/components/tab-select.mdxmarkdown6.0 KB
docs/components/text-table.mdxmarkdown9.0 KB
docs/components/text.mdxmarkdown4.5 KB
docs/components/textarea.mdxmarkdown7.7 KB
docs/components/time-to-first-draw.mdxmarkdown4.7 KB
docs/core-concepts/audio.mdxmarkdown32.2 KB
docs/core-concepts/colors.mdxmarkdown7.8 KB
docs/core-concepts/console.mdxmarkdown3.2 KB
docs/core-concepts/constructs.mdxmarkdown5.8 KB
docs/core-concepts/keyboard.mdxmarkdown10.4 KB
docs/core-concepts/layout.mdxmarkdown4.0 KB
docs/core-concepts/lifecycle.mdxmarkdown4.4 KB
docs/core-concepts/notifications.mdxmarkdown2.3 KB
docs/core-concepts/renderables-vs-constructs.mdxmarkdown4.5 KB
docs/core-concepts/renderables.mdxmarkdown9.9 KB
docs/core-concepts/renderer.mdxmarkdown30.9 KB
docs/core-concepts/testing.mdxmarkdown14.6 KB
docs/getting-started.mdxmarkdown3.2 KB
docs/keymap/addons.mdxmarkdown15.6 KB
docs/keymap/core.mdxmarkdown38.9 KB
docs/keymap/custom-addons.mdxmarkdown26.7 KB
docs/keymap/hosts.mdxmarkdown15.7 KB
docs/keymap/overview.mdxmarkdown18.1 KB
docs/keymap/react.mdxmarkdown4.9 KB
docs/keymap/solid.mdxmarkdown5.1 KB
docs/plugins/core.mdxmarkdown12.6 KB
docs/plugins/react.mdxmarkdown6.5 KB
docs/plugins/slots.mdxmarkdown12.7 KB
docs/plugins/solid.mdxmarkdown7.0 KB
docs/reference/color-matrix.mdxmarkdown3.8 KB
docs/reference/env-vars.mdxmarkdown6.5 KB
docs/reference/native-span-feed.mdxmarkdown6.0 KB
docs/reference/package-entrypoints.mdxmarkdown9.6 KB
docs/reference/qr-encoder.mdxmarkdown12.3 KB
docs/reference/ssh.mdxmarkdown14.8 KB
docs/reference/standalone-executables.mdxmarkdown7.1 KB
docs/reference/three.mdxmarkdown14.8 KB
docs/reference/tree-sitter.mdxmarkdown4.6 KB

docs/reference/color-matrix.mdx

View on GitHub
---
title: Color matrix
description: Per-cell and uniform RGBA matrix transforms on FrameBuffer
order: 3
---

# Color matrix

`FrameBuffer` supports native 4x4 RGBA matrix transforms through two methods: `colorMatrix(...)` and
`colorMatrixUniform(...)`.

Use `colorMatrix(...)` when you want to transform specific cells with per-cell strengths. Use
`colorMatrixUniform(...)` when you want to apply one transform to the entire buffer.

Both methods work on normalized RGBA values (`0.0` to `1.0`) and can target foreground, background, or both channels.

## API

```typescript
import { TargetChannel } from "@opentui/core"

frameBuffer.colorMatrix(
  matrix: Float32Array,
  cellMask: Float32Array,
  strength = 1.0,
  target = TargetChannel.Both,
)

frameBuffer.colorMatrixUniform(
  matrix: Float32Array,
  strength = 1.0,
  target = TargetChannel.Both,
)
```

## Matrix format

Matrix must be exactly 16 floats in row-major order.

Each row defines one output channel:

```text
Row 0: [r->r, g->r, b->r, a->r]  // output red
Row 1: [r->g, g->g, b->g, a->g]  // output green
Row 2: [r->b, g->b, b->b, a->b]  // output blue
Row 3: [r->a, g->a, b->a, a->a]  // output alpha
```

Each cell is transformed in two stages:

```text
newColor = M * color
output = original + (newColor - original) * strength
```

This means `strength = 0.0` keeps original color, and `strength = 1.0` applies full matrix result.

## Target channels

Use the `TargetChannel` enum to choose which color buffers are affected:

- `TargetChannel.FG` (`1`): foreground only
- `TargetChannel.BG` (`2`): background only
- `TargetChannel.Both` (`3`): foreground + background

## `colorMatrix` cell mask format

`cellMask` uses packed triplets:

```text
[x, y, perCellStrength, x, y, perCellStrength, ...]
```

- `x` and `y` are cell coordinates
- `perCellStrength` is multiplied by method `strength`
- incomplete trailing values (not a multiple of 3) are ignored
- out-of-bounds or non-finite coordinates are skipped
- non-finite effective strengths are skipped

This method is useful for effects that only affect part of the buffer, such as scanlines, vignettes, or localized color
grading.

## `colorMatrixUniform` behavior

`colorMatrixUniform` applies the same matrix to every pixel in the selected channel(s).

- optimized path processes 4 pixels at a time with SIMD
- scalar fallback handles any remaining pixels
- `strength === 0` or non-finite `strength` returns early

Use this method for full-frame color grading and global post-processing.

## No clamping

Result values are not clamped to `[0, 1]`. Matrix coefficients and strengths can push channels above `1.0` or below
`0.0`.

## Example: invert whole buffer

```typescript
import { INVERT_MATRIX, TargetChannel } from "@opentui/core"

frameBuffer.colorMatrixUniform(INVERT_MATRIX, 1.0, TargetChannel.Both)
```

## Example: apply sepia to selected cells

```typescript
import { SEPIA_MATRIX, TargetChannel } from "@opentui/core"

// Affect only three cells at custom strengths
const cellMask = new Float32Array([
  5,
  2,
  1.0, // full sepia at (5,2)
  6,
  2,
  0.5, // half sepia at (6,2)
  7,
  2,
  0.25, // subtle sepia at (7,2)
])

frameBuffer.colorMatrix(SEPIA_MATRIX, cellMask, 1.0, TargetChannel.FG)
```

## Example: custom saturation matrix

```typescript
import { TargetChannel } from "@opentui/core"

function createSaturationMatrix(saturation: number): Float32Array {
  const rw = 0.299
  const gw = 0.587
  const bw = 0.114
  const inv = 1 - saturation

  return new Float32Array([
    rw * inv + saturation,
    gw * inv,
    bw * inv,
    0,
    rw * inv,
    gw * inv + saturation,
    bw * inv,
    0,
    rw * inv,
    gw * inv,
    bw * inv + saturation,
    0,
    0,
    0,
    0,
    1,
  ])
}

const saturation = createSaturationMatrix(1.25)
frameBuffer.colorMatrixUniform(saturation, 0.8, TargetChannel.Both)
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall