Support unwrapping complex phase values

packages/app/src/vis-packs/core/complex/MappedComplexLineVis.tsx

@@ -69,26 +69,34 @@ function MappedComplexLineVis(props: Props) {
     interpolation,
   } = config;
 
-  const { phaseArrays, amplitudeArrays } = usePhaseAmplitudeArrays([
-    value,
-    ...auxValues,
-  ]);
+  const { phaseArrays, unwrappedPhaseArrays, amplitudeArrays } =
+    usePhaseAmplitudeArrays([value, ...auxValues]);
   const numAxisArrays = useToNumArrays(axisValues);
 
   const mappingArgs = useSlicedDimsAndMapping(dims, dimMapping);
   const mappedPhaseArrays = useMappedArrays(phaseArrays, ...mappingArgs);
+  const mappedUnwrappedPhaseArrays = useMappedArrays(
+    unwrappedPhaseArrays,
+    ...mappingArgs,
+  );
   const mappedAmplitudeArrays = useMappedArrays(
     amplitudeArrays,
     ...mappingArgs,
   );
 
   const phaseDomains = useDomains(mappedPhaseArrays, yScaleType);
+  const unwrappedPhaseDomains = useDomains(
+    mappedUnwrappedPhaseArrays,
+    yScaleType,
+  );
   const amplitudeDomains = useDomains(mappedAmplitudeArrays, yScaleType);
 
   const [pickedArrays, pickedDomains] =
-    complexVisType === ComplexVisType.Phase
-      ? [mappedPhaseArrays, phaseDomains]
-      : [mappedAmplitudeArrays, amplitudeDomains];
+    complexVisType === ComplexVisType.Amplitude
+      ? [mappedAmplitudeArrays, amplitudeDomains]
+      : complexVisType === ComplexVisType.Phase
+        ? [mappedPhaseArrays, phaseDomains]
+        : [mappedUnwrappedPhaseArrays, unwrappedPhaseDomains];
 
   const [dataArray, ...auxArrays] = pickedArrays;
   const [dataDomain, ...auxDomains] = pickedDomains;

packages/app/src/vis-packs/core/complex/hooks.ts

@@ -1,36 +1,6 @@
 import { createMemo } from '@h5web/shared/createMemo';
-import { isComplexArray } from '@h5web/shared/guards';
-import {
-  type ArrayValue,
-  type ComplexType,
-  type NumericLikeType,
-} from '@h5web/shared/hdf5-models';
-import { type NumArray } from '@h5web/shared/vis-models';
 
-import { toNumArray } from '../utils';
-import { getPhaseAmplitude } from './utils';
+import { getPhaseAmplitude, getPhaseAmplitudeArrays } from './utils';
 
 export const usePhaseAmplitude = createMemo(getPhaseAmplitude);
-
-export function usePhaseAmplitudeArrays(
-  values: ArrayValue<NumericLikeType | ComplexType>[],
-): { phaseArrays: NumArray[]; amplitudeArrays: NumArray[] } {
-  const phaseArrays: NumArray[] = [];
-  const amplitudeArrays: NumArray[] = [];
-
-  values.forEach((arr) => {
-    if (isComplexArray(arr)) {
-      const { phase, amplitude } = getPhaseAmplitude(arr);
-      phaseArrays.push(phase);
-      amplitudeArrays.push(amplitude);
-      return;
-    }
-
-    // Consider real numbers as complex numbers with no imaginary parts
-    const numArray = toNumArray(arr);
-    phaseArrays.push(numArray.map(() => 0));
-    amplitudeArrays.push(numArray.map((v) => Math.abs(v)));
-  });
-
-  return { phaseArrays, amplitudeArrays };
-}
+export const usePhaseAmplitudeArrays = createMemo(getPhaseAmplitudeArrays);

packages/app/src/vis-packs/core/complex/utils.ts

@@ -1,11 +1,22 @@
-import { type H5WebComplex } from '@h5web/shared/hdf5-models';
-import { ComplexVisType } from '@h5web/shared/vis-models';
+import { isComplexArray } from '@h5web/shared/guards';
+import {
+  type ArrayValue,
+  type ComplexType,
+  type H5WebComplex,
+  type NumericLikeType,
+} from '@h5web/shared/hdf5-models';
+import { ComplexVisType, type NumArray } from '@h5web/shared/vis-models';
+
+import { toNumArray } from '../utils';
+
+const TWO_PI = 2 * Math.PI;
 
 export const COMPLEX_VIS_TYPE_LABELS = {
   [ComplexVisType.Amplitude]: 'Amplitude',
   [ComplexVisType.Phase]: 'Phase',
+  [ComplexVisType.PhaseUnwrapped]: 'Phase (unwrapped)',
   [ComplexVisType.PhaseAmplitude]: 'Phase & Amplitude',
-};
+} satisfies Record<ComplexVisType, string>;
 
 export function getPhaseAmplitude(values: H5WebComplex[]): {
   phase: number[];
@@ -21,3 +32,52 @@ export function getPhaseAmplitude(values: H5WebComplex[]): {
 
   return { phase, amplitude };
 }
+
+// Unwrap phase values by removing 2π discontinuities
+export function unwrapPhase(values: number[]): number[] {
+  const unwrapped: number[] = Array.from({ length: values.length });
+
+  for (const [i, val] of values.entries()) {
+    if (i === 0) {
+      unwrapped[0] = val;
+      continue;
+    }
+
+    const diff = val - unwrapped[i - 1];
+    unwrapped[i] = val - TWO_PI * Math.round(diff / TWO_PI);
+  }
+
+  return unwrapped;
+}
+
+export function getPhaseAmplitudeArrays(
+  values: ArrayValue<NumericLikeType | ComplexType>[],
+): {
+  phaseArrays: NumArray[];
+  unwrappedPhaseArrays: NumArray[];
+  amplitudeArrays: NumArray[];
+} {
+  const phaseArrays: NumArray[] = [];
+  const unwrappedPhaseArrays: NumArray[] = [];
+  const amplitudeArrays: NumArray[] = [];
+
+  values.forEach((arr) => {
+    if (isComplexArray(arr)) {
+      const { phase, amplitude } = getPhaseAmplitude(arr);
+      phaseArrays.push(phase);
+      unwrappedPhaseArrays.push(unwrapPhase(phase));
+      amplitudeArrays.push(amplitude);
+      return;
+    }
+
+    // Consider real numbers as complex numbers with no imaginary parts
+    const numArray = toNumArray(arr);
+    const phaseArray = numArray.map(() => 0);
+
+    phaseArrays.push(phaseArray);
+    unwrappedPhaseArrays.push([...phaseArray]);
+    amplitudeArrays.push(numArray.map((v) => Math.abs(v)));
+  });
+
+  return { phaseArrays, unwrappedPhaseArrays, amplitudeArrays };
+}

packages/app/src/vis-packs/core/heatmap/HeatmapToolbar.tsx

@@ -10,7 +10,11 @@ import {
   ToggleBtn,
   Toolbar,
 } from '@h5web/lib';
-import { ComplexVisType, type ExportEntry } from '@h5web/shared/vis-models';
+import {
+  type ComplexHeatmapVisType,
+  ComplexVisType,
+  type ExportEntry,
+} from '@h5web/shared/vis-models';
 import { COLOR_SCALE_TYPES } from '@h5web/shared/vis-utils';
 import {
   MdAspectRatio,
@@ -22,6 +26,12 @@ import {
 import { getImageInteractions } from '../utils';
 import { type HeatmapConfig } from './config';
 
+const COMPLEX_VIS_TYPES: ComplexHeatmapVisType[] = [
+  ComplexVisType.Amplitude,
+  ComplexVisType.Phase,
+  ComplexVisType.PhaseAmplitude,
+];
+
 interface Props {
   dataDomain: Domain;
   isSlice?: boolean;
@@ -82,7 +92,7 @@ function HeatmapToolbar(props: Props) {
         <ComplexVisTypeSelector
           value={complexVisType}
           onChange={setComplexVisType}
-          options={Object.values(ComplexVisType)}
+          options={COMPLEX_VIS_TYPES}
         />
       )}
 

packages/app/src/vis-packs/core/heatmap/config.tsx

@@ -2,6 +2,7 @@ import { type CustomDomain } from '@h5web/lib';
 import { isDefined } from '@h5web/shared/guards';
 import {
   type ColorScaleType,
+  type ComplexHeatmapVisType,
   ComplexVisType,
   type NoProps,
   ScaleType,
@@ -31,8 +32,8 @@ export interface HeatmapConfig {
   scaleType: ColorScaleType;
   setScaleType: (scaleType: ColorScaleType) => void;
 
-  complexVisType: ComplexVisType;
-  setComplexVisType: (complexVisType: ComplexVisType) => void;
+  complexVisType: ComplexHeatmapVisType;
+  setComplexVisType: (complexVisType: ComplexHeatmapVisType) => void;
 
   showGrid: boolean;
   toggleGrid: () => void;

packages/app/src/vis-packs/core/line/LineToolbar.tsx

@@ -12,6 +12,7 @@ import {
   Toolbar,
 } from '@h5web/lib';
 import {
+  type ComplexLineVisType,
   ComplexVisType,
   type Domain,
   type ExportEntry,
@@ -23,6 +24,12 @@ import { CURVE_TYPE_LABELS, INTERACTIONS_WITH_AXIAL_ZOOM } from '../utils';
 import { type LineConfig } from './config';
 import ErrorsIcon from './ErrorsIcon';
 
+const COMPLEX_VIS_TYPES: ComplexLineVisType[] = [
+  ComplexVisType.Amplitude,
+  ComplexVisType.Phase,
+  ComplexVisType.PhaseUnwrapped,
+];
+
 interface Props {
   dataDomain: Domain;
   isSlice?: boolean;
@@ -84,7 +91,7 @@ function LineToolbar(props: Props) {
           <ComplexVisTypeSelector
             value={complexVisType}
             onChange={setComplexVisType}
-            options={[ComplexVisType.Amplitude, ComplexVisType.Phase]}
+            options={COMPLEX_VIS_TYPES}
           />
         </>
       )}

packages/lib/src/toolbar/controls/ComplexVisTypeSelector.tsx

@@ -3,8 +3,9 @@ import { ComplexVisType } from '@h5web/shared/vis-models';
 import Selector from './Selector/Selector';
 
 const VIS_TYPE_OPTIONS = {
-  [ComplexVisType.Phase]: 'φ Phase',
   [ComplexVisType.Amplitude]: '𝓐 Amplitude',
+  [ComplexVisType.Phase]: 'φ Phase',
+  [ComplexVisType.PhaseUnwrapped]: 'φ Phase (unwrapped)',
   [ComplexVisType.PhaseAmplitude]: 'φ𝓐 Phase & Amp.',
 } satisfies Record<ComplexVisType, string>;
 

packages/shared/src/mock-values.ts

@@ -30,10 +30,7 @@ const oneD_enum = () => ndarray([0, 2, 2, 1, 1, 0, 2, 2, 1, 1]);
 const oneD_cplx = () =>
   ndarray(
     range9().map((val) =>
-      cplx(
-        val * Math.cos((val * 3.14) / 10),
-        val * Math.sin((val * 3.14) / 10),
-      ),
+      cplx(val * Math.cos(val * 3.14), val * Math.sin(val * 3.14)),
     ),
   );
 

packages/shared/src/vis-models.ts

@@ -53,11 +53,19 @@ export type ColorScaleType = Exclude<ScaleType, 'gamma'>;
 export type AxisScaleType = Exclude<ScaleType, 'sqrt' | 'gamma'>;
 
 export enum ComplexVisType {
-  Phase = 'phase',
   Amplitude = 'amplitude',
+  Phase = 'phase',
+  PhaseUnwrapped = 'phase-unwrapped',
   PhaseAmplitude = 'phase-amplitude',
 }
-export type ComplexLineVisType = Exclude<ComplexVisType, 'phase-amplitude'>;
+export type ComplexLineVisType = Exclude<
+  ComplexVisType,
+  ComplexVisType.PhaseAmplitude
+>;
+export type ComplexHeatmapVisType = Exclude<
+  ComplexVisType,
+  ComplexVisType.PhaseUnwrapped
+>;
 
 export interface Bounds {
   min: number;