brainsmatics 1.2.6 → 1.2.7

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 CHANGED
@@ -54,7 +54,8 @@ export default function App() {
54
54
 
55
55
  - 展示 3D 标准脑图谱。
56
56
  - 在同一个 Three.js 场景中展示脑区、核团、血管、神经元等对象。
57
- - 加载并展示 SWC 神经元形态数据。
57
+ - 各场景共用的模型右键菜单仅在右击时打开,并保留当次模型的操作目标;从模型移入菜单后可正常选择,移出菜单卡片、选择菜单项或点击外部后关闭,重新悬停模型不会自动打开。
58
+ - 加载并展示 SWC 神经元形态数据;悬停时红色高亮,移至空白、其他神经元或画布外后恢复原色,快速移开同样生效。
58
59
  - 将用户上传的数据插入 3D 场景并进行平移、旋转、缩放、调色和透明度调整。
59
60
  - 加载 `.tif`、`.tiff` 图像栈,并以体数据方式渲染。
60
61
  - 加载 `.nii.gz` 压缩 NIfTI 体数据。
@@ -0,0 +1,10 @@
1
+ import * as THREE from "three";
2
+ /** The same model-space -> Viewer transform used by the existing FBX scene. */
3
+ export declare function applyBrainOutlineTransform(object: THREE.Object3D, options?: {
4
+ scale?: number;
5
+ offsetScale?: number;
6
+ translateX?: number;
7
+ translateY?: number;
8
+ translateZ?: number;
9
+ offsetZ?: number;
10
+ }): THREE.Object3D<THREE.Object3DEventMap>;
@@ -1,12 +1,21 @@
1
1
  import React from "react";
2
+ import type { SequenceLivePose, SequenceVolumeGeometry } from "./stamPlane";
2
3
  import type { SequenceDisplayMode, SequenceSlice, SequenceTransform, SequenceTransformMode } from "./types";
3
4
  import "./index.css";
4
5
  interface Props {
5
- onShowSlice?: (slice: SequenceSlice, mode: SequenceDisplayMode) => void;
6
+ onShowSlice?: (slice: SequenceSlice, mode: SequenceDisplayMode) => void | Promise<void>;
6
7
  onHideSlice?: (sliceId: string) => void;
8
+ onSectionChange?: (slice: SequenceSlice, section: 0 | 1 | 2) => Promise<void>;
7
9
  onTransformModeChange?: (mode: SequenceTransformMode) => void;
8
10
  onSaveTransform?: (slice: SequenceSlice, transform: SequenceTransform) => Promise<number>;
9
- onRegisterTransformSaver?: (saver: (sliceId: string, transform: SequenceTransform) => Promise<void>) => void;
11
+ onRegisterTransformSaver?: (saver: (sliceId: string, transform: SequenceTransform) => Promise<number>) => void;
12
+ onRegisterLivePoseListener?: (listener: ((sliceId: string, pose: SequenceLivePose, committed: boolean) => void) | null) => void;
13
+ onSequenceVolumeGeometry?: (geometry: SequenceVolumeGeometry | null) => void;
14
+ onGetExportPose?: (slice: SequenceSlice, size: {
15
+ width: number;
16
+ height: number;
17
+ }) => SequenceLivePose | null;
18
+ onGetLivePose?: (sliceId: string) => SequenceLivePose | null;
10
19
  }
11
20
  declare const SequenceRegistrationPanel: React.FC<Props>;
12
21
  export default SequenceRegistrationPanel;
@@ -1,4 +1,6 @@
1
- import type { SequenceJob, SequenceSession, SequenceSlice, SequenceTransform } from "./types";
1
+ import type { SequenceSession, SequenceSlice, SequenceTransform } from "./types";
2
+ export declare function configureSequenceConnection(token: unknown, loginId: unknown): boolean;
3
+ export declare function clearSequenceConnection(): void;
2
4
  export declare function sequenceAuthToken(): string;
3
5
  export declare function sequenceRequest<T>(path: string, init?: RequestInit): Promise<T>;
4
6
  export declare function sequenceImageBlob(url: string): Promise<Blob>;
@@ -14,10 +16,8 @@ export declare function updateSequenceSlice(sessionId: string, slice: SequenceSl
14
16
  export declare function reorderSequenceSlices(sessionId: string, sliceIds: string[]): Promise<{
15
17
  ok: boolean;
16
18
  }>;
17
- export declare function submitSequenceRegistration(sessionId: string, slice: SequenceSlice, typeName: string): Promise<SequenceJob>;
18
- export declare const getSequenceJob: (jobId: string) => Promise<SequenceJob>;
19
- export declare const retrySequenceJob: (jobId: string) => Promise<SequenceJob>;
20
19
  export declare function saveSequenceTransform(sessionId: string, sliceId: string, revision: number, transform: SequenceTransform): Promise<{
21
20
  revision: number;
22
21
  transform: SequenceTransform;
23
22
  }>;
23
+ export declare function deleteSequenceSlice(sessionId: string, sliceId: string): Promise<void>;
@@ -0,0 +1,64 @@
1
+ /** Coordinate conversions shared with the existing Atlas Reslicing routes. */
2
+ export type AtlasReferencePositionMm = readonly [x: number, y: number, z: number];
3
+ export type AtlasReferenceVoxelXYZ = [x: number, y: number, z: number];
4
+ export interface TargetTifGeometry {
5
+ available: boolean;
6
+ reason?: string;
7
+ atlas_id?: string;
8
+ geometry_revision?: string;
9
+ shape_zyx?: [number, number, number];
10
+ target_volume?: {
11
+ dataset_id?: string;
12
+ dataset_version?: string;
13
+ shape_zyx?: [number, number, number];
14
+ pixel_size_x_um?: number | null;
15
+ pixel_size_y_um?: number | null;
16
+ pixel_size_z_um?: number | null;
17
+ };
18
+ axis_order?: "xyz";
19
+ frame_axis?: "cor";
20
+ coordinate_unit?: "um";
21
+ physical_to_voxel_um?: number[][];
22
+ }
23
+ export type TargetTifFrameMapping = {
24
+ available: false;
25
+ reason: string;
26
+ } | {
27
+ available: true;
28
+ datasetId: string;
29
+ datasetRevision: string;
30
+ mappingId: string;
31
+ frameAxis: "cor";
32
+ voxelXYZ: [number, number, number];
33
+ continuousFrameIndex: number;
34
+ frameIndex: number;
35
+ systemFrame: number;
36
+ frameCount: number;
37
+ mappingType?: "physical-affine" | "reference-resolution-scale";
38
+ referenceResolutionUm?: number;
39
+ targetResolutionUm?: number;
40
+ shapeZYX?: [number, number, number];
41
+ };
42
+ /** Existing standard coronal reference page number (`inp`, 1-based). */
43
+ export declare function coronalReferenceInput(positionZMm: number): number | null;
44
+ /**
45
+ * Position in the legacy higher-resolution reference image coordinate
46
+ * system. These values are voxel-like reference coordinates, not physical
47
+ * micrometers; they must never be fed directly into a physical affine.
48
+ */
49
+ export declare function atlasReferenceVoxelCoordinates(positionMm: AtlasReferencePositionMm): AtlasReferenceVoxelXYZ | null;
50
+ /** JavaScript parseInt(number.toString()) behavior used by the legacy URL. */
51
+ export declare function truncateAtlasReferencePosition(position: AtlasReferenceVoxelXYZ): AtlasReferenceVoxelXYZ;
52
+ /**
53
+ * Map the 1 µm Atlas Reslicing reference grid to the matching 10 µm
54
+ * annotation volume. This mapping is only valid for the full atlas volume
55
+ * dimensions; cropped or differently sampled TIFFs need a physical affine.
56
+ */
57
+ export declare function mapAtlasReferencePositionTo10umTif(referenceVoxelXYZ: readonly [number, number, number] | null | undefined, geometry: TargetTifGeometry | null | undefined, sourceAtlasId: string | null | undefined): TargetTifFrameMapping;
58
+ /**
59
+ * Map a canonical STAM physical center (µm) to a target TIFF only when both
60
+ * Atlas ID and geometry revision agree. Legacy reference-image coordinates
61
+ * are intentionally not accepted here because their physical calibration is
62
+ * not established by the old URL formula.
63
+ */
64
+ export declare function mapAtlasPhysicalPoseToTifFrame(physicalXYZUm: readonly [number, number, number] | null | undefined, geometry: TargetTifGeometry | null | undefined, sourceAtlasId: string | null | undefined, sourceGeometryRevision: string | null | undefined): TargetTifFrameMapping;
@@ -0,0 +1,6 @@
1
+ import * as THREE from "three";
2
+ export interface BrainShellClampResult {
3
+ point: THREE.Vector3;
4
+ constrained: boolean;
5
+ }
6
+ export declare const clampPointToBrainShell: (root: THREE.Object3D, candidate: THREE.Vector3, previousLegalPoint?: THREE.Vector3 | null) => BrainShellClampResult;
@@ -0,0 +1,8 @@
1
+ /** Storybook's manager owns the opener; its preview iframe uses a narrow bridge. */
2
+ export declare function sequenceLaunchParams(win?: Window): URLSearchParams;
3
+ export declare function sequenceConnection(win?: Window): {
4
+ handoffId: string;
5
+ returnOrigin: string;
6
+ peer: Window;
7
+ transportOrigin: string;
8
+ } | null;
@@ -0,0 +1,4 @@
1
+ import type { SequenceLivePose } from "./stamPlane";
2
+ import type { SequenceRegistrationExportV3, SequenceSlice } from "./types";
3
+ export declare function createSequenceExportResult(slice: SequenceSlice, pose: SequenceLivePose, exportId: string): SequenceRegistrationExportV3;
4
+ export declare function mapSequenceExports<T, R>(items: T[], operation: (item: T, index: number) => Promise<R>): Promise<R[]>;
@@ -0,0 +1,11 @@
1
+ export interface SequenceRegistrationAckExpectation {
2
+ exportId: string;
3
+ sliceId: string;
4
+ }
5
+ export declare function isMatchingSequenceRegistrationAck(data: unknown, expected: SequenceRegistrationAckExpectation, handoffId: string): data is {
6
+ type: "stam.sequence-registration.ack";
7
+ handoffId: string;
8
+ exportId: string;
9
+ sliceId: string;
10
+ accepted: boolean;
11
+ };
@@ -0,0 +1,26 @@
1
+ export { sequenceSectionFromAngles } from "./stamPlane";
2
+ import type { SequencePoseGeometry } from "./types";
3
+ type Options = {
4
+ geometry: SequencePoseGeometry;
5
+ shape: number[];
6
+ center: number[];
7
+ angles: number[];
8
+ imageUrl?: string;
9
+ outlineUrl?: string;
10
+ onOutlineStatus?: (status: string) => void;
11
+ onChange: (center: number[], angles: number[]) => void;
12
+ onCommit?: (center: number[], angles: number[]) => void;
13
+ };
14
+ /** Standalone build of the Viewer controls; no auth or annotation state. */
15
+ export declare function mountPoseEditor(host: HTMLElement, options: Options): {
16
+ setPose: (center: number[], angles: number[]) => void;
17
+ setSection: (section: 0 | 1 | 2) => void;
18
+ setSliceImage: (url?: string, definition?: {
19
+ centerVoxelXYZ: number[];
20
+ uExtentVoxelXYZ: number[];
21
+ vExtentVoxelXYZ: number[];
22
+ }) => void;
23
+ fit: () => void;
24
+ setMode: (mode: "translate" | "rotate") => void;
25
+ dispose: () => void;
26
+ };
@@ -0,0 +1,99 @@
1
+ import * as THREE from "three";
2
+ import type { SequenceSlice, StamPlane } from "./types";
3
+ import type { TargetTifFrameMapping, TargetTifGeometry } from "./atlasReslicingReference";
4
+ export interface SequenceSlicePose {
5
+ centerMm: [number, number, number];
6
+ orientation: THREE.Quaternion;
7
+ }
8
+ export declare function standardSequenceQuaternion(section: 0 | 1 | 2): THREE.Quaternion;
9
+ export declare function sequenceSectionFromAngles(angles?: number[]): -1 | 0 | 1 | 2;
10
+ export interface AtlasReslicingPose extends SequenceSlicePose {
11
+ angles: [number, number, number];
12
+ }
13
+ export interface SequencePhysicalPose {
14
+ centerUm: [number, number, number];
15
+ uAxis: [number, number, number];
16
+ vAxis: [number, number, number];
17
+ normal: [number, number, number];
18
+ }
19
+ export interface SequenceVolumeGeometry extends TargetTifGeometry {
20
+ }
21
+ type DefaultSequencePlacement = Pick<SequenceSlice, "targetFrame" | "sequenceOrder" | "positionOffsetUm">;
22
+ export interface SequenceLivePose {
23
+ annotationTarget?: {
24
+ datasetId: string;
25
+ datasetVersion: string;
26
+ };
27
+ poseGeometry?: import("./types").SequencePoseGeometry;
28
+ centerMm: [number, number, number];
29
+ /** Scene-local XYZ Euler degrees used by the original high-resolution jump. */
30
+ angles: [number, number, number];
31
+ referenceVoxelXYZ?: [number, number, number];
32
+ referenceVoxelXYZRaw?: [number, number, number];
33
+ referenceInp?: number;
34
+ targetTif?: Extract<TargetTifFrameMapping, {
35
+ available: true;
36
+ }>;
37
+ physicalXYZUm?: [number, number, number];
38
+ uAxis?: [number, number, number];
39
+ vAxis?: [number, number, number];
40
+ normal?: [number, number, number];
41
+ voxelXYZ?: [number, number, number];
42
+ frameAxis?: "cor";
43
+ systemFrame?: number;
44
+ frameIndex?: number;
45
+ tifFrameCount?: number;
46
+ frameCalculationReason?: string;
47
+ atlasId?: string;
48
+ atlasGeometryRevision?: string;
49
+ poseRevision?: string;
50
+ poseSaved?: boolean;
51
+ obliquePlane?: {
52
+ schemaVersion: 1;
53
+ coordinateSpace: "target-tif-voxel-xyz";
54
+ datasetId: string;
55
+ datasetRevision: string;
56
+ mappingId: string;
57
+ centerVoxelXYZ: [number, number, number];
58
+ uExtentVoxelXYZ: [number, number, number];
59
+ vExtentVoxelXYZ: [number, number, number];
60
+ widthPx: number;
61
+ heightPx: number;
62
+ };
63
+ }
64
+ export interface StamGeometryMetadata {
65
+ atlasId: string;
66
+ atlasGeometryRevision: string;
67
+ sliceCoordinateToPhysicalUm: number[];
68
+ }
69
+ export declare function applyStamGeometryMetadata(brain: THREE.Object3D, value: unknown): boolean;
70
+ /**
71
+ * Derive the default coronal plane position from the sequence's one-based
72
+ * target frame and physical spacing. The known 10 µm reference mapping uses
73
+ * the same [-7, +7] mm Z range as Atlas Reslicing; other volumes use their
74
+ * declared physical affine and the Viewer-to-STAM geometry manifest.
75
+ */
76
+ export declare function getDefaultSequencePlaneCenter(placement: DefaultSequencePlacement, brain: THREE.Object3D, geometry: SequenceVolumeGeometry | null | undefined, fallbackCenter: THREE.Vector3): THREE.Vector3 | null;
77
+ export declare function getSequenceSlicePose(mesh: THREE.Mesh, brain: THREE.Object3D): SequenceSlicePose | null;
78
+ /**
79
+ * Convert a viewer plane to the pose convention used by the slicing API:
80
+ * center in the slicing coordinate frame and XYZ Euler angles after the same
81
+ * +90 degree X correction used by `/c-api/slicing`.
82
+ */
83
+ export declare function getAtlasReslicingPose(mesh: THREE.Mesh, brain: THREE.Object3D): AtlasReslicingPose | null;
84
+ export declare function getSequenceSlicePhysicalPose(mesh: THREE.Mesh, brain: THREE.Object3D): SequencePhysicalPose | null;
85
+ export declare function getSequenceLivePose(mesh: THREE.Mesh, brain: THREE.Object3D): SequenceLivePose | null;
86
+ /** Export the same geometry used above, rather than making the annotation UI
87
+ * guess the Atlas Euler baseline, scene scale or the TIFF's voxel spacing. */
88
+ export declare function getSequencePoseEditGeometry(mesh: THREE.Mesh, brain: THREE.Object3D, pose: SequenceLivePose): {
89
+ outlineModelMatrix: THREE.Matrix4Tuple;
90
+ schemaVersion: 1;
91
+ voxelFromAtlasLinear: number[][];
92
+ voxelFromViewerAffine: number[][];
93
+ planeAxes: [[number, number, number], [number, number, number]];
94
+ planeSize: [number, number];
95
+ } | undefined;
96
+ export declare function buildStamPlane(mesh: THREE.Mesh, brain: THREE.Object3D): StamPlane | null;
97
+ export declare function hasCurrentStamPlane(plane: StamPlane | undefined, brain: THREE.Object3D): boolean;
98
+ export declare function quaternionFromStamPlane(plane: StamPlane): THREE.Quaternion;
99
+ export {};
@@ -0,0 +1,4 @@
1
+ import * as THREE from "three";
2
+ import { TransformControls } from "three/examples/jsm/controls/TransformControls.js";
3
+ /** Shared by the full Viewer and the annotation pose dialog. */
4
+ export declare function createSequenceTransformControls(camera: THREE.Camera, element: HTMLElement, plane: THREE.Object3D, mode: "translate" | "rotate"): TransformControls;
@@ -3,6 +3,18 @@ export type SequenceJobStatus = "queued" | "processing" | "succeeded" | "failed"
3
3
  export type SequenceSliceStatus = "uploaded" | "queued" | "processing" | "registered" | "failed" | "stale";
4
4
  export type SequenceDisplayMode = "source" | "atlas";
5
5
  export type SequenceTransformMode = "translate" | "rotate";
6
+ export interface StamPlane {
7
+ schemaVersion: 1;
8
+ atlasId: string;
9
+ atlasGeometryRevision: string;
10
+ centerUm: [number, number, number];
11
+ uAxis: [number, number, number];
12
+ vAxis: [number, number, number];
13
+ normal: [number, number, number];
14
+ widthPx: number;
15
+ heightPx: number;
16
+ pixelSpacingUm: [number, number];
17
+ }
6
18
  export interface SequenceTransform {
7
19
  position: {
8
20
  x: number;
@@ -15,7 +27,108 @@ export interface SequenceTransform {
15
27
  z: number;
16
28
  w: number;
17
29
  };
30
+ plane?: StamPlane;
31
+ }
32
+ export interface SequenceRegistrationExportV2 {
33
+ schemaVersion: 2;
34
+ sessionId: string;
35
+ sliceId: string;
36
+ filename: string;
37
+ sequenceOrder: number;
38
+ systemFrame: number;
39
+ frameIndex: number;
40
+ tifFrameCount: number;
41
+ frameSource: "atlas-geometry";
42
+ frameVoxelAxis: "Z";
43
+ frameVoxelCoordinate: number;
44
+ frameAxis: "cor";
45
+ angles: [number, number, number];
46
+ angleUnit: "degree";
47
+ angleSource: "atlas-reslicing";
48
+ angleConvention: "atlas-reslicing-xyz";
49
+ physicalCoordinateUnit: "um";
50
+ voxelCoordinateUnit: "voxel";
51
+ centerCoordinateUnit: "mm";
52
+ physicalXYZUm?: [number, number, number];
53
+ voxelXYZ?: [number, number, number];
54
+ centerMm: [number, number, number];
55
+ uAxis?: [number, number, number];
56
+ vAxis?: [number, number, number];
57
+ normal?: [number, number, number];
58
+ atlasId?: string;
59
+ atlasGeometryRevision?: string;
60
+ exportedAt: string;
61
+ }
62
+ export interface SequenceRegistrationExportV3 {
63
+ schemaVersion: 3;
64
+ exportId: string;
65
+ sessionId: string;
66
+ sliceId: string;
67
+ filename: string;
68
+ sequenceOrder: number;
69
+ exportedAt: string;
70
+ /** Snapshot id; `poseSaved` says whether this exact snapshot reached the server. */
71
+ poseRevision: string;
72
+ poseSaved: boolean;
73
+ annotationTarget?: {
74
+ datasetId: string;
75
+ datasetVersion: string;
76
+ };
77
+ /** Mappings sampled from the original Atlas Reslicing geometry, for annotation-side editing. */
78
+ poseGeometry?: SequencePoseGeometry;
79
+ atlasReference: {
80
+ section: "arbitrary";
81
+ referenceInp?: number;
82
+ centerMm: [number, number, number];
83
+ /** Coordinates produced by the existing higher-resolution URL formula. */
84
+ referenceVoxelXYZ?: [number, number, number];
85
+ /** Untruncated 1 µm reference coordinates used for resolution conversion. */
86
+ referenceVoxelXYZRaw?: [number, number, number];
87
+ angles: [number, number, number];
88
+ angleUnit: "degree";
89
+ angleSource: "atlas-reslicing";
90
+ angleConvention: "atlas-reslicing-xyz";
91
+ };
92
+ /** A display-only plane in the target annotation TIFF's XYZ voxel space. */
93
+ obliquePlane?: {
94
+ schemaVersion: 1;
95
+ coordinateSpace: "target-tif-voxel-xyz";
96
+ datasetId: string;
97
+ datasetRevision: string;
98
+ mappingId: string;
99
+ centerVoxelXYZ: [number, number, number];
100
+ /** Full-width and full-height plane vectors, in target TIFF voxels. */
101
+ uExtentVoxelXYZ: [number, number, number];
102
+ vExtentVoxelXYZ: [number, number, number];
103
+ widthPx: number;
104
+ heightPx: number;
105
+ };
106
+ /** Missing means the pose cannot be associated with this TIFF's geometry. */
107
+ targetTif?: {
108
+ datasetId: string;
109
+ datasetRevision: string;
110
+ mappingId: string;
111
+ frameAxis: "cor";
112
+ frameIndex: number;
113
+ systemFrame: number;
114
+ frameCount: number;
115
+ continuousFrameIndex: number;
116
+ voxelXYZ: [number, number, number];
117
+ mappingType?: "physical-affine" | "reference-resolution-scale";
118
+ referenceResolutionUm?: number;
119
+ targetResolutionUm?: number;
120
+ shapeZYX?: [number, number, number];
121
+ };
122
+ }
123
+ export interface SequencePoseGeometry {
124
+ outlineModelMatrix?: number[];
125
+ schemaVersion: 1;
126
+ voxelFromAtlasLinear: number[][];
127
+ voxelFromViewerAffine: number[][];
128
+ planeSize: [number, number];
129
+ planeAxes?: [[number, number, number], [number, number, number]];
18
130
  }
131
+ export type SequenceRegistrationExport = SequenceRegistrationExportV2 | SequenceRegistrationExportV3;
19
132
  export interface SequenceRegistration {
20
133
  url?: string;
21
134
  angles?: number[];
@@ -1 +1 @@
1
- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./index-rnHO1IdP.js"),t=require("./basedecoder-CsHP9rmG.js");class d extends t.BaseDecoder{decodeBlock(e){return r.inflate_1(new Uint8Array(e)).buffer}}exports.default=d;
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./index-Bf0sP4HG.js"),t=require("./basedecoder-CsHP9rmG.js");class d extends t.BaseDecoder{decodeBlock(e){return r.inflate_1(new Uint8Array(e)).buffer}}exports.default=d;
@@ -1,4 +1,4 @@
1
- import { i as r } from "./index-D_EhKvAR.mjs";
1
+ import { i as r } from "./index-BDTXoGmb.mjs";
2
2
  import { B as a } from "./basedecoder-PoXbLGBV.mjs";
3
3
  class s extends a {
4
4
  decodeBlock(e) {