State gallery: Config

midlik · midlik · commit 453e313b863e · 2024-07-30T13:58:20.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ All notable changes to this project will be documented in this file, following t
 - Added options `leftPanel`, `rightPanel`, `logPanel`
 - All color options accept color names and hexcodes
 - `visualStyle` option allows per-component specification
+- StateGallery extension (work in progress)
 
 ## [v3.2.0] - 2024-04-24
 - Mol* core dependency updated to 3.45.0
diff --git a/src/app/extensions/state-gallery/behavior.ts b/src/app/extensions/state-gallery/behavior.ts
@@ -1,7 +1,6 @@
-import { Model, Structure } from 'molstar/lib/mol-model/structure';
 import { PluginBehavior } from 'molstar/lib/mol-plugin/behavior';
-import { StateGalleryControls } from './ui';
 import { StateGalleryManager } from './manager';
+import { StateGalleryControls } from './ui';
 
 
 /** All public functions provided by the StateGallery extension  */
@@ -60,9 +59,3 @@ export const StateGallery = PluginBehavior.create<{ autoAttach: boolean }>({
     //     serverUrl: PD.Text(AssemblySymmetryData.DefaultServerUrl)
     // })
 });
-
-
-// TODO move elsewhere
-export function isApplicable(structure?: Structure): boolean {
-    return !!structure && structure.models.length === 1 && Model.hasPdbId(structure.models[0]);
-}
diff --git a/src/app/extensions/state-gallery/config.ts b/src/app/extensions/state-gallery/config.ts
@@ -0,0 +1,30 @@
+import { PluginConfigItem } from 'molstar/lib/mol-plugin/config';
+import { PluginContext } from 'molstar/lib/mol-plugin/context';
+import { PluginConfigUtils } from '../../helpers';
+
+
+export const StateGalleryConfigDefaults = {
+    /** Base URL of the state API (list of states will be downloaded from `{ServerUrl}/{entryId}.json`, states from `{ServerUrl}/{stateName}.molj`) */
+    ServerUrl: 'https://www.ebi.ac.uk/pdbe/static/entry',
+    /** Load canvas properties, such as background, axes indicator, fog, outline (if false, keep current canvas properties) */
+    LoadCanvasProps: false,
+    /** Load camera orientation when loading state (if false, keep current orientation) */
+    LoadCameraOrientation: true,
+    /** Time in miliseconds between loading state and starting camera transition */
+    CameraPreTransitionMs: 100,
+    /** Duration of the camera transition in miliseconds */
+    CameraTransitionMs: 400,
+};
+export type StateGalleryConfigValues = typeof StateGalleryConfigDefaults;
+
+export const StateGalleryConfig: PluginConfigUtils.ConfigFor<StateGalleryConfigValues> = {
+    ServerUrl: new PluginConfigItem<string>('pdbe-state-gallery.server-url', StateGalleryConfigDefaults.ServerUrl),
+    LoadCanvasProps: new PluginConfigItem<boolean>('pdbe-state-gallery.load-canvas-props', StateGalleryConfigDefaults.LoadCanvasProps),
+    LoadCameraOrientation: new PluginConfigItem<boolean>('pdbe-state-gallery.load-camera-orientation', StateGalleryConfigDefaults.LoadCameraOrientation),
+    CameraPreTransitionMs: new PluginConfigItem<number>('pdbe-state-gallery.camera-pre-transition-ms', StateGalleryConfigDefaults.CameraPreTransitionMs),
+    CameraTransitionMs: new PluginConfigItem<number>('pdbe-state-gallery.camera-transition-ms', StateGalleryConfigDefaults.CameraTransitionMs),
+};
+
+export function getStateGalleryConfig(plugin: PluginContext): StateGalleryConfigValues {
+    return PluginConfigUtils.getConfigValues(plugin, StateGalleryConfig, StateGalleryConfigDefaults);
+}
diff --git a/src/app/extensions/state-gallery/manager.ts b/src/app/extensions/state-gallery/manager.ts
@@ -7,12 +7,7 @@ import { isPlainObject } from 'molstar/lib/mol-util/object';
 import { sleep } from 'molstar/lib/mol-util/sleep';
 import { BehaviorSubject } from 'rxjs';
 import { PreemptiveQueue, PreemptiveQueueResult, combineUrl, distinct } from '../../helpers';
-
-
-const LOAD_BACKGROUND = false; // TODO put to config+param
-const LOAD_CAMERA_ORIENTATION = true; // TODO put to config+param
-const CAMERA_PRE_TRANSITION_MS = 100; // TODO put to config+param
-const CAMERA_TRANSITION_MS = 400; // TODO put to config+param
+import { StateGalleryConfigValues, getStateGalleryConfig } from './config';
 
 
 export interface StateGalleryData {
@@ -81,23 +76,26 @@ export class StateGalleryManager {
     public readonly images: Image[];
     public readonly requestedStateName = new BehaviorSubject<string | undefined>(undefined);
     public readonly loadedStateName = new BehaviorSubject<string | undefined>(undefined);
+    /** True if at least one state has been loaded (this is to skip animation on the first load) */
     private firstLoaded = false;
 
     private constructor(
         public readonly plugin: PluginContext,
-        public readonly serverUrl: string,
         public readonly entryId: string,
         public readonly data: StateGalleryData | undefined,
+        public readonly options: StateGalleryConfigValues,
     ) {
-        this.images = removeWithSuffixes(listImages(data, true), ['_side', '_top']); // TODO allow suffixes by a parameter, sort by parameter
+        const allImages = listImages(data, true);
+        this.images = removeWithSuffixes(allImages, ['_side', '_top']); // removing images in different orientation than 'front'
     }
 
-    static async create(plugin: PluginContext, serverUrl: string, entryId: string) {
-        const data = await getData(plugin, serverUrl, entryId);
+    static async create(plugin: PluginContext, entryId: string, options?: Partial<StateGalleryConfigValues>) {
+        const fullOptions = { ...getStateGalleryConfig(plugin), ...options };
+        const data = await getData(plugin, fullOptions.ServerUrl, entryId);
         if (data === undefined) {
             console.error(`StateGalleryManager failed to get data for entry ${entryId}`);
         }
-        return new this(plugin, serverUrl, entryId, data);
+        return new this(plugin, entryId, data, fullOptions);
     }
 
     private async _load(filename: string): Promise<void> {
@@ -108,17 +106,18 @@ export class StateGalleryManager {
         const incomingCamera = getCameraFromSnapshot(snapshot); // Camera position from the MOLJ file, which may be incorrectly zoomed if viewport width < height
         const newCamera: Camera.Snapshot = { ...oldCamera, ...refocusCameraSnapshot(this.plugin.canvas3d.camera, incomingCamera) };
         snapshot = modifySnapshot(snapshot, {
-            removeBackground: !LOAD_BACKGROUND,
+            removeCanvasProps: !this.options.LoadCanvasProps,
             replaceCamera: {
-                camera: (LOAD_CAMERA_ORIENTATION && !this.firstLoaded) ? newCamera : oldCamera,
+                camera: (this.options.LoadCameraOrientation && !this.firstLoaded) ? newCamera : oldCamera,
                 transitionDurationInMs: 0,
             }
         });
-        const file = new File([snapshot], `${filename}.molj`);
-        await PluginCommands.State.Snapshots.OpenFile(this.plugin, { file });
-        // await this.plugin.managers.snapshot.setStateSnapshot(JSON.parse(data));
-        await sleep(this.firstLoaded ? CAMERA_PRE_TRANSITION_MS : 0); // it is necessary to sleep even for 0 ms here, to get animation
-        await PluginCommands.Camera.Reset(this.plugin, { snapshot: LOAD_CAMERA_ORIENTATION ? newCamera : undefined, durationMs: this.firstLoaded ? CAMERA_TRANSITION_MS : 0 });
+        await this.plugin.managers.snapshot.setStateSnapshot(JSON.parse(snapshot));
+        await sleep(this.firstLoaded ? this.options.CameraPreTransitionMs : 0); // it is necessary to sleep even for 0 ms here, to get animation
+        await PluginCommands.Camera.Reset(this.plugin, {
+            snapshot: this.options.LoadCameraOrientation ? newCamera : undefined,
+            durationMs: this.firstLoaded ? this.options.CameraTransitionMs : 0,
+        });
 
         this.firstLoaded = true;
     }
@@ -135,7 +134,7 @@ export class StateGalleryManager {
 
     private readonly cache: { [filename: string]: string } = {};
     private async fetchSnapshot(filename: string): Promise<string> {
-        const url = combineUrl(this.serverUrl, `${filename}.molj`);
+        const url = combineUrl(this.options.ServerUrl, `${filename}.molj`);
         const data = await this.plugin.runTask(this.plugin.fetch({ url, type: 'string' }));
         return data;
     }
@@ -145,7 +144,7 @@ export class StateGalleryManager {
 }
 
 
-async function getData(plugin: PluginContext, serverUrl: string, entryId: string) {
+async function getData(plugin: PluginContext, serverUrl: string, entryId: string): Promise<StateGalleryData | undefined> {
     const url = combineUrl(serverUrl, entryId + '.json');
     try {
         const text = await plugin.runTask(plugin.fetch(url));
@@ -161,7 +160,6 @@ function listImages(data: StateGalleryData | undefined, byCategory: boolean = fa
         const out: Image[] = [];
 
         // Entry
-        // out.push(...data?.entry?.all?.image ?? []);
         for (const img of data?.entry?.all?.image ?? []) {
             const title = img.filename.includes('_chemically_distinct_molecules')
                 ? 'Deposited model (color by entity)'
@@ -171,19 +169,16 @@ function listImages(data: StateGalleryData | undefined, byCategory: boolean = fa
             out.push({ ...img, category: 'Entry', simple_title: title });
         }
         // Validation
-        // out.push(...data?.validation?.geometry?.deposited?.image ?? []);
         for (const img of data?.validation?.geometry?.deposited?.image ?? []) {
             out.push({ ...img, category: 'Entry', simple_title: 'Geometry validation' });
         }
         // Bfactor
-        // out.push(...data?.entry?.bfactor?.image ?? []);
         for (const img of data?.entry?.bfactor?.image ?? []) {
             out.push({ ...img, category: 'Entry', simple_title: 'B-factor' });
         }
         // Assembly
         const assemblies = data?.assembly;
         for (const ass in assemblies) {
-            // out.push(...assemblies[ass].image);
             for (const img of assemblies[ass].image ?? []) {
                 const title = img.filename.includes('_chemically_distinct_molecules')
                     ? `Assembly ${ass} (color by entity)`
@@ -196,23 +191,20 @@ function listImages(data: StateGalleryData | undefined, byCategory: boolean = fa
         // Entity
         const entities = data?.entity;
         for (const entity in entities) {
-            // out.push(...entities[entity].image);
             for (const img of entities[entity].image ?? []) {
                 out.push({ ...img, category: 'Entities', simple_title: `Entity ${entity}` });
             }
         }
         // Ligand
         const ligands = data?.entry?.ligands;
         for (const ligand in ligands) {
-            // out.push(...ligands[ligand].image);
             for (const img of ligands[ligand].image ?? []) {
                 out.push({ ...img, category: 'Ligands', simple_title: `Ligand environment for ${ligand}` });
             }
         }
         // Modres
         const modres = data?.entry?.mod_res;
         for (const res in modres) {
-            // out.push(...modres[res].image);
             for (const img of modres[res].image ?? []) {
                 out.push({ ...img, category: 'Modified residues', simple_title: `Modified residue ${res}` });
             }
@@ -223,9 +215,8 @@ function listImages(data: StateGalleryData | undefined, byCategory: boolean = fa
             for (const db in dbs) {
                 const domains = dbs[db];
                 for (const domain in domains) {
-                    // out.push(...domains[domain].image);
                     for (const img of domains[domain].image ?? []) {
-                        out.push({ ...img, category: 'Domains', simple_title: `${db} ${domain} in entity ${entity}` });
+                        out.push({ ...img, category: 'Domains', simple_title: `${db} ${domain} (entity ${entity})` });
                     }
                 }
             }
@@ -257,12 +248,12 @@ function removeWithSuffixes(images: Image[], suffixes: string[]): Image[] {
     return images.filter(img => !suffixes.some(suffix => img.filename.endsWith(suffix)));
 }
 
-function modifySnapshot(snapshot: string, options: { removeBackground?: boolean, replaceCamera?: { camera: Camera.Snapshot, transitionDurationInMs: number } }) {
+function modifySnapshot(snapshot: string, options: { removeCanvasProps?: boolean, replaceCamera?: { camera: Camera.Snapshot, transitionDurationInMs: number } }) {
     const json = JSON.parse(snapshot) as PluginStateSnapshotManager.StateSnapshot;
     for (const entry of json.entries ?? []) {
         if (entry.snapshot) {
-            if (options.removeBackground) {
-                delete entry.snapshot.canvas3d;
+            if (options.removeCanvasProps && entry.snapshot.canvas3d) {
+                delete entry.snapshot.canvas3d.props;
             }
             if (options.replaceCamera) {
                 const { camera, transitionDurationInMs } = options.replaceCamera;
diff --git a/src/app/extensions/state-gallery/ui.tsx b/src/app/extensions/state-gallery/ui.tsx
@@ -6,7 +6,7 @@ import { ParamDefinition as PD } from 'molstar/lib/mol-util/param-definition';
 import React from 'react';
 import { createIndex, groupElements, nonnegativeModulo } from '../../helpers';
 import { ChevronLeftSvg, ChevronRightSvg, CollectionsOutlinedSvg, EmptyIconSvg, HourglassBottomSvg } from '../../ui/icons';
-import { StateGalleryManager } from './manager';
+import { Image, StateGalleryManager } from './manager';
 
 
 interface StateGalleryControlsState {
@@ -79,7 +79,7 @@ export class StateGalleryControls extends CollapsableControls<{}, StateGalleryCo
     };
     private load = async () => {
         this.setState({ isLoading: true, description: undefined });
-        const manager = await StateGalleryManager.create(this.plugin, 'https://www.ebi.ac.uk/pdbe/static/entry', this.state.entryId);
+        const manager = await StateGalleryManager.create(this.plugin, this.state.entryId);
         this.setState({ manager, isLoading: false, description: this.state.entryId.toUpperCase() });
     };
     private onChangeValues = (values: Values) => {
@@ -104,10 +104,15 @@ export class StateGalleryControls extends CollapsableControls<{}, StateGalleryCo
 
 function ManagerControls(props: { manager: StateGalleryManager }) {
     const images = props.manager.images;
-    const categories = React.useMemo(() => groupElements(images, img => img.category ?? 'Miscellaneous'), [images]);
-    const imageIndex = React.useMemo(() => createIndex(images), [images]);
     const nImages = images.length;
-    const [selected, setSelected] = React.useState(images[0]);
+
+    if (nImages === 0) {
+        return <div style={{ margin: 8 }}>No data available for {props.manager.entryId}.</div>;
+    }
+
+    const imageIndex = React.useMemo(() => createIndex(images), [images]);
+    const categories = React.useMemo(() => groupElements(images, img => img.category ?? 'Miscellaneous'), [images]);
+    const [selected, setSelected] = React.useState<Image>(images[0]);
     const [status, setStatus] = React.useState<'ready' | 'loading' | 'error'>('ready');
 
     React.useEffect(() => {
@@ -119,7 +124,6 @@ function ManagerControls(props: { manager: StateGalleryManager }) {
 
     const keyDownTargetRef = React.useRef<HTMLDivElement>(null);
     React.useEffect(() => keyDownTargetRef.current?.focus(), []);
-    const selectedStateIcon = (status === 'loading') ? HourglassBottomSvg : (status === 'error') ? ErrorSvg : CheckSvg;
 
     const shift = (x: number) => setSelected(old => {
         const oldIndex = imageIndex.get(old) ?? 0;
@@ -133,20 +137,12 @@ function ManagerControls(props: { manager: StateGalleryManager }) {
         if (e.code === 'ArrowRight') selectNext();
     };
 
-    if (nImages === 0) {
-        return <div style={{ margin: 8 }}>No data available for {props.manager.entryId}.</div>;
-    }
-
     return <div className='pdbemolstar-state-gallery-controls' onKeyDown={handleKeyDown} tabIndex={-1} ref={keyDownTargetRef} >
         <ExpandGroup header='States' initiallyExpanded={true} key='states'>
             {categories.groups.map(cat =>
                 <ExpandGroup header={cat} key={cat} initiallyExpanded={true} >
                     {categories.members.get(cat)?.map(img =>
-                        <Button key={img.filename} className='msp-action-menu-button' onClick={() => setSelected(img)} title={img.simple_title ?? img.filename}
-                            icon={img === selected ? selectedStateIcon : EmptyIconSvg}
-                            style={{ height: 24, lineHeight: '24px', textAlign: 'left', overflow: 'hidden', textOverflow: 'ellipsis', fontWeight: img === selected ? 'bold' : undefined }}>
-                            {img.category ?? 'Miscellaneous'}: {img.simple_title ?? img.filename}
-                        </Button>
+                        <StateButton key={img.filename} img={img} isSelected={img === selected} status={status} onClick={() => setSelected(img)} />
                     )}
                 </ExpandGroup>
             )}
@@ -165,3 +161,17 @@ function ManagerControls(props: { manager: StateGalleryManager }) {
         </div >
     </div>;
 }
+
+function StateButton(props: { img: Image, isSelected: boolean, status: 'ready' | 'loading' | 'error', onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void }) {
+    const { img, isSelected, status, onClick } = props;
+    const icon = !isSelected ? EmptyIconSvg : (status === 'loading') ? HourglassBottomSvg : (status === 'error') ? ErrorSvg : CheckSvg;
+    const title = img.simple_title ?? img.filename;
+    const errorMsg = (isSelected && status === 'error') ? '[Failed to load] ' : '';
+    return <Button className='msp-action-menu-button'
+        icon={icon}
+        onClick={onClick}
+        title={`${errorMsg}${title}`}
+        style={{ height: 24, lineHeight: '24px', textAlign: 'left', overflow: 'hidden', textOverflow: 'ellipsis', fontWeight: isSelected ? 'bold' : undefined }}>
+        {title}
+    </Button>;
+}
diff --git a/src/app/helpers.ts b/src/app/helpers.ts
@@ -7,6 +7,7 @@ import { StructureRef } from 'molstar/lib/mol-plugin-state/manager/structure/hie
 import { StateTransforms } from 'molstar/lib/mol-plugin-state/transforms';
 import { CreateVolumeStreamingInfo } from 'molstar/lib/mol-plugin/behavior/dynamic/volume-streaming/transformers';
 import { PluginCommands } from 'molstar/lib/mol-plugin/commands';
+import { PluginConfigItem } from 'molstar/lib/mol-plugin/config';
 import { PluginContext } from 'molstar/lib/mol-plugin/context';
 import { MolScriptBuilder as MS } from 'molstar/lib/mol-script/language/builder';
 import { Expression } from 'molstar/lib/mol-script/language/expression';
@@ -606,3 +607,16 @@ export class PreemptiveQueue<X, Y> {
         }
     }
 }
+
+
+export namespace PluginConfigUtils {
+    export type ConfigFor<T> = { [key in keyof T]: PluginConfigItem<T[key]> }
+
+    export function getConfigValues<T>(plugin: PluginContext | undefined, configItems: { [name in keyof T]: PluginConfigItem<T[name]> }, defaults: T): T {
+        const values = {} as T;
+        for (const name in configItems) {
+            values[name] = plugin?.config.get(configItems[name]) ?? defaults[name];
+        }
+        return values;
+    }
+}
