numbl 0.4.2 → 0.4.4

package/dist-lib/graphics/axisLimits.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure computation of the current axis limits for an `AxesState`.
+ *
+ * This is the source of truth for the query form `lim = axis`: the numbl
+ * runtime reduces its accumulated plot instructions into an `AxesState` and
+ * asks this module for the limit vector. It is deliberately rendering-free
+ * (no canvas, no DOM) so numbl-core can import it.
+ *
+ * For an axis with an explicit limit, that limit is returned verbatim (a
+ * `null` bound falls back to the data-derived bound). For a fully automatic
+ * axis the data extent is computed across every trace type and padded the
+ * same way `drawPlot` pads a default 2-D view, so the reported limits track
+ * what is drawn.
+ */
+import type { AxesState } from "./figuresReducer.js";
+/** Does this axes hold any 3-D content (so limits are a 6-vector)? */
+export declare function axesIs3D(axes: AxesState): boolean;
+/**
+ * Compute the limit vector for `lim = axis`.
+ * Returns 4 elements `[xmin xmax ymin ymax]` for a 2-D view, or 6 elements
+ * `[xmin xmax ymin ymax zmin zmax]` when the axes holds 3-D content.
+ */
+export declare function computeAxisLimits(axes: AxesState): number[];

package/dist-lib/graphics/figuresReducer.d.ts

@@ -0,0 +1,77 @@
+import type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, PlotInstruction } from "./types.js";
+export type AxesState = {
+    holdOn: boolean;
+    traces: PlotTrace[];
+    plot3Traces: Plot3Trace[];
+    surfTraces: SurfTrace[];
+    imagescTrace?: ImagescTrace;
+    pcolorTraces: PcolorTrace[];
+    contourTraces: ContourTrace[];
+    barTraces: BarTrace[];
+    barhTraces: BarTrace[];
+    bar3Traces: Bar3Trace[];
+    bar3hTraces: Bar3Trace[];
+    errorBarTraces: ErrorBarTrace[];
+    boxTraces: BoxTrace[];
+    pieTrace?: PieTrace;
+    heatmapTrace?: HeatmapTrace;
+    quiverTraces: QuiverTrace[];
+    quiver3Traces: Quiver3Trace[];
+    areaTraces: PlotTrace[];
+    areaBaseValue: number;
+    patchTraces: PatchTrace[];
+    title?: string;
+    xlabel?: string;
+    ylabel?: string;
+    zlabel?: string;
+    shading?: "faceted" | "flat" | "interp";
+    legend?: string[];
+    gridOn?: boolean;
+    /** Axes border. Undefined/true → full rectangle (numbl's default, matching
+     *  MATLAB `box on`); false → only the left and bottom axis lines (`box off`). */
+    boxOn?: boolean;
+    colorbar?: boolean;
+    colorbarLocation?: string;
+    colormap?: string;
+    colormapData?: number[][];
+    view?: {
+        az: number;
+        el: number;
+    };
+    axisMode?: string;
+    axisScale?: "linear" | "semilogx" | "semilogy" | "loglog";
+    caxis?: [number, number];
+    /** Explicit axis limits from `axis([...])` / `xlim` / `ylim`. Each bound
+     *  may be `null`, meaning "use the data-derived bound" (partial limits). An
+     *  absent field means the whole axis is automatic. */
+    xlim?: [number | null, number | null];
+    ylim?: [number | null, number | null];
+    zlim?: [number | null, number | null];
+    /** y-axis direction: "reverse" is `axis ij` (origin at top-left). */
+    yDir?: "normal" | "reverse";
+    /** Axes lines/background visibility (`axis off` sets this false). */
+    axisVisible?: boolean;
+};
+export type FigureState = {
+    subplotGrid?: {
+        rows: number;
+        cols: number;
+    };
+    currentAxesIndex: number;
+    sgtitle?: string;
+    axes: {
+        [index: number]: AxesState;
+    };
+};
+export type FiguresState = {
+    currentHandle: number;
+    figs: {
+        [handle: number]: FigureState;
+    };
+};
+/** Actions accepted by the figures reducer: any PlotInstruction, plus "clear" for UI resets. */
+export type FiguresAction = PlotInstruction | {
+    type: "clear";
+};
+export declare const initialFiguresState: FiguresState;
+export declare const figuresReducer: (state: FiguresState, action: FiguresAction) => FiguresState;

package/dist-lib/graphics/types.d.ts

@@ -19,6 +19,10 @@ export interface PlotTrace {
     markerEdgeColor?: [number, number, number];
     markerFaceColor?: [number, number, number];
     markerIndices?: number[];
+    /** Stable identity for a trace returned as a graphics handle (e.g. from
+     *  `line`). Lets `set(h,'XData',...)` / `update_trace` find and mutate this
+     *  exact trace in the renderer's accumulated state across `drawnow`. */
+    id?: number;
 }
 export interface Plot3Trace {
     x: number[];
@@ -32,6 +36,35 @@ export interface Plot3Trace {
     markerEdgeColor?: [number, number, number];
     markerFaceColor?: [number, number, number];
     markerIndices?: number[];
+    /** See PlotTrace.id. */
+    id?: number;
+}
+/** A patch object: one or more colored polygons sharing a single set of
+ *  vertices. Mirrors MATLAB's Faces/Vertices model — `patch(X,Y,C)` and the
+ *  name-value forms are all canonicalized to this shape at parse time. */
+export interface PatchTrace {
+    /** Unique vertices: `vertices[k] = [x, y]` (2-D) or `[x, y, z]` (3-D). */
+    vertices: number[][];
+    /** Faces as 0-based vertex-index arrays — one polygon per face. */
+    faces: number[][];
+    /** Single RGB for all faces, a colormap keyword, or 'none'. */
+    faceColor?: [number, number, number] | "flat" | "interp" | "none";
+    /** Edge color (default black [0,0,0]). */
+    edgeColor?: [number, number, number] | "flat" | "interp" | "none";
+    /** Face transparency in [0,1]. */
+    faceAlpha?: number;
+    lineWidth?: number;
+    lineStyle?: string;
+    marker?: string;
+    markerFaceColor?: [number, number, number] | "flat" | "none";
+    /** Color data driving 'flat'/'interp': one entry per face (flat) or per
+     *  vertex (interp). Each entry is a scalar (mapped through the colormap) or
+     *  an RGB triplet. */
+    faceVertexCData?: (number | [number, number, number])[];
+    /** True when vertices carry a z-coordinate (3-D patch). */
+    is3D?: boolean;
+    /** See PlotTrace.id — lets `set(p,...)` live-update this patch. */
+    id?: number;
 }
 export interface SurfTrace {
     /** X coordinates: flat array of length rows*cols (column-major) */
@@ -219,6 +252,12 @@ export interface HeatmapTrace {
     /** Y-axis labels (one per row) */
     yLabels?: string[];
 }
+/** A single axis's limit request from `axis([...])` / `axis auto`.
+ *  - A `[lo, hi]` pair, where either bound may be `null` to mean "keep the
+ *    automatically-chosen bound" (from `inf`/`-inf` in the limits vector).
+ *  - The string `"auto"` clears any explicit limit so the axis refits to its
+ *    data (from `axis auto` / `axis 'auto x'`). */
+export type AxisLimitSpec = [number | null, number | null] | "auto";
 export type PlotInstruction = {
     type: "set_figure_handle";
     handle: number;
@@ -228,6 +267,19 @@ export type PlotInstruction = {
 } | {
     type: "plot3";
     traces: Plot3Trace[];
+} | {
+    type: "line";
+    traces: PlotTrace[];
+} | {
+    type: "line3";
+    traces: Plot3Trace[];
+} | {
+    type: "patch";
+    trace: PatchTrace;
+} | {
+    type: "update_trace";
+    id: number;
+    props: Record<string, unknown>;
 } | {
     type: "surf";
     trace: SurfTrace;
@@ -321,6 +373,9 @@ export type PlotInstruction = {
 } | {
     type: "set_grid";
     value: boolean;
+} | {
+    type: "set_box";
+    value: boolean;
 } | {
     type: "set_colorbar";
     value: string;
@@ -332,6 +387,17 @@ export type PlotInstruction = {
 } | {
     type: "set_axis";
     value: string;
+} | {
+    type: "set_axis_limits";
+    xlim?: AxisLimitSpec;
+    ylim?: AxisLimitSpec;
+    zlim?: AxisLimitSpec;
+} | {
+    type: "set_axis_ydir";
+    dir: "normal" | "reverse";
+} | {
+    type: "set_axis_visible";
+    value: boolean;
 } | {
     type: "set_axis_scale";
     value: "linear" | "semilogx" | "semilogy" | "loglog";