@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.
- package/README.md +171 -16
- package/README_zh.md +155 -14
- package/lib/color.d.ts +8 -0
- package/lib/color.js +16 -0
- package/lib/index.d.ts +2 -1
- package/lib/index.js +2 -1
- package/lib/inspect-mol.d.ts +28 -0
- package/lib/inspect-mol.js +103 -0
- package/lib/inspect-plugin.d.ts +22 -0
- package/lib/inspect-plugin.js +339 -0
- package/lib/inspect.d.ts +88 -0
- package/lib/inspect.js +189 -0
- package/lib/protocol.d.ts +277 -15
- package/lib/protocol.js +32 -1
- package/lib/represent.d.ts +25 -0
- package/lib/represent.js +191 -0
- package/lib/select.d.ts +12 -0
- package/lib/select.js +41 -1
- package/lib/viewer.d.ts +40 -3
- package/lib/viewer.js +481 -173
- package/package.json +4 -2
package/lib/represent.js
ADDED
|
@@ -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 {
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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[]>;
|