@gcszhn/mol4agent-core 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,191 @@
1
+ import { StructureElement } from 'molstar/lib/mol-model/structure.js';
2
+ import { COLOR_THEMES, REPRESENTATION_TYPES, } from "./protocol.js";
3
+ import { formatColor, parseColor } from "./color.js";
4
+ import { selectionKey, selectorExpression } from "./select.js";
5
+ /**
6
+ * How many fresh all-atom components this viewer has created.
7
+ *
8
+ * A new key per global non-preset style keeps stacking (`replace: false`)
9
+ * additive instead of updating a previous component in place.
10
+ */
11
+ let globalComponentSeq = 0;
12
+ /** True when the style uses Mol*'s polymer-and-ligand preset. */
13
+ export function usesPolymerAndLigandPreset(style) {
14
+ return style.type === undefined || style.type === 'cartoon';
15
+ }
16
+ /**
17
+ * Apply one `represent` command.
18
+ *
19
+ * `replace: true` (the default) clears the structure components first, whether
20
+ * or not `target` is present; `target` then narrows only the new
21
+ * representation's coverage. `replace: false` keeps every existing
22
+ * representation and adds the new one. Returns the same structured result as
23
+ * every other command.
24
+ */
25
+ export async function applyRepresentation(plugin, command, scopedStructures) {
26
+ const style = command.style;
27
+ if (style.type !== undefined && !REPRESENTATION_TYPES.includes(style.type)) {
28
+ return invalid(command.op, `unknown representation "${style.type}"; supported: ${REPRESENTATION_TYPES.join(', ')}`);
29
+ }
30
+ if (style.color !== undefined && !COLOR_THEMES.includes(style.color)) {
31
+ return invalid(command.op, `unknown colour theme "${style.color}"; supported: ${COLOR_THEMES.join(', ')}`);
32
+ }
33
+ // Normalize once, before touching the scene: a bad color must fail the
34
+ // command instead of reaching Mol* and painting the structure black.
35
+ let resolvedColor;
36
+ if (style.colorParams?.value !== undefined) {
37
+ try {
38
+ resolvedColor = parseColor(style.colorParams.value);
39
+ }
40
+ catch (error) {
41
+ return invalid(command.op, error instanceof Error ? error.message : String(error));
42
+ }
43
+ }
44
+ const colorParams = resolvedColor === undefined ? undefined : { value: resolvedColor };
45
+ const colorSuffix = resolvedColor === undefined ? '' : ` ${formatColor(resolvedColor)}`;
46
+ const structures = scopedStructures ?? plugin.managers.structure.hierarchy.current.structures;
47
+ if (structures.length === 0) {
48
+ return { ok: false, op: command.op, code: 'NO_STRUCTURE', message: 'no structure is loaded' };
49
+ }
50
+ const replace = command.replace !== false;
51
+ if (command.target !== undefined) {
52
+ const expression = selectorExpression(command.target);
53
+ // Do not clear the scene for a selection that matches nothing: the command
54
+ // would fail after destroying the previous view. `nullIfEmpty` makes the
55
+ // component builder skip an empty selection, so this mirrors its check.
56
+ if (replace && !matchesAnyStructure(structures, expression)) {
57
+ return representFailed(command.op, command.target);
58
+ }
59
+ if (replace && !await clearRepresentations(plugin, structures)) {
60
+ return {
61
+ ok: false,
62
+ op: command.op,
63
+ code: 'REPRESENT_FAILED',
64
+ message: 'could not remove the current representations',
65
+ };
66
+ }
67
+ let targeted = 0;
68
+ for (const structure of structures) {
69
+ const component = await plugin.builders.structure.tryCreateComponentFromExpression(structure.cell, expression, selectionKey(command.target), { label: 'mol4agent selection' });
70
+ if (component === undefined)
71
+ continue;
72
+ // No tag: with `replace: false` every targeted style must add its own
73
+ // representation, so two styles of the same selection stack instead of
74
+ // updating one another. A `replace: true` command clears first, so it
75
+ // still leaves exactly one.
76
+ const rep = await plugin.builders.structure.representation.addRepresentation(component, {
77
+ type: (style.type ?? 'ball-and-stick'),
78
+ color: (style.color ?? 'uniform'),
79
+ ...(colorParams === undefined ? {} : { colorParams: colorParams }),
80
+ });
81
+ if (rep !== undefined)
82
+ targeted += 1;
83
+ }
84
+ if (targeted === 0)
85
+ return representFailed(command.op, command.target);
86
+ plugin.canvas3d?.requestDraw();
87
+ return {
88
+ ok: true,
89
+ op: command.op,
90
+ message: `applied ${style.type ?? 'ball-and-stick'} / ${style.color ?? 'uniform'}${colorSuffix} to ${command.target.kind}`,
91
+ };
92
+ }
93
+ if (replace && !await clearRepresentations(plugin, structures)) {
94
+ return {
95
+ ok: false,
96
+ op: command.op,
97
+ code: 'REPRESENT_FAILED',
98
+ message: 'could not remove the current representations',
99
+ };
100
+ }
101
+ // A single Cartoon representation hides HETATM ligands. Use Mol*'s
102
+ // polymer-and-ligand preset for the default cartoon style so ATP/HEM/etc.
103
+ // stay visible. A uniform colorParams is passed through the preset theme so
104
+ // "gray cartoon" still keeps the ligand representation.
105
+ let added = 0;
106
+ if (usesPolymerAndLigandPreset(style)) {
107
+ for (const structure of structures) {
108
+ await plugin.builders.structure.representation.applyPreset(structure.cell, 'polymer-and-ligand', {
109
+ theme: {
110
+ globalName: style.color ?? 'chain-id',
111
+ ...(colorParams === undefined ? {} : { globalColorParams: colorParams }),
112
+ },
113
+ });
114
+ added += 1;
115
+ }
116
+ }
117
+ else {
118
+ // Representations live under components. Build one fresh all-atom
119
+ // component per structure. With replace: false the previous components
120
+ // stay, so every new style needs its own key.
121
+ const all = selectorExpression({ kind: 'all' });
122
+ for (const structure of structures) {
123
+ const component = await plugin.builders.structure.tryCreateComponentFromExpression(structure.cell, all, `mol4agent-global-${globalComponentSeq += 1}`, { label: 'mol4agent global' });
124
+ if (component === undefined)
125
+ continue;
126
+ const rep = await plugin.builders.structure.representation.addRepresentation(component, {
127
+ type: (style.type ?? 'cartoon'),
128
+ color: (style.color ?? 'chain-id'),
129
+ ...(colorParams === undefined ? {} : { colorParams: colorParams }),
130
+ });
131
+ if (rep !== undefined)
132
+ added += 1;
133
+ }
134
+ }
135
+ if (added === 0) {
136
+ return {
137
+ ok: false,
138
+ op: command.op,
139
+ code: 'REPRESENT_FAILED',
140
+ message: `Mol* did not create a representation for ${style.type ?? 'cartoon'}`,
141
+ };
142
+ }
143
+ plugin.canvas3d?.requestDraw();
144
+ return {
145
+ ok: true,
146
+ op: command.op,
147
+ message: `applied ${style.type ?? 'cartoon'} / ${style.color ?? 'chain-id'}${colorSuffix}`,
148
+ };
149
+ }
150
+ /** Whether `expression` selects at least one atom in any loaded structure. */
151
+ function matchesAnyStructure(structures, expression) {
152
+ for (const structure of structures) {
153
+ const data = structure.cell.obj?.data;
154
+ if (data === undefined)
155
+ continue;
156
+ try {
157
+ if (!StructureElement.Loci.isEmpty(StructureElement.Loci.fromExpression(data, expression)))
158
+ return true;
159
+ }
160
+ catch {
161
+ // Treat an expression we cannot evaluate as no match: never clear the
162
+ // scene for a selection the component builder may then fail to create.
163
+ }
164
+ }
165
+ return false;
166
+ }
167
+ /** Remove every structure component, i.e. every agent or human representation. */
168
+ async function clearRepresentations(plugin, structures) {
169
+ const components = structures.flatMap(structure => [...structure.components]);
170
+ if (components.length === 0)
171
+ return true;
172
+ try {
173
+ await plugin.managers.structure.hierarchy.remove(components, true);
174
+ return true;
175
+ }
176
+ catch (reason) {
177
+ console.warn('[mol4agent] could not remove the current representations', reason);
178
+ return false;
179
+ }
180
+ }
181
+ function representFailed(op, target) {
182
+ return {
183
+ ok: false,
184
+ op,
185
+ code: 'REPRESENT_FAILED',
186
+ message: `Mol* did not create a representation for ${target.kind}`,
187
+ };
188
+ }
189
+ function invalid(op, message) {
190
+ return { ok: false, op, code: 'INVALID_COMMAND', message };
191
+ }
package/lib/select.d.ts CHANGED
@@ -17,3 +17,15 @@ export type CompiledSelector = {
17
17
  export declare function compileSelector(selector: StructureSelector): CompiledSelector;
18
18
  /** A schema-only selector, or undefined when the selector needs a full query. */
19
19
  export declare function selectorSchema(selector: StructureSelector): ElementSchema | undefined;
20
+ /** The Mol* expression equivalent of a selector, for direct Loci lookups. */
21
+ export declare function selectorExpression(selector: StructureSelector): Expression;
22
+ /**
23
+ * Stable component key for one selection.
24
+ *
25
+ * Repeated targeted styles of the same selection reuse one Mol* cell; each
26
+ * `replace: false` command adds its own representation there, so cartoon +
27
+ * stick + line overlays do not fragment into sibling components.
28
+ */
29
+ export declare function selectionKey(selector: StructureSelector): string;
30
+ /** Short human label for a selector, used in tool and inspection output. */
31
+ export declare function describeSelector(selector: StructureSelector): string;
package/lib/select.js CHANGED
@@ -1,5 +1,6 @@
1
1
  /** Selector compilation: protocol selectors to Mol* schemas/queries. @module @gcszhn/mol4agent-core/select */
2
- import { StructureSelectionQueries } from 'molstar/lib/mol-plugin-state/helpers/structure-selection-query';
2
+ import { StructureElement } from 'molstar/lib/mol-model/structure.js';
3
+ import { StructureSelectionQueries } from 'molstar/lib/mol-plugin-state/helpers/structure-selection-query.js';
3
4
  /**
4
5
  * Compile one agent selector.
5
6
  *
@@ -56,6 +57,45 @@ export function selectorSchema(selector) {
56
57
  const compiled = compileSelector(selector);
57
58
  return 'elements' in compiled ? compiled.elements : undefined;
58
59
  }
60
+ /** The Mol* expression equivalent of a selector, for direct Loci lookups. */
61
+ export function selectorExpression(selector) {
62
+ const compiled = compileSelector(selector);
63
+ return 'elements' in compiled
64
+ ? StructureElement.Schema.toExpression(compiled.elements)
65
+ : compiled.expression(undefined);
66
+ }
67
+ /**
68
+ * Stable component key for one selection.
69
+ *
70
+ * Repeated targeted styles of the same selection reuse one Mol* cell; each
71
+ * `replace: false` command adds its own representation there, so cartoon +
72
+ * stick + line overlays do not fragment into sibling components.
73
+ */
74
+ export function selectionKey(selector) {
75
+ let hash = 2166136261;
76
+ for (const char of JSON.stringify(selector)) {
77
+ hash ^= char.charCodeAt(0);
78
+ hash = Math.imul(hash, 16777619);
79
+ }
80
+ return `mol4agent-sel-${(hash >>> 0).toString(36)}`;
81
+ }
82
+ /** Short human label for a selector, used in tool and inspection output. */
83
+ export function describeSelector(selector) {
84
+ switch (selector.kind) {
85
+ case 'all': return 'whole structure';
86
+ case 'polymer': return 'polymer';
87
+ case 'protein': return 'protein';
88
+ case 'nucleic': return 'nucleic acid';
89
+ case 'ligand': return 'ligand';
90
+ case 'water': return 'water';
91
+ case 'ion': return 'ion';
92
+ case 'chain': return `chain ${selector.chain}`;
93
+ case 'residue': return `residue ${selector.chain ?? ''}${selector.index}`;
94
+ case 'residues': return `residues ${selector.chain ?? ''}${selector.start}-${selector.end}`;
95
+ case 'comp': return `comp ${selector.compId}`;
96
+ case 'schema': return 'custom schema';
97
+ }
98
+ }
59
99
  function query(selection) {
60
100
  return { expression: () => selection.expression };
61
101
  }
package/lib/viewer.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type CaptureOptions, type CommandResult, type MolCommand, type StructureData, type StructureSummary } from './protocol.ts';
1
+ import { type CaptureOptions, type CommandResult, type LoadedStructure, type InspectRequest, type InspectResult, type MolCommand, type StructureData, type StructureSummary, type TmScoreRequest, type TmScoreResult } from './protocol.ts';
2
2
  export interface MolViewerOptions {
3
3
  readonly container: HTMLElement;
4
4
  readonly theme?: 'light' | 'dark';
@@ -23,13 +23,50 @@ export interface ViewerDiagnostics {
23
23
  export interface MolViewer {
24
24
  /** Snapshot of layout and Mol* hierarchy counts, for diagnostics. */
25
25
  diagnostics(): ViewerDiagnostics;
26
- /** Replace the displayed structure with adapter-supplied bytes. */
26
+ /**
27
+ * Replace the displayed scene with adapter-supplied bytes.
28
+ *
29
+ * The previous structures, their components, and measurements are cleared.
30
+ * `options.id` sets the id of the new (primary) structure; it defaults to
31
+ * `structure`.
32
+ */
27
33
  load(data: StructureData, options?: {
28
34
  preset?: string;
35
+ id?: string;
29
36
  }): Promise<StructureSummary>;
37
+ /**
38
+ * Add another structure to the current scene without clearing existing ones.
39
+ *
40
+ * Returns the stable id and summary. `options.id` must be unique within the
41
+ * scene; a generated id (`structure-2`, `structure-3`, ...) is used when it
42
+ * is omitted.
43
+ */
44
+ addStructure(data: StructureData, options?: {
45
+ preset?: string;
46
+ id?: string;
47
+ }): Promise<LoadedStructure>;
48
+ /** Remove one structure (and its components) from the scene. */
49
+ removeStructure(id: string): Promise<void>;
50
+ /** Structures currently loaded in this scene, in load order. */
51
+ listStructures(): readonly LoadedStructure[];
30
52
  /** Current summary, when a structure is loaded. */
31
53
  summary(): StructureSummary | undefined;
32
- /** Execute one command against the loaded structure. */
54
+ /**
55
+ * Read the loaded structure and the way Mol* currently draws it.
56
+ *
57
+ * Read-only: unlike {@link MolViewer.execute} it changes nothing, and its
58
+ * answers include human-driven viewer state (clicked selection, panel
59
+ * styles) that never passed through the adapter's command log.
60
+ */
61
+ inspect(request?: InspectRequest): InspectResult;
62
+ /**
63
+ * Compute TM-align metrics for two selections without moving either one.
64
+ *
65
+ * Read-only, like {@link MolViewer.inspect}; RMSD is measured after optimal
66
+ * superposition of the aligned polymer-trace atoms, not in the current frame.
67
+ */
68
+ tmScore(request: TmScoreRequest): TmScoreResult;
69
+ /** Execute one command against the loaded structures. */
33
70
  execute(command: MolCommand): Promise<CommandResult>;
34
71
  /** Execute commands in order, returning per-command results. */
35
72
  apply(commands: readonly MolCommand[]): Promise<readonly CommandResult[]>;