@aics/vole-app 2.13.7 → 2.14.0

package/es/index.js

@@ -1,4 +1,5 @@
+import { parseViewerUrlParams } from "./aics-image-viewer/shared/utils/urlParsing";
 import ImageViewerApp from "./aics-image-viewer/components/App";
 import ViewerStateProvider from "./aics-image-viewer/components/ViewerStateProvider";
 export { ViewMode, RenderMode, ImageType } from "./aics-image-viewer/shared/enums";
-export { ImageViewerApp, ViewerStateProvider };
+export { ImageViewerApp, ViewerStateProvider, parseViewerUrlParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aics/vole-app",
-  "version": "2.13.7",
+  "version": "2.14.0",
   "description": "web view of cell volume images",
   "repository": "github:allen-cell-animated/vole-app",
   "main": "es/index.js",

package/type-declarations/aics-image-viewer/components/App/types.d.ts

@@ -42,5 +42,6 @@ export interface AppProps {
     metadataFormatter?: (metadata: MetadataRecord) => MetadataRecord;
     onControlPanelToggle?: (collapsed: boolean) => void;
     showError?: (error: any) => void;
+    onImageTitleChange?: (title: string | undefined) => void;
 }
 export {};

package/type-declarations/aics-image-viewer/components/Toolbar/index.d.ts

@@ -27,5 +27,5 @@ type ToolbarProps = {
     changeViewerSetting: ViewerSettingUpdater;
     resetToSavedViewerState: () => void;
 };
-declare const _default: React.FC<Omit<ToolbarProps, "viewMode" | "renderMode" | "imageType" | "showAxes" | "showBoundingBox" | "autorotate" | "changeViewerSetting" | "resetToSavedViewerState">>;
+declare const _default: React.FC<Omit<ToolbarProps, "viewMode" | "renderMode" | "imageType" | "showAxes" | "showBoundingBox" | "autorotate" | "resetToSavedViewerState" | "changeViewerSetting">>;
 export default _default;

package/type-declarations/aics-image-viewer/components/ViewerStateProvider/index.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import type { ViewerState, ViewerStateContextType } from "./types";
-export declare const ALL_VIEWER_STATE_KEYS: (keyof ViewerState | "changeViewerSetting" | "setChannelSettings" | "channelSettings" | "changeChannelSetting" | "applyColorPresets" | keyof import("./types").ResetState)[];
+export declare const ALL_VIEWER_STATE_KEYS: (keyof ViewerState | keyof import("./types").ResetState | "channelSettings" | "changeViewerSetting" | "changeChannelSetting" | "setChannelSettings" | "applyColorPresets")[];
 type NoNull<T> = {
     [K in keyof T]: NonNullable<T[K]>;
 };

package/type-declarations/aics-image-viewer/shared/utils/datatypes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns a (shallow) copy of an object with all properties that are
+ * `undefined` removed.
+ */
+export declare function removeUndefinedProperties<T>(obj: T): Partial<T>;
+/**
+ * Returns a copy of `obj` where all properties with values that match the properties of `match`
+ * are removed. Matching is determined by deep equality (see `isDeepEqual()`).
+ */
+export declare function removeMatchingProperties<T extends Object>(obj: Partial<T>, match: T): Partial<T>;

package/type-declarations/aics-image-viewer/shared/utils/firebase/index.d.ts

@@ -0,0 +1,69 @@
+import { DocumentData, FirebaseFirestore } from "@firebase/firestore-types";
+export interface DatasetMetaData {
+    name: string;
+    version: string;
+    datasets?: {
+        [key: string]: DatasetMetaData;
+    };
+    id: string;
+    description: string;
+    image: string;
+    link?: string;
+    manifest?: string;
+    production?: boolean;
+    userData: {
+        isNew: boolean;
+        inReview: boolean;
+        totalTaggedStructures: number;
+        totalCells: number;
+        totalFOVs: number;
+    };
+}
+export interface FileInfo {
+    CellId: string;
+    CellLineName: string;
+    FOVId: string;
+    structureProteinName: string;
+    fovThumbnailPath: string;
+    fovVolumeviewerPath: string;
+    thumbnailPath: string;
+    volumeviewerPath: string;
+}
+interface ManifestDocumentData extends DocumentData {
+    featuresDataPath: string;
+    cellLineDataPath: string;
+    thumbnailRoot: string;
+    downloadRoot: string;
+    volumeViewerDataRoot: string;
+    featuresDisplayOrder: string[];
+    defaultXAxis: string;
+    defaultYAxis: string;
+    fileInfoPath: string;
+    featuresDataOrder: string[];
+    albumPath: string;
+    featureDefsPath: string;
+}
+declare class FirebaseRequest {
+    private firestore;
+    private fileInfoPath;
+    private collectionRef;
+    private featuresDataPath;
+    private cellLineDataPath;
+    private thumbnailRoot;
+    private downloadRoot;
+    private volumeViewerDataRoot;
+    private featuresDisplayOrder;
+    private datasetId;
+    private featuresDataOrder;
+    private albumPath;
+    private featureDefsPath;
+    constructor(firestore: FirebaseFirestore);
+    private getDoc;
+    getAvailableDatasets: () => Promise<DatasetMetaData[]>;
+    setCollectionRef: (id: string) => void;
+    private getManifest;
+    selectDataset: (ref: string) => Promise<ManifestDocumentData>;
+    getFileInfoByCellId: (cellId: string) => Promise<FileInfo | undefined>;
+    getFileInfoByArrayOfCellIds: (cellIds: string[]) => Promise<(FileInfo | undefined)[]>;
+}
+export default FirebaseRequest;

package/type-declarations/aics-image-viewer/shared/utils/math.d.ts

@@ -0,0 +1 @@
+export declare function clamp(value: number, min: number, max: number): number;

package/type-declarations/aics-image-viewer/shared/utils/urlParsing.d.ts

@@ -0,0 +1,344 @@
+import { CameraState } from "@aics/vole-core";
+import { FirebaseFirestore } from "@firebase/firestore-types";
+import type { AppProps } from "../../components/App/types";
+import type { ChannelState, ViewerState, ViewerStateContextType } from "../../components/ViewerStateProvider/types";
+import { ViewMode } from "../enums";
+import type { MetadataRecord } from "../types";
+import { ColorArray } from "./colorRepresentations";
+import type { ViewerChannelSetting } from "./viewerChannelSettings";
+export declare const ENCODED_COMMA_REGEX: RegExp;
+export declare const ENCODED_COLON_REGEX: RegExp;
+/**
+ * LEGACY: Matches a COMMA-separated list of control points, where each control point is represented
+ * by a triplet of `{x}:{opacity}:{hex color}`.
+ * The hex color can be replaced with `w` to represent white (`ffffff`).
+ */
+export declare const LEGACY_CONTROL_POINTS_REGEX: RegExp;
+/**
+ * Matches a COLON-separated list of control points, where each control point is represented
+ * by a triplet of `{x}:{opacity}:{hex color}`.
+ * The hex color can be replaced with `w` to represent white (`ffffff`).
+ */
+export declare const CONTROL_POINTS_REGEX: RegExp;
+/**
+ * Enum keys for URL parameters. These are stored as enums for better readability,
+ * and are mapped to types in `ViewerStateParams`.
+ */
+export declare enum ViewerStateKeys {
+    View = "view",
+    Mode = "mode",
+    Mask = "mask",
+    Image = "image",
+    Axes = "axes",
+    BoundingBox = "bb",
+    BoundingBoxColor = "bbcol",
+    BackgroundColor = "bgcol",
+    Autorotate = "rot",
+    Brightness = "bright",
+    Density = "dens",
+    Levels = "lvl",
+    Interpolation = "interp",
+    Region = "reg",
+    Slice = "slice",
+    Time = "t",
+    Scene = "scene",
+    CameraState = "cam"
+}
+export declare enum CameraTransformKeys {
+    /** Camera position in 3D coordinates. */
+    Position = "pos",
+    /** Target position of the trackball controls in 3D coordinates. */
+    Target = "tar",
+    /** The up vector of the camera. Will be normalized to magnitude of 1. */
+    Up = "up",
+    /** Scale factor for orthographic cameras. */
+    OrthoScale = "ort",
+    /** Vertical FOV of the camera view frustum, from top to bottom, in degrees. */
+    Fov = "fov"
+}
+/**
+ * Mapped to types in `ViewerChannelSettingParams`
+ */
+export declare enum ViewerChannelSettingKeys {
+    Color = "col",
+    Colorize = "clz",
+    ColorizeAlpha = "cza",
+    IsosurfaceAlpha = "isa",
+    Lut = "lut",
+    Ramp = "rmp",
+    ControlPoints = "cps",
+    ControlPointsEnabled = "cpe",
+    VolumeEnabled = "ven",
+    SurfaceEnabled = "sen",
+    IsosurfaceValue = "isv"
+}
+/**
+ * The serialized form of a ViewerChannelSetting, as a dictionary object.
+ */
+export declare class ViewerChannelSettingParams {
+    /** Color, as a 6-digit hex color.  */
+    [ViewerChannelSettingKeys.Color]?: string;
+    /** Colorize. "1" is enabled. Disabled by default. */
+    [ViewerChannelSettingKeys.Colorize]?: "1" | "0";
+    /** Colorize alpha, in the [0, 1] range. Set to `1.0` by default. */
+    [ViewerChannelSettingKeys.ColorizeAlpha]?: string;
+    /** Isosurface alpha, in the [0, 1 range]. Set to `1.0` by default.*/
+    [ViewerChannelSettingKeys.IsosurfaceAlpha]?: string;
+    /**
+     * Lookup table (LUT) to map from volume intensity to opacity. Should be two
+     * alphanumeric values separated by a colon, where the first value is the
+     * minimum and the second is the maximum. Defaults to [0, 255].
+     *
+     * Min and max values are determined as following:
+     * - Plain numbers are indices of histogram bins, typically in the range [0,
+     *   255].
+     * - `v{n}` represents a raw intensity value, where `n` is a number.
+     * - `p{n}` represents a percentile, where `n` is a percentile in the [0, 100]
+     *   range.
+     * - `m{n}` represents the median multiplied by `n / 100`.
+     * - `autoij` in either the min or max fields will use the "auto" algorithm
+     *   from ImageJ to select the min and max.
+     *
+     * Values will be used to determine the initial control points and ramp if
+     * those fields are not provided.
+     *
+     * @example
+     * ```
+     * "0:255"    // min: intensity 0, max: intensity 255.
+     * "p50:p90"  // min: 50th percentile, max: 90th percentile.
+     * "m1:p75"   // min: median, max: 75th percentile.
+     * "autoij:0" // use Auto-IJ to calculate min and max.
+     * ```
+     */
+    [ViewerChannelSettingKeys.Lut]?: string;
+    /**
+     * Control points for the transfer function. If provided, overrides the
+     * `lut` field when calculating the control points. Should be a list
+     * of `x:opacity:color` triplets, separated by colon.
+     * - `x` is a numeric intensity value.
+     * - `opacity` is a float in the [0, 1] range.
+     * - `color` is a 6-digit hex color, e.g. `ff0000`.
+     */
+    [ViewerChannelSettingKeys.ControlPoints]?: string;
+    /**
+     * Whether to show advanced mode, which will show control points instead of
+     * ramp values defined by the LUT. "1" is enabled, disabled by default.
+     */
+    [ViewerChannelSettingKeys.ControlPointsEnabled]?: "1" | "0";
+    /**
+     * Raw ramp values, which should be two numeric values separated by a colon.
+     * If provided, overrides the `lut` field when calculating the ramp values.
+     */
+    [ViewerChannelSettingKeys.Ramp]?: string;
+    /** Volume enabled. "1" is enabled. Disabled by default. */
+    [ViewerChannelSettingKeys.VolumeEnabled]?: "1" | "0";
+    /** Isosurface enabled. "1" is enabled. Disabled by default. */
+    [ViewerChannelSettingKeys.SurfaceEnabled]?: "1" | "0";
+    /** Isosurface value, in the [0, 255] range. Set to `128` by default. */
+    [ViewerChannelSettingKeys.IsosurfaceValue]?: string;
+}
+/**
+ * Channels, matching the pattern `c0`, `c1`, etc. corresponding to the index of the channel being configured.
+ * The channel parameter should have a value that is a comma-separated list of `key:value` pairs, with keys
+ * defined in `ViewerChannelSettingJson`.
+ */
+type ChannelParams = {
+    [_ in `c${number}`]?: string;
+};
+/** Serialized version of `ViewerState`. */
+export declare class ViewerStateParams {
+    /** Axis to view. Valid values are "3D", "X", "Y", and "Z". Defaults to "3D". */
+    [ViewerStateKeys.View]?: string;
+    /**
+     * Render mode. Valid values are "volumetric", "maxproject", and "pathtrace".
+     * Defaults to "volumetric".
+     */
+    [ViewerStateKeys.Mode]?: string;
+    /** The opacity of the mask channel, an integer in the range [0, 100]. Defaults to 50. */
+    [ViewerStateKeys.Mask]?: string;
+    /** The type of image to display. Valid values are "cell" and "fov". Defaults to "cell". */
+    [ViewerStateKeys.Image]?: string;
+    /** Whether to show the axes helper. "1" is enabled. Disabled by default. */
+    [ViewerStateKeys.Axes]?: string;
+    /** Whether to show the bounding box. "1" is enabled. Disabled by default. */
+    [ViewerStateKeys.BoundingBox]?: string;
+    /** The color of the bounding box, as a 6-digit hex color. */
+    [ViewerStateKeys.BoundingBoxColor]?: string;
+    /** The background color, as a 6-digit hex color. */
+    [ViewerStateKeys.BackgroundColor]?: string;
+    /** Whether to autorotate the view. "1" is enabled. Disabled by default. */
+    [ViewerStateKeys.Autorotate]?: string;
+    /** The brightness of the image, an float in the range [0, 100]. Defaults to 70. */
+    [ViewerStateKeys.Brightness]?: string;
+    /** Density, a float in the range [0, 100]. Defaults to 50. */
+    [ViewerStateKeys.Density]?: string;
+    /**
+     * Levels for image intensity adjustment. Should be three numeric values separated
+     * by commas, representing the low, middle, and high values in a [0, 255] range.
+     * Values will be sorted in ascending order; empty values will be parsed as 0.
+     */
+    [ViewerStateKeys.Levels]?: string;
+    /** Whether to enable interpolation. "1" is enabled. Enabled by default. */
+    [ViewerStateKeys.Interpolation]?: string;
+    /** Subregions per axis, as min:max pairs separated by commas.
+     * Defaults to full range (`0:1`) for each axis.
+     */
+    [ViewerStateKeys.Region]?: string;
+    /** Slice position per X, Y, and Z axes, as a list of comma-separated floats.
+     * 0.5 for all axes by default (e.g. `0.5,0.5,0.5`)
+     */
+    [ViewerStateKeys.Slice]?: string;
+    /** Frame number, for time-series volumes. 0 by default. */
+    [ViewerStateKeys.Time]?: string;
+    /** Scene number, for multiscene images. 0 by default. */
+    [ViewerStateKeys.Scene]?: string;
+    /**
+     * Camera transform settings, as a list of `key:value` pairs separated by commas.
+     * Valid keys are defined in `CameraTransformKeys`:
+     * - `pos`: position
+     * - `tar`: target
+     * - `up`: up
+     * - `rot`: rotation
+     * - `ort`: orthographic scales
+     *
+     * All values are an array of three floats, separated by commas and
+     * encoded using `encodeURIComponent`.
+     */
+    [ViewerStateKeys.CameraState]?: string;
+}
+/** URL parameters that define data sources when loading volumes. */
+declare class DataParams {
+    /**
+     * One or more volume URLs to load. If multiple URLs are provided, they should
+     * be separated by commas.
+     */
+    url?: string;
+    /**
+     * The URL of a JSON manifest. The JSON should contain two properties:
+     *  - "scenes": A string array of volume URLs.
+     *  - "meta": An array of metadata dictionary objects.
+     *
+     * See `ManifestJson` for the type definition.
+     */
+    manifest?: string;
+    /**
+     * The name of a dataset in the Cell Feature Explorer database. Used with `id`.
+     */
+    dataset?: string;
+    /**
+     * The ID of a cell within the loaded dataset. Used with `dataset`.
+     */
+    id?: string;
+}
+declare class DeprecatedParams {
+    /** Deprecated query parameter for channel settings. */
+    ch?: string;
+    /** Deprecated query parameter for LUT settings. */
+    luts?: string;
+    /** Deprecated query parameter for channel colors. */
+    colors?: string;
+}
+type AppParams = Partial<ViewerStateParams & DataParams & DeprecatedParams & ChannelParams>;
+/**
+ * Filters a set of URLSearchParams for only the keys that are valid parameters for the viewer.
+ * Non-matching keys are discarded.
+ * @param searchParams Input URL search parameters.
+ * @returns a dictionary object matching the type of `Params`.
+ */
+export declare function getAllowedParams(searchParams: URLSearchParams): AppParams;
+/**
+ * Parse a string list of comma-separated key:value pairs into
+ * a key-value object.
+ *
+ * @param data The string to parse. Expected to be in the format
+ * "key1:value1,key2:value2,...". Commas in keys or values
+ * must be encoded using `encodeURIComponent`.
+ * @returns An object with the parsed key-value pairs. Key and value strings
+ *  will be decoded using `decodeURIComponent`.
+ */
+export declare function parseKeyValueList(data: string): Record<string, string>;
+export declare function objectToKeyValueList(obj: Record<string, string | undefined>): string;
+/**
+ * Parses a string to a float and clamps the result to the [min, max] range.
+ * Returns `undefined` if the string is undefined or NaN.
+ * @param value String to parse as a float. Will be parsed with `Number.parseFloat`.
+ * @param min Minimum value, inclusive.
+ * @param max Maximum value, inclusive.
+ * @returns
+ * - The parsed number, clamped to the [min, max] range.
+ * - `undefined` if the string is undefined or NaN.
+ */
+export declare function parseStringFloat(value: string | undefined, min: number, max: number): number | undefined;
+/**
+ * Parses a string to an integer and clamps the result to the [min, max] range.
+ * @param value String to parse as a float. Assumes base 10, parses with `Number.parseInt(value, 10)`.
+ * @param min Minimum value, inclusive.
+ * @param max Maximum value, inclusive.
+ * @returns
+ * - The parsed number, clamped to the [min, max] range.
+ * - `undefined` if the string is undefined or NaN.
+ */
+export declare function parseStringInt(value: string | undefined, min: number, max: number): number | undefined;
+/**
+ * Parses a string to an enum value; if the string is not in the enum, returns the default value.
+ * @param value String to parse.
+ * @param enumValues Enum. Cannot be a `const enum`, as these are removed at compile time.
+ * @param defaultValue Default value to return if the string is not in the enum.
+ * @returns A value from the enum or the default value. Note that the return type includes `undefined`
+ * if the `defaultValue` is `undefined`.
+ */
+export declare function parseStringEnum<E extends string, T extends E | undefined>(value: string | undefined, enumValues: Record<string | number | symbol, E>, defaultValue?: T): T;
+export declare function parseHexColorAsColorArray(hexColor: string | undefined): ColorArray | undefined;
+export declare function serializeCameraState(cameraState: Partial<CameraState>, removeDefaults: boolean, viewMode?: ViewMode): string | undefined;
+/**
+ * Parses a ViewerChannelSetting from a JSON object.
+ * @param channelIndex Index of the channel, to be turned into a `match` value.
+ * @param jsonState The serialized ViewerChannelSetting to parse, as an object.
+ * @returns A ViewerChannelSetting object.
+ */
+export declare function deserializeViewerChannelSetting(channelIndex: number, jsonState: ViewerChannelSettingParams): ViewerChannelSetting;
+/**
+ * Serializes a single viewer channel setting into a dictionary of URL parameters
+ * (`ViewerChannelSettingParams`).
+ * @param channelSetting The channel state object to serialize.
+ * @param removeDefaults Whether to remove properties that match the output of `GET_DEFAULT_CHANNEL_STATE`.
+ * @returns A `ViewerChannelSettingParams` object with the serialized parameters. Undefined values are removed.
+ */
+export declare function serializeViewerChannelSetting(channelSetting: Partial<ChannelState>, removeDefaults: boolean): Partial<ViewerChannelSettingParams>;
+export declare function deserializeViewerState(params: ViewerStateParams): Partial<ViewerState>;
+/**
+ * Serializes a ViewerState object into a dictionary of URL parameters.
+ * @param state The ViewerState to serialize.
+ * @param removeDefaults If true, remove properties that match the output of `GET_DEFAULT_VIEWER_STATE`.
+ * @returns A `ViewerStateParams` object with the serialized parameters. Undefined values are removed.
+ */
+export declare function serializeViewerState(state: Partial<ViewerState>, removeDefaults: boolean): ViewerStateParams;
+export declare function loadFromManifest(manifestUrl: string): Promise<{
+    scenes: (string | string[])[];
+    metadata?: MetadataRecord[];
+}>;
+/**
+ * Parses a set of URL search parameters into props for the viewer.
+ * @param urlSearchParams The URLSearchParams object to parse.
+ * @param firestore Optional Firestore instance. If provided, the function can
+ * load data from a Firestore dataset if the `dataset` and `id` parameters are
+ * provided.
+ * @returns An object containing:
+ * - `args`: Partial AppProps object.
+ * - `viewerSettings`: Partial ViewerState object.
+ *
+ * `args` can be passed as props to the `ImageViewerApp`, and `viewerSettings`
+ * can be passed to `ViewerStateProvider`.
+ */
+export declare function parseViewerUrlParams(urlSearchParams: URLSearchParams, firestore?: FirebaseFirestore): Promise<{
+    args: Partial<AppProps>;
+    viewerSettings: Partial<ViewerState>;
+}>;
+/**
+ * Serializes the ViewerState and ChannelState of a ViewerStateContext into a URLSearchParams object.
+ * @param state ViewerStateContext to serialize.
+ * @param removeDefaults If true, shortens parameters by removing any properties that match the default state.
+ * This includes the output of GET_DEFAULT_VIEWER_STATE and GET_DEFAULT_CHANNEL_STATE.
+ */
+export declare function serializeViewerUrlParams(state: Partial<ViewerStateContextType>, removeDefaults?: boolean): AppParams;
+export {};

package/type-declarations/index.d.ts

@@ -1,7 +1,9 @@
+import { parseViewerUrlParams } from "./aics-image-viewer/shared/utils/urlParsing";
 import ImageViewerApp from "./aics-image-viewer/components/App";
 import ViewerStateProvider from "./aics-image-viewer/components/ViewerStateProvider";
 export type { ViewerChannelSettings, ViewerChannelGroup, ViewerChannelSetting, } from "./aics-image-viewer/shared/utils/viewerChannelSettings";
+export type { ViewerState } from "./aics-image-viewer/components/ViewerStateProvider/types";
 export { ViewMode, RenderMode, ImageType } from "./aics-image-viewer/shared/enums";
 export type { AppProps } from "./aics-image-viewer/components/App/types";
 export type { RawArrayData, RawArrayInfo } from "@aics/vole-core";
-export { ImageViewerApp, ViewerStateProvider };
+export { ImageViewerApp, ViewerStateProvider, parseViewerUrlParams };