@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/util/markEncoding.d.ts

@@ -0,0 +1,150 @@
+import Flatbush from './flatbush/index.ts';
+import type { FeatureTable } from './featureTable.ts';
+import type { JexlInstance } from './jexlStrings.ts';
+import type { ColorEncoding, ColorScaleTable, ContinuousRef, Encoded, EncodedChannels, FieldRef, LocusRef, ShapeEncoding, SizeEncoding, LaneName } from './markEncodingTypes.ts';
+import type { ProgressReporter } from './progress.ts';
+import type { Feature } from './simpleFeature.ts';
+export type { AggregateOp, AggregateStep, BinStep, CategoricalRef, ColorEncoding, ContinuousRef, CoverageStep, ColorScaleTable, CoreGetEncodedLayersArgs, Encoded, EncodedChannels, EncodedLayersResult, FacetSection, FacetSpec, FieldRef, FilterStep, FormulaStep, LocusRef, MateStep, ShapeEncoding, ShapeName, ShapeScaleTable, SizeEncoding, SizeRef, SizeScaleTable, LaneName, LayerRequest, MarkEncoding, ScaleTable, ThresholdRef, TransformStep, } from './markEncodingTypes.ts';
+export type { ColorSchemeName } from './colorSchemes.ts';
+export { COLOR_SCHEMES } from './colorSchemes.ts';
+export { NO_VALUE_LABEL } from './categoricalField.ts';
+export declare const DEFAULT_MARK_COLOR = "#0068d1";
+export declare const DEFAULT_SIZE_RANGE_PX: [number, number];
+/**
+ * #api
+ * The misconfiguration grey packed as the encoder paints it: a `jexl:` colour
+ * that answered no string, a ramp value that is no number, text a threshold
+ * cannot read.
+ */
+export declare const MISCONFIGURED_ABGR: number;
+/**
+ * #api
+ * The no-value grey packed as the encoder paints it: a feature with nothing in
+ * the field a threshold reads.
+ */
+export declare const NO_VALUE_ABGR: number;
+/**
+ * #api
+ * A channel read per feature: the compiled form of a {@link FieldRef}, and
+ * what a display's own worker method hands the encoder for a channel no
+ * field name can say — a join against a second adapter, a lookup table, a
+ * rule over two fields.
+ */
+export type ChannelReader<T = unknown> = (feature: Feature) => T;
+/**
+ * #api
+ * What `encodeFeatures` takes: a {@link MarkEncoding}, any channel of which
+ * may be a {@link ChannelReader} in place of its declared form, and `row` the
+ * values themselves, one per input feature, where the caller computed them —
+ * a facet's stacked rows. The declared form is what crosses the wire; a
+ * reader or a value list is built in the worker.
+ */
+export interface MarkEncodingInput {
+    x?: FieldRef | ChannelReader;
+    x2?: FieldRef | LocusRef | ChannelReader;
+    y?: FieldRef | ChannelReader;
+    row?: FieldRef | ChannelReader | ArrayLike<number>;
+    color?: ColorEncoding | ChannelReader<number>;
+    shape?: ShapeEncoding | ChannelReader<number>;
+    text?: FieldRef | ChannelReader;
+    size?: SizeEncoding;
+}
+/**
+ * #api
+ * What surrounds an encode: the jexl instance a `jexl:` channel compiles
+ * against — a caller whose channels are all readers or field names passes
+ * none — and a progress reporter.
+ */
+export interface EncodeContext {
+    jexl?: JexlInstance;
+    report?: ProgressReporter;
+}
+/**
+ * #api
+ * The hit index over `count` instances: each a box from `x` to `x2` at its
+ * `y`, or at 0 for a mark with no value.
+ */
+export declare function hitIndexOf(x: Uint32Array, x2: Uint32Array, y: Float32Array | undefined, count?: number): Flatbush;
+/**
+ * #api
+ * An encoded payload as a display stores it: the hit index the worker built
+ * with {@link hitIndexOf}, wrapped once where the payload lands.
+ */
+export type HitIndexed<T extends EncodedChannels> = T & {
+    flatbush?: Flatbush;
+};
+/**
+ * #api
+ * {@link HitIndexed} over what the worker shipped.
+ */
+export declare function withHitIndex<T extends EncodedChannels>(channels: T): HitIndexed<T>;
+/**
+ * #api
+ * Evaluate one encoding over a feature list into dense channel arrays for
+ * the lanes named, the scale table each scaled channel came from, the `y`
+ * extremes and — when `index` is among the lanes — a hit index.
+ *
+ * A feature whose `x`, `x2` or (declared and asked-for) `y` is not finite is
+ * skipped and counted in `skipped`, so every array stays index-aligned with
+ * the Flatbush. Pure: the RPC around it owns the adapter, the filters and the
+ * transferables.
+ *
+ * Columnar: one pass admits the rows over `x`, `x2` and `y` alone, and none
+ * runs where all three are lanes of whole numbers; every other lane is then
+ * filled in its own loop over the admitted rows, a lane straight off a typed
+ * column and a categorical over a `category` column per label.
+ */
+export declare function encodeFeatures<L extends LaneName>(input: readonly Feature[] | FeatureTable, encoding: MarkEncodingInput, lanes: readonly L[], ctx?: EncodeContext): Encoded<L>;
+/**
+ * #api
+ * A continuous colour scale over `extent`, the values it met: the domain its
+ * declared ends and the extent make, the straight table its stops bake to and
+ * where its middle stop sits, and the packed colour a value paints through
+ * them: an infinity the end on its side, as a threshold places it, and NaN,
+ * text that is no number, the misconfiguration grey. The encoder and every
+ * display painting a ramp itself read it, so a value takes one colour whoever
+ * paints it.
+ */
+export declare function continuousColorScale(encoding: ContinuousRef, extent: readonly [number, number]): {
+    domain: [number, number];
+    lut: Uint8Array<ArrayBufferLike>;
+    midNorm: number;
+    colorOf: (value: number) => number;
+};
+/**
+ * #api
+ * A ramp table over `extent`, the union a display took across the regions it
+ * loaded: each open end of the domain moved to the union's, the pinned ends
+ * kept. The table stays straight and `domainMid` a value, so the middle stop
+ * follows the widened domain with no table baked again.
+ */
+export declare function rampOverExtent(table: Extract<ColorScaleTable, {
+    kind: 'ramp';
+}>, extent: [number, number]): Extract<ColorScaleTable, {
+    kind: 'ramp';
+}>;
+/**
+ * #api
+ * A CSS colour or `jexl:` colour expression as a per-feature packed ABGR —
+ * the unscaled arm of {@link ColorEncoding}, on its own for a display that
+ * carries a plain `color` slot.
+ */
+export declare function colorEvaluator(color: string, jexl: JexlInstance | undefined): (feature: Feature) => number;
+/**
+ * #api
+ * The input feature instance `i` of `channels` was: `featureIndex[i]`, or `i`
+ * itself where the encoder skipped none and so shipped no index.
+ */
+export declare function featureIndexAt(channels: Pick<EncodedChannels, 'featureIndex'>, i: number): number;
+/**
+ * #api
+ * The packed colour instance `i` of `channels` paints: `color[i]`, or `color`
+ * itself where the colour is a constant and so shipped as one number.
+ */
+export declare function colorAt(channels: Pick<EncodedChannels, 'color'>, i: number): number | undefined;
+/**
+ * #api
+ * The buffers an {@link EncodedChannels} owns, for `rpcResult`'s transfer
+ * list.
+ */
+export declare function encodedChannelTransferables(c: EncodedChannels): ArrayBufferLike[];