@matteria-js/adapters

Integration helpers at app boundaries.

Current shipped scope:

• structureToAtomMeshData
• structureToUnitCellLineData
• structureToViewerData
• scalarGridToSliceImageData
• scalarGridToOrthogonalSlicesData
• scalarFieldToTransferablePayload
• vectorFieldToTransferablePayload
• scalarGridToIsosurfacePayload
• bandStructureToPlotData
• densityOfStatesToPlotData
• phononBandStructureToPlotData
• phononDensityOfStatesToPlotData
• directionalYoungModulusToPlotData
• phononModeToAnimationPayload
• calculationReportToDashboardPayload
• workflowPlanToDashboardPayload

The output is framework-neutral typed arrays: atom positions, fractional positions, atomic numbers, radii, colors, site indices, and unit-cell line segments.

Volumetric helpers accept generic scalar and vector grid shapes, so @matteria-js/volumetric grids can be passed across this boundary without making adapters depend on that package. Slice payloads expose raw values, normalized values, and grayscale RGBA bytes without using DOM ImageData. Orthogonal slice previews package x/y/z slices with one shared value range for dashboards. Transfer payloads expose compact Float32Array buffers, valueLayout: "x-fastest", units when provided, and a transferables list for worker handoff. Vector-field transfer payloads also expose componentLayout: "interleaved-xyz", component ranges, magnitude ranges, and explicit grid step vectors.

Isosurface payload helpers prepare scalar-grid values, explicit x-fastest layout metadata, optional binary masks, origin, step vectors, ranges, and transferables for downstream meshing code. They do not extract triangles or construct meshes.

Electronic, phonon, and mechanics helpers accept simple local interfaces and return plot-ready typed arrays, ranges, labels, units, and metadata. Directional Young's modulus helpers package sampled elastic directions and moduli from mechanics-like summaries without making adapters depend on @matteria-js/mechanics. Phonon mode helpers package positions, displacements, phases, amplitudes, and transferables for animation code. They do not draw axes, choose colors, allocate canvases, or import plotting libraries.

Calculation-report helpers accept project-report-like records and return compact JSON-friendly dashboard payloads with status, scalar values, source inventory counts, warnings, and trajectory metadata. Workflow-plan helpers accept metadata-only workflow-plan records and return generated-file, external-artifact, stage, program, warning, and note counts for dashboards. They do not create dashboard components or depend on @matteria-js/project or @matteria-js/workflows.

This package should not own rendering components, Three.js scenes, cameras, shaders, plot widgets, DOM objects, meshing algorithms, or application state management. Viewer code can use these buffers to build Three.js, WebGL, Canvas, SVG, or worker payloads.

Current Example

import {
  scalarGridToIsosurfacePayload,
  scalarGridToOrthogonalSlicesData,
  scalarGridToSliceImageData,
  structureToViewerData,
  vectorFieldToTransferablePayload,
} from "@matteria-js/adapters";

const data = structureToViewerData(structure);

console.log(data.atoms.positions); // Float32Array
console.log(data.unitCell.positions); // Float32Array

const slice = scalarGridToSliceImageData({
  dimensions: [64, 64, 64],
  values: chargeDensityValues,
});

const preview = scalarGridToOrthogonalSlicesData({
  dimensions: [64, 64, 64],
  values: chargeDensityValues,
  units: "e/Ang^3",
});

const iso = scalarGridToIsosurfacePayload({
  dimensions: [64, 64, 64],
  values: chargeDensityValues,
  mask: selectedRegionMask,
}, { isovalue: 0.03 });

console.log(slice.normalizedValues); // Float32Array
console.log(slice.rgba); // Uint8ClampedArray
console.log(preview.x.rgba); // Uint8ClampedArray
console.log(preview.valueRange);
console.log(iso.transferables);
console.log(iso.valueLayout); // "x-fastest"
console.log(iso.maskSelectedCount); // selected voxel count when a mask is supplied

const vectors = vectorFieldToTransferablePayload({
  dimensions: [64, 64, 64],
  data: vectorValues,
  axisVectors: gridAxisVectors,
  componentLayout: "interleaved-xyz",
});

console.log(vectors.vectors); // Float32Array, interleaved xyz
console.log(vectors.gridVectors); // Float32Array step vectors
console.log(vectors.magnitudeRange);

import {
  bandStructureToPlotData,
  densityOfStatesToPlotData,
  directionalYoungModulusToPlotData,
  phononBandStructureToPlotData,
  phononDensityOfStatesToPlotData,
} from "@matteria-js/adapters";

const bands = bandStructureToPlotData({
  energies: [[-1, -0.8, -0.4], [0.2, 0.5, 0.9]],
  distances: [0, 0.5, 1],
  labels: ["Gamma", null, "X"],
  fermiEnergy: 0,
});

const dos = densityOfStatesToPlotData({
  energies: [-1, 0, 1],
  densities: [0.2, 1.1, 0.4],
  fermiEnergy: 0,
});

console.log(bands.energies); // Float32Array
console.log(dos.series[0]?.densities); // Float32Array

const phononBands = phononBandStructureToPlotData({
  frequencies: [[0, 1.2, 2.4], [0.2, 1.4, 2.8]],
  distances: [0, 0.5, 1],
  labels: ["Gamma", null, "X"],
  frequencyUnit: "THz",
});

const phononDos = phononDensityOfStatesToPlotData({
  frequencies: [0, 1, 2, 3],
  densities: [0, 2, 2, 0],
  frequencyUnit: "THz",
});

const elasticDirections = directionalYoungModulusToPlotData({
  unit: "GPa",
  samples: [
    { label: "[100]", direction: [1, 0, 0], youngModulus: 200 },
    { label: "[111]", direction: [1, 1, 1], youngModulus: 150 },
  ],
});

console.log(phononBands.frequencies); // Float32Array
console.log(phononDos.series[0]?.densities); // Float32Array
console.log(elasticDirections.directions); // Float32Array, normalized xyz triplets
console.log(elasticDirections.youngModuli); // Float32Array

import { phononModeToAnimationPayload } from "@matteria-js/adapters";

const mode = phononModeToAnimationPayload({
  positions: [0, 0, 0, 1, 0, 0],
  displacements: [0.02, 0, 0, -0.02, 0, 0],
  frequency: 5.2,
  frequencyUnit: "THz",
});

console.log(mode.displacements); // Float32Array
console.log(mode.transferables);

import {
  calculationReportToDashboardPayload,
  workflowPlanToDashboardPayload,
} from "@matteria-js/adapters";

const dashboard = calculationReportToDashboardPayload(calculationReport);
const workflowDashboard = workflowPlanToDashboardPayload(workflowPlan);

console.log(dashboard.status);
console.log(dashboard.scalarValues);
console.log(dashboard.sourceSummary.categories);
console.log(workflowDashboard.externalProgramNames);
console.log(workflowDashboard.expectedOutputArtifacts);

Planned Next Slice

Next adapter work should tighten these payload contracts against real viewer imports and parsed electronic, phonon, project, and volumetric files. Payloads should describe data only. They should not construct plots, textures, meshes, materials, render loops, dashboards, or framework components.