molstar
Version:
A comprehensive macromolecular library.
198 lines (197 loc) • 9.74 kB
JavaScript
;
/**
* Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
*
* @author Adam Midlik <midlik@gmail.com>
* @author David Sehnal <david.sehnal@gmail.com>
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.MVSXFormatProvider = exports.MVSJFormatProvider = exports.LoadMvsData = exports.LoadMvsDataParams = exports.ParseMVSX = exports.ParseMVSJ = exports.Mvs = void 0;
exports.loadMVSX = loadMVSX;
exports.loadMVSData = loadMVSData;
const util_1 = require("../../../mol-data/util");
const string_like_1 = require("../../../mol-io/common/string-like");
const provider_1 = require("../../../mol-plugin-state/formats/provider");
const objects_1 = require("../../../mol-plugin-state/objects");
const data_1 = require("../../../mol-plugin-state/transforms/data");
const mol_state_1 = require("../../../mol-state");
const mol_task_1 = require("../../../mol-task");
const assets_1 = require("../../../mol-util/assets");
const param_definition_1 = require("../../../mol-util/param-definition");
const zip_1 = require("../../../mol-util/zip/zip");
const load_1 = require("../load");
const mvs_data_1 = require("../mvs-data");
const annotation_structure_component_1 = require("./annotation-structure-component");
/** Plugin state object storing `MVSData` */
class Mvs extends objects_1.PluginStateObject.Create({ name: 'MVS Data', typeClass: 'Data' }) {
}
exports.Mvs = Mvs;
/** Transformer for parsing data in MVSJ format */
exports.ParseMVSJ = (0, annotation_structure_component_1.MVSTransform)({
name: 'mvs-parse-mvsj',
display: { name: 'MolViewSpec from MVSJ', description: 'Create MolViewSpec view from MVSJ data' },
from: objects_1.PluginStateObject.Data.String,
to: Mvs,
})({
apply({ a }, plugin) {
const mvsData = mvs_data_1.MVSData.fromMVSJ(string_like_1.StringLike.toString(a.data));
const sourceUrl = tryGetDownloadUrl(a, plugin);
return new Mvs({ mvsData, sourceUrl });
},
});
/** Transformer for parsing data in MVSX format (= zipped MVSJ + referenced files like structures and annotations) */
exports.ParseMVSX = (0, annotation_structure_component_1.MVSTransform)({
name: 'mvs-parse-mvsx',
display: { name: 'MolViewSpec from MVSX', description: 'Create MolViewSpec view from MVSX data' },
from: objects_1.PluginStateObject.Data.Binary,
to: Mvs,
params: {
mainFilePath: param_definition_1.ParamDefinition.Text('index.mvsj'),
},
})({
apply({ a, params }, plugin) {
return mol_task_1.Task.create('Parse MVSX file', async (ctx) => {
const data = await loadMVSX(plugin, ctx, a.data, params.mainFilePath);
return new Mvs(data);
});
},
});
/** Params for the `LoadMvsData` action */
exports.LoadMvsDataParams = {
appendSnapshots: param_definition_1.ParamDefinition.Boolean(false, { description: 'If true, add snapshots from MVS into current snapshot list; if false, replace the snapshot list.' }),
keepCamera: param_definition_1.ParamDefinition.Boolean(false, { description: 'If true, any camera positioning from the MVS state will be ignored and the current camera position will be kept.' }),
applyExtensions: param_definition_1.ParamDefinition.Boolean(true, { description: 'If true, apply builtin MVS-loading extensions (not a part of standard MVS specification).' }),
};
/** State action which loads a MVS view into Mol* */
exports.LoadMvsData = mol_state_1.StateAction.build({
display: { name: 'Load MVS Data' },
from: Mvs,
params: exports.LoadMvsDataParams,
})(({ a, params }, plugin) => mol_task_1.Task.create('Load MVS Data', async () => {
const { mvsData, sourceUrl } = a.data;
await (0, load_1.loadMVS)(plugin, mvsData, { appendSnapshots: params.appendSnapshots, keepCamera: params.keepCamera, sourceUrl: sourceUrl, extensions: params.applyExtensions ? undefined : [] });
}));
/** Data format provider for MVSJ format.
* If Visuals:On, it will load the parsed MVS view;
* otherwise it will just create a plugin state object with parsed data. */
exports.MVSJFormatProvider = (0, provider_1.DataFormatProvider)({
label: 'MVSJ',
description: 'MVSJ',
category: 'Miscellaneous',
stringExtensions: ['mvsj'],
parse: async (plugin, data) => {
return plugin.state.data.build().to(data).apply(exports.ParseMVSJ).commit();
},
visuals: async (plugin, data) => {
const ref = mol_state_1.StateObjectRef.resolveRef(data);
const params = param_definition_1.ParamDefinition.getDefaultValues(exports.LoadMvsDataParams);
return await plugin.state.data.applyAction(exports.LoadMvsData, params, ref).run();
},
});
/** Data format provider for MVSX format.
* If Visuals:On, it will load the parsed MVS view;
* otherwise it will just create a plugin state object with parsed data. */
exports.MVSXFormatProvider = (0, provider_1.DataFormatProvider)({
label: 'MVSX',
description: 'MVSX',
category: 'Miscellaneous',
binaryExtensions: ['mvsx'],
parse: async (plugin, data) => {
return plugin.state.data.build().to(data).apply(exports.ParseMVSX).commit();
},
visuals: exports.MVSJFormatProvider.visuals,
});
/** Parse binary data `data` as MVSX archive,
* add all contained files to `plugin`'s asset manager,
* and parse the main file in the archive as MVSJ.
* Return parsed MVS data and `sourceUrl` for resolution of relative URIs. */
async function loadMVSX(plugin, runtimeCtx, data, mainFilePath = 'index.mvsj') {
// Ensure at most one generation of MVSX file assets exists in the asset manager.
// Hopefully, this is a reasonable compromise to ensure MVSX files work in multi-snapshot
// states.
clearMVSXFileAssets(plugin);
const archiveId = `ni,fnv1a;${(0, util_1.hashFnv32a)(data)}`;
let files;
try {
files = await (0, zip_1.unzip)(runtimeCtx, data);
}
catch (err) {
plugin.log.error('Invalid MVSX file');
throw err;
}
for (const path in files) {
const url = arcpUri(archiveId, path);
// Need to use static assets so they persist accross snapsho
ensureUrlAsset(plugin.managers.asset, url, files[path], { isFile: true });
}
const mainFile = files[mainFilePath];
if (!mainFile)
throw new Error(`File ${mainFilePath} not found in the MVSX archive`);
const mvsData = mvs_data_1.MVSData.fromMVSJ(decodeUtf8(mainFile));
const sourceUrl = arcpUri(archiveId, mainFilePath);
return { mvsData, sourceUrl };
}
async function loadMVSData(plugin, data, format, options) {
if (typeof data === 'string' && data.startsWith('base64')) {
data = Uint8Array.from(atob(data.substring(7)), c => c.charCodeAt(0)); // Decode base64 string to Uint8Array
}
if (format === 'mvsj') {
if (data.BYTES_PER_ELEMENT && data.buffer) {
data = new TextDecoder().decode(data); // Decode Uint8Array to string using UTF8
}
let mvsData;
if (typeof data === 'string') {
mvsData = mvs_data_1.MVSData.fromMVSJ(data);
}
else {
mvsData = data;
}
await (0, load_1.loadMVS)(plugin, mvsData, { sanityChecks: true, sourceUrl: undefined, ...options });
}
else if (format === 'mvsx') {
if (typeof data === 'string') {
throw new Error("loadMvsData: if `format` is 'mvsx', then `data` must be a Uint8Array or a base64-encoded string prefixed with 'base64,'.");
}
await plugin.runTask(mol_task_1.Task.create('Load MVSX file', async (ctx) => {
const parsed = await loadMVSX(plugin, ctx, data);
await (0, load_1.loadMVS)(plugin, parsed.mvsData, { sanityChecks: true, ...options, sourceUrl: parsed.sourceUrl });
}));
}
else {
throw new Error(`Unknown MolViewSpec format: ${format}`);
}
}
function clearMVSXFileAssets(plugin) {
plugin.managers.asset.clearTag('mvsx-file');
}
/** If the PluginStateObject `pso` comes from a Download transform, try to get its `url` parameter. */
function tryGetDownloadUrl(pso, plugin) {
var _a;
const theCell = plugin.state.data.selectQ(q => q.ofTransformer(data_1.Download)).find(cell => cell.obj === pso);
const urlParam = (_a = theCell === null || theCell === void 0 ? void 0 : theCell.transform.params) === null || _a === void 0 ? void 0 : _a.url;
return urlParam ? assets_1.Asset.getUrl(urlParam) : undefined;
}
/** Return a URI referencing a file within an archive, using ARCP scheme (https://arxiv.org/pdf/1809.06935.pdf).
* `archiveId` corresponds to the `authority` part of URI (e.g. 'uuid,EYVwjDiZhM20PWbF1OWWvQ' or 'ni,fnv1a;938511930')
* `path` corresponds to the path to a file within the archive */
function arcpUri(archiveId, path) {
return new URL(path, `arcp://${archiveId}/`).href;
}
/** Add a URL asset to asset manager.
* Skip if an asset with the same URL already exists. */
function ensureUrlAsset(manager, url, data, options) {
var _a;
const asset = assets_1.Asset.getUrlAsset(manager, url);
if (!manager.has(asset)) {
const filename = (_a = url.split('/').pop()) !== null && _a !== void 0 ? _a : 'file';
// We need to mark files as static resources to prevent deleting them
// when changing state snapshots.
manager.set(asset, new File([data], filename), (options === null || options === void 0 ? void 0 : options.isFile) ? { isStatic: true, tag: 'mvsx-file' } : undefined);
}
}
/** Decode bytes to text using UTF-8 encoding */
function decodeUtf8(bytes) {
_decoder !== null && _decoder !== void 0 ? _decoder : (_decoder = new TextDecoder());
return _decoder.decode(bytes);
}
let _decoder;