Matrices
scene.viz.matrix: matrices seleccionables y mutables, con morph entre estados y álgebra simbólica opcional
scene.viz.matrix(...) crea una matriz cuyas entradas son objetos independientes. Una celda, fila, columna, diagonal o bloque puede recibir estilo y animación sin desarmar la composición, y la matriz puede cambiar de forma o transformarse en otra.
from gaanim import GOLD, Scene
scene = Scene(frame=(16, 9), background="#0f172a")
m = scene.viz.matrix([[1, 2, 3], [4, 5, 6]], delimiters="parentheses")
m[0, :].fill(GOLD)
scene.play(m.entries.animate.write(order="spiral_in", stagger=0.05).duration(0.4))
scene.render()
Matrix y sus tipos auxiliares (MatrixSelection, MatrixEntry…) se importan desde gaanim y se definen en su módulo Python, por eso las fichas de esta página los nombran por la variable (matrix.row) y no por la clase. Matrix es un Drawable: se coloca, escala y anima como cualquier objeto, y los métodos heredados, place incluido, devuelven la propia matriz. Al escalarla crecen también las entradas y los delimitadores.
Crear una matriz
La fábrica y los datos que acepta.
FÁBRICAVisualization.matrixmatrix(data: Any, *, row_gap: float = 0.24, column_gap: float = 0.24, delimiter_gap: float = 0.12, delimiters: Literal["brackets", "parentheses", "braces", "bars", "double_bars", "none"] = "brackets", delimiter_size: float | None = None, delimiter_weight: int = 300, row_labels: Sequence[Any] | None = None, column_labels: Sequence[Any] | None = None, label_mode: Literal["math", "text"] = "math", cell_mode: Literal["math", "text"] = "math", entry_style: Any | None = None, label_style: Any | None = None, cell_factory: Callable[[Any, int, int], Drawable] | None = None, numeric_format: str = "g", fractions: Literal["stacked", "inline"] = "stacked") -> Matrix
Los escalares se convierten en ecuaciones Typst; un
Drawable se conserva tal cual. Filas desiguales, etiquetas incompatibles, modos, grosores o delimitadores inválidos lanzan ValueError o TypeError antes del render.Parámetros
| Nombre | Tipo | Predeterminado | Descripción |
|---|---|---|---|
data | Sequence[Sequence[valor]] | sympy.MatrixBase | obligatorio | Datos rectangulares no vacíos. |
row_gap / column_gap | float | 0.24 / 0.24 | Separación entre filas y columnas, en unidades de escena. |
delimiter_gap | float | 0.12 | Espacio entre las entradas y los delimitadores. |
delimiters | str | "brackets" | brackets, parentheses, braces, bars, double_bars o none. |
delimiter_size / delimiter_weight | float | None / int | None / 300 | Tamaño y grosor tipográfico, de 100 a 900. Sin tamaño, los delimitadores abarcan las filas: siguen el tamaño de entry_style y la separación entre filas. |
row_labels / column_labels | Sequence | None | None | Etiquetas externas alineadas con filas o columnas. |
cell_mode / label_mode | "math" | "text" | "math" | Entradas y etiquetas como matemática Typst o texto plano. |
entry_style / label_style | TextStyle | None | None | Estilo de entradas y etiquetas. |
cell_factory | Callable[[valor, fila, columna], Drawable] | None | None | Crea un objeto propio para cada celda. |
numeric_format | str | "g" | Formato de Python para los números decimales. |
fractions | "stacked" | "inline" | "stacked" | Los racionales exactos como fracciones apiladas o, con "inline", en una línea (3/2), tan altas como las demás entradas. |
Ejemplo
costs = scene.viz.matrix(
[[12.5, 8], [3, 40.25]],
row_labels=["A", "B"], column_labels=["ida", "vuelta"],
label_mode="text", numeric_format=".1f", delimiters="brackets",
)CLASEMatrixEntryMatrixEntry(value, key=None, style=None)
Valor de una celda con una clave estable opcional (
key) para emparejarlo en morph_to y un estilo de texto local. Los predicados de where y MatrixSelection.values reciben entradas de este tipo; el número está en .value.Ejemplo
m = scene.viz.matrix([[MatrixEntry("a", key="a"), 0], [0, MatrixEntry("b", key="b")]])PROPIEDADmatrix.shape / nrows / ncolsshape: tuple[int, int] · nrows: int · ncols: int · entries: MatrixSelection · row_labels · column_labels · drawable
Dimensiones, todas las entradas como selección, las etiquetas como tuplas de
Drawable y el objeto raíz de la composición.Seleccionar entradas
Grupos estables de celdas que se estilizan y animan juntos.
MÉTODOmatrix[fila, columna]matrix[r, c] -> Drawable · matrix[filas, columnas] -> MatrixSelection
Con dos enteros devuelve la celda; con slices o listas de índices, una
MatrixSelection. Admite índices negativos.Ejemplo
m = scene.viz.matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
m[1, 1].fill(RED)
m[:, 0].fill(GOLD)MÉTODOmatrix.row / column / blockrow(index) · column(index) · block(rows, columns) -> MatrixSelection
Una fila, una columna o un bloque;
rows y columns aceptan un índice, un slice o una lista.Ejemplo
m = scene.viz.matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
m.block(slice(0, 2), [1, 2]).fill(BLUE)
scene.play(m.row(2).animate.indicate(order="row_major", stagger=0.1))MÉTODOmatrix.diagonal / anti_diagonaldiagonal(offset=0) · anti_diagonal(offset=0) -> MatrixSelection
La diagonal principal o la secundaria, desplazada
offset columnas.MÉTODOmatrix.wherewhere(mask_or_predicate) -> MatrixSelection
Selecciona con una máscara rectangular de booleanos o con un predicado
f(entrada, fila, columna), donde entrada es un MatrixEntry.Ejemplo
m = scene.viz.matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
m.where(lambda entry, row, column: entry.value % 2 == 0).fill(GOLD)CLASEMatrixSelectionfill(color) · opacity(value) · offset(dx, dy) · coordinates · values · animate
Secuencia estable de celdas.
fill y opacity cambian su estilo al instante, offset desplaza las celdas sin salir del layout, coordinates y values devuelven sus posiciones y entradas, y animate da un MatrixSelectionAnimation.CLASEMatrixSelectionAnimationwrite · create · fade_in · fade_out · indicate · wiggle · fill · opacity · scale_by · rotate_by (order=…, stagger=…, seed=0) · duration · easing
Animación de todas las celdas de una selección.
order recorre las celdas en simultaneous, row_major, column_major, main_diagonal, anti_diagonal, spiral_in, spiral_out o random (reproducible con seed), o en el orden de una lista de coordenadas o de una función (fila, columna) -> clave. stagger es el retraso entre celdas; con simultaneous todas empiezan juntas. Sin order, empiezan juntas o, si das un stagger, fila a fila. Se pasa directamente a scene.play.Ejemplo
m = scene.viz.matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
scene.play(m.entries.animate.fade_in(order="main_diagonal", stagger=0.08).duration(0.8))
scene.play(m.diagonal().animate.fill(GOLD).duration(0.4))Cambiar la estructura
Cambios de valores, filas y columnas que recomponen la matriz en el cursor. La matriz conserva su lugar, su transformación y sus animaciones: cambian los hijos de su cuadrícula, no la cuadrícula.
MÉTODOmatrix.setset(row, column, value) -> Drawable
Sustituye el valor de una celda y devuelve su nuevo objeto.
Ejemplo
m = scene.viz.matrix([[1, 2], [3, 4]])
scene.wait(0.5)
m.set(0, 1, 7).fill(GOLD)MÉTODOmatrix.insert_row / remove_row / insert_column / remove_columninsert_row(index, values) · remove_row(index) · insert_column(index, values) · remove_column(index) -> Matrix
Añade o quita filas y columnas; los valores nuevos deben tener la longitud correcta.
Ejemplo
m = scene.viz.matrix([[1, 2], [3, 4]])
m.insert_row(1, [0, 0]).remove_column(0)MÉTODOmatrix.swap_rows / swap_columns / reorder_rows / reorder_columnsswap_rows(first, second) · swap_columns(first, second) · reorder_rows(order) · reorder_columns(order) -> Matrix
Intercambia o permuta filas y columnas;
order es una permutación completa de índices.Ejemplo
m = scene.viz.matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
m.swap_rows(0, 2)
m.reorder_columns([2, 0, 1])MÉTODOmatrix.becomebecome(data) -> Matrix
Sustituye todos los datos, incluso con otra forma. Un
delimiter_size explícito crece o se encoge con el número de filas, como el automático.MÉTODOmatrix.morph_tomorph_to(target: Matrix, *, match="auto", stagger=0.0) -> MatrixSelectionAnimation
Transforma la matriz en
target, que es la que queda al final. Con match="auto" empareja primero por las claves de MatrixEntry, después por valores y por último por posiciones. Cada entrada emparejada viaja hasta la suya y le cede el lugar; las que no tienen pareja se desvanecen, las del destino sin pareja aparecen y los delimitadores y etiquetas se transforman en los del destino. El destino se muestra al empezar, aunque estuviera oculto con hidden(). Configura el tiempo con .duration(...) y .easing(...).Ejemplo
from gaanim import Scene
scene = Scene(frame=(16, 9), background="#0f172a")
a = scene.viz.matrix([[1, 2], [3, 4]]).move_to(-2.5, 0)
b = scene.viz.matrix([[1, 3], [2, 4]]).move_to(2.5, 0)
scene.play(a.entries.animate.write(stagger=0.05).duration(0.5))
scene.play(a.morph_to(b).duration(1.0))
scene.render()
Álgebra simbólica
Operaciones exactas con SymPy que devuelven el resultado y los pasos animables.
Instala el extra gaanim[algebra] para usarlas. add, subtract, matmul, hadamard, scalar_multiply, transpose, determinant, inverse, rank, trace, rref, lu, qr y eigen aceptan exact=True, precision=None y devuelven una MatrixDerivation[T]: T es Matrix para resultados matriciales, Drawable para escalares y tuple[Matrix, Matrix] para descomposiciones. Los fallos exactos no se aproximan en silencio: pasa exact=False, precision=N de forma explícita. to_sympy() devuelve la matriz de SymPy. Una matriz resultado toma las opciones de la matriz de origen (separaciones, delimitadores, entry_style, cell_factory, numeric_format, fractions), no sus etiquetas; un escalar es una ecuación como rank = 2.
CLASEMatrixDerivationvalue · result · steps · animations(*, order="row_major", stagger=0.04)
Resultado de una operación:
value es el valor exacto de SymPy, result el objeto visual y steps los pasos (MatrixStep, con kind, sources, target y expression). animations() devuelve una MatrixSelectionAnimation que recorre los pasos. Un error de álgebra lanza MatrixAlgebraError, subclase de ValueError.Ejemplo
from gaanim import Scene
scene = Scene(frame=(16, 9), background="#0f172a")
a = scene.viz.matrix([[1, 2], [3, 4]]).move_to(-3, 0)
b = scene.viz.matrix([[2, 0], [1, 2]])
product = a.matmul(b)
product.result.move_to(3, 0)
scene.play(product.animations().duration(0.7))
scene.render()