wavesimpro 0.9.0__py3-none-any.whl

wavesimpro/binary_utils.py

@@ -0,0 +1,936 @@
+"""
+Binary data utilities for uploading/downloading numpy arrays
+
+This module provides utilities to convert numpy arrays to/from binary files
+for use with VoxelsModel primitives and CustomField sources.
+
+Also provides RMON (Rayfos MONitor) format reader/writer for self-describing
+monitor binary files.
+"""
+
+import gzip
+import struct
+import numpy as np
+from pathlib import Path
+from typing import Tuple, Union, Optional, Dict, Any
+import tempfile
+import logging
+
+logger = logging.getLogger(__name__)
+
+# RMON format constants
+RMON_MAGIC = b'RMON'
+RMON_VERSION = 3
+RMON_FIXED_HEADER_SIZE = 64
+
+# RMON data type codes
+RMON_DATATYPE_COMPLEX64 = 0
+RMON_DATATYPE_FLOAT32 = 1
+RMON_DATATYPE_FLOAT64 = 2
+RMON_DATATYPE_COMPLEX128 = 3
+
+# RMON monitor type codes
+RMON_MONITOR_PERMITTIVITY = 0
+RMON_MONITOR_FIELD = 1
+RMON_MONITOR_FLUX = 2
+RMON_MONITOR_DIFFRACTION = 3
+
+# RMON plane codes
+RMON_PLANE_XY = 0
+RMON_PLANE_YZ = 1
+RMON_PLANE_XZ = 2
+RMON_PLANE_VOLUME = 3
+
+
+class VoxelDataFormat:
+    """Binary data format specifications"""
+    FLOAT32 = "Float32"
+    FLOAT64 = "Float64"
+    COMPLEX64 = "Complex64"
+    COMPLEX128 = "Complex128"
+
+
+def upload_array_as_binary(
+    client,
+    project_id: str,
+    version_id: str,
+    data_array: np.ndarray,
+    filename: str,
+    data_type: str = "float32",
+) -> dict:
+    """
+    Upload a numpy array as a binary file
+    
+    This function converts a numpy array to a binary file and uploads it
+    to a project version. Useful for uploading refractive index distributions
+    or field data for custom primitives and sources.
+    
+    Args:
+        client: RayfosClient instance
+        project_id: Project UUID
+        version_id: Version UUID
+        data_array: Numpy array of any dimensions
+        filename: Desired filename for upload
+        data_type: Data type - 'float32', 'float64', 'complex64', 'complex128'
+    
+    Returns:
+        dict: Upload result with keys:
+            - fileId or id or blobName: File identifier
+            - dataFormat: VoxelDataFormat string
+            - dimensions: Shape of the uploaded array
+            - originalDataType: The data_type parameter
+    
+    Binary File Format:
+        Real data: Values written sequentially in C-order (row-major)
+        Complex data: Values written as interleaved [real1, imag1, real2, imag2, ...]
+    
+    Examples:
+        # Upload refractive index array
+        import numpy as np
+        w = np.ones((50, 40, 200), dtype=np.float32)
+        file_info = upload_array_as_binary(client, proj_id, ver_id, w, 'ri_data.bin', 'float32')
+        
+        # Upload complex field data
+        Es = np.random.rand(50, 40, 1) + 1j * np.random.rand(50, 40, 1)
+        file_info = upload_array_as_binary(client, proj_id, ver_id, Es, 'source_field.bin', 'complex64')
+    """
+    
+    # Validate inputs
+    if not isinstance(data_array, np.ndarray):
+        raise TypeError(f"data_array must be a numpy array, got {type(data_array)}")
+    
+    if data_array.size == 0:
+        raise ValueError("data_array cannot be empty")
+    
+    # Store original dimensions
+    original_shape = data_array.shape
+    
+    # Determine data format and prepare data
+    data_type_lower = data_type.lower()
+    
+    if data_type_lower == 'float32':
+        format_str = VoxelDataFormat.FLOAT32
+        data = data_array.astype(np.float32).flatten(order='C')
+        dtype_write = np.float32
+        
+    elif data_type_lower == 'float64':
+        format_str = VoxelDataFormat.FLOAT64
+        data = data_array.astype(np.float64).flatten(order='C')
+        dtype_write = np.float64
+        
+    elif data_type_lower == 'complex64':
+        format_str = VoxelDataFormat.COMPLEX64
+        # Interleave real and imaginary parts
+        data_flat = data_array.astype(np.complex64).flatten(order='C')
+        data = np.empty(data_flat.size * 2, dtype=np.float32)
+        data[0::2] = data_flat.real
+        data[1::2] = data_flat.imag
+        dtype_write = np.float32
+        
+    elif data_type_lower == 'complex128':
+        format_str = VoxelDataFormat.COMPLEX128
+        # Interleave real and imaginary parts
+        data_flat = data_array.astype(np.complex128).flatten(order='C')
+        data = np.empty(data_flat.size * 2, dtype=np.float64)
+        data[0::2] = data_flat.real
+        data[1::2] = data_flat.imag
+        dtype_write = np.float64
+        
+    else:
+        raise ValueError(
+            f"Unknown data type: {data_type}. "
+            f"Valid options: 'float32', 'float64', 'complex64', 'complex128'"
+        )
+    
+    # Create temporary file
+    with tempfile.NamedTemporaryFile(mode='wb', suffix='.bin', delete=False) as tmp_file:
+        temp_path = tmp_file.name
+        
+        # Write header (20 bytes total):
+        # - Version (int32, 4 bytes) = 1
+        # - DataTypeCode (int32, 4 bytes) = format index
+        # - Nx (int32, 4 bytes)
+        # - Ny (int32, 4 bytes)
+        # - Nz (int32, 4 bytes)
+        import struct
+        
+        version = 1
+        # Map data format to code: 0=Complex64, 1=Float32, 2=Float64, 3=Complex128
+        format_code_map = {
+            VoxelDataFormat.FLOAT32: 1,
+            VoxelDataFormat.FLOAT64: 2,
+            VoxelDataFormat.COMPLEX64: 0,
+            VoxelDataFormat.COMPLEX128: 3
+        }
+        data_type_code = format_code_map.get(format_str, 0)
+        
+        # Pad dimensions to 3D if needed
+        shape_3d = list(original_shape)
+        while len(shape_3d) < 3:
+            shape_3d.append(1)
+        nx, ny, nz = shape_3d[0], shape_3d[1], shape_3d[2]
+        
+        # Write header
+        header = struct.pack('<5i', version, data_type_code, nx, ny, nz)
+        tmp_file.write(header)
+        
+        # Write data
+        data.tofile(tmp_file)
+    
+    try:
+        # Upload file
+        file_info = client.upload_file(project_id, version_id, temp_path, 'input')
+        
+        # Add metadata
+        file_info['dataFormat'] = format_str
+        file_info['dimensions'] = list(original_shape)
+        file_info['originalDataType'] = data_type
+        
+        logger.info(
+            f"✓ Uploaded array as {format_str} ({filename}): {original_shape}"
+        )
+        
+        return file_info
+        
+    finally:
+        # Clean up temporary file
+        Path(temp_path).unlink(missing_ok=True)
+
+
+def read_binary_field(
+    file_path_or_data: Union[str, Path, bytes],
+    dimensions: Optional[Tuple[int, ...]] = None,
+    data_format: str = 'Complex64'
+) -> np.ndarray:
+    """
+    Read binary field data from wavesim output (file or memory)
+    
+    This function reads binary field data files produced by wavesim simulations
+    and reconstructs the numpy array with proper dimensions. Supports reading from
+    both file paths and in-memory bytes data.
+    
+    Args:
+        file_path_or_data: Path to binary file or bytes data
+        dimensions: Array dimensions (nx, ny, nz) or (nx, ny, nz, n_components)
+        data_format: Data format - 'Float32', 'Float64', 'Complex64', 'Complex128'
+    
+    Returns:
+        np.ndarray: Field data with specified dimensions
+    
+    Binary File Format:
+        Version 1 Header (20 bytes):
+            - Version (int32): 1
+            - DataTypeCode (int32): 0=Complex64, 1=Float32, 2=Float64, 3=Complex128
+            - Nx, Ny, Nz (3x int32)
+        Version 2 Header (24 bytes):
+            - Version (int32): 2
+            - DataTypeCode (int32): 0=Complex64, 1=Float32, 2=Float64, 3=Complex128
+            - nPol (int32): Number of polarization components (1=scalar, 3=vectorial)
+            - Nx, Ny, Nz (3x int32)
+        Data:
+            - Real data: Values stored sequentially
+            - Complex data: Interleaved [real1, imag1, real2, imag2, ...]
+    
+    Examples:
+        # Read from file
+        E = read_binary_field('output.bin', (50, 40, 200), 'Complex64')
+        
+        # Read from memory
+        data_bytes = client.download_file_data(project_id, version_id, file_id)
+        E = read_binary_field(data_bytes, (50, 40, 200), 'Complex64')
+    """
+    
+    # Handle input: file path or bytes
+    if isinstance(file_path_or_data, bytes):
+        # Read from memory
+        file_data = file_path_or_data
+        file_size = len(file_data)
+    else:
+        # Read from file
+        file_path = Path(file_path_or_data)
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        file_size = file_path.stat().st_size
+        with open(file_path, 'rb') as f:
+            file_data = f.read()
+    
+    # Validate inputs
+    if not dimensions:
+        raise ValueError("dimensions must be a non-empty tuple")
+    
+    # Try to read header
+    # Version 1: 20 bytes (5 int32s: version, dataType, nx, ny, nz)
+    # Version 2: 24 bytes (6 int32s: version, dataType, nPol, nx, ny, nz)
+    has_header = file_size >= 20
+    version = 2  # Default to version 2 (solver output)
+    n_pol_from_header = 1
+    header_dims = None
+
+    if has_header:
+        try:
+            # Read first int32 to check version
+            ver_check = struct.unpack('<i', file_data[:4])[0]
+
+            if ver_check == 1:
+                # Version 1: 20-byte header [version, dataType, nx, ny, nz]
+                header = struct.unpack('<5i', file_data[:20])
+                version, data_type_code, nx_file, ny_file, nz_file = header
+                n_pol_from_header = 1
+                header_dims = (nx_file, ny_file, nz_file)
+                logger.info(f"Found binary header (version 1): dims=[{nx_file}, {ny_file}, {nz_file}]")
+                file_data = file_data[20:]
+                file_size -= 20
+            elif ver_check == 2:
+                # Version 2: 24-byte header [version, dataType, nPol, nx, ny, nz]
+                header = struct.unpack('<6i', file_data[:24])
+                version, data_type_code, n_pol_from_header, nx_file, ny_file, nz_file = header
+                if n_pol_from_header > 1:
+                    header_dims = (n_pol_from_header, nx_file, ny_file, nz_file)
+                else:
+                    header_dims = (nx_file, ny_file, nz_file)
+                logger.info(f"Found binary header (version 2): nPol={n_pol_from_header}, dims=[{nx_file}, {ny_file}, {nz_file}]")
+                file_data = file_data[24:]
+                file_size -= 24
+            else:
+                # Not a valid header, treat as raw data (version 2)
+                logger.info("No valid header found, assuming version 2 (raw data)")
+                version = 2
+        except struct.error:
+            # Failed to unpack header, treat as raw data
+            logger.info("Failed to read header, assuming version 2 (raw data)")
+            version = 2
+    else:
+        logger.info("File too small for header, assuming version 2 (raw data)")
+        version = 2
+
+    # Use header dimensions if caller didn't provide them
+    if dimensions is None or len(dimensions) == 0:
+        if header_dims is not None:
+            dimensions = header_dims
+            logger.info(f"Auto-detected dimensions from header: {dimensions}")
+        else:
+            raise ValueError("No dimensions provided and no valid header found to auto-detect")
+    
+    # Determine precision and whether data is complex
+    if data_format == 'Float32':
+        dtype_read = np.float32
+        is_complex = False
+        bytes_per_value = 4
+        
+    elif data_format == 'Float64':
+        dtype_read = np.float64
+        is_complex = False
+        bytes_per_value = 8
+        
+    elif data_format == 'Complex64':
+        dtype_read = np.float32
+        is_complex = True
+        bytes_per_value = 8  # 4 bytes real + 4 bytes imag
+        
+    elif data_format == 'Complex128':
+        dtype_read = np.float64
+        is_complex = True
+        bytes_per_value = 16  # 8 bytes real + 8 bytes imag
+        
+    else:
+        raise ValueError(
+            f"Unknown data format: {data_format}. "
+            f"Valid options: 'Float32', 'Float64', 'Complex64', 'Complex128'"
+        )
+    
+    # Calculate expected number of elements
+    total_elements = np.prod(dimensions)
+    expected_size = total_elements * bytes_per_value
+    
+    if file_size != expected_size:
+        logger.warning(
+            f"File size mismatch!\n"
+            f"  Expected: {expected_size} bytes ({total_elements} elements × {bytes_per_value} bytes/element)\n"
+            f"  Actual: {file_size} bytes\n"
+            f"  Attempting to read anyway..."
+        )
+    
+    # Read data
+    if is_complex:
+        # Read interleaved complex data
+        data = np.frombuffer(file_data, dtype=dtype_read)
+        
+        if data.size < total_elements * 2:
+            logger.warning(
+                f"Read fewer elements than expected: {data.size} / {total_elements * 2}"
+            )
+        
+        # De-interleave: [r1, i1, r2, i2, ...] -> [r1, r2, ...] + 1j*[i1, i2, ...]
+        real_part = data[0::2]
+        imag_part = data[1::2]
+        field_data = real_part + 1j * imag_part
+        
+    else:
+        # Read real data
+        field_data = np.frombuffer(file_data, dtype=dtype_read)
+        
+        if field_data.size < total_elements:
+            logger.warning(
+                f"Read fewer elements than expected: {field_data.size} / {total_elements}"
+            )
+    
+    # Handle dimension permutation based on version
+    if version == 1:
+        # Version 1: Data was permuted before writing, need to reverse
+        reversed_dims = dimensions[::-1]
+        field_data = field_data.reshape(reversed_dims, order='C')
+        # Reverse permutation
+        perm_order = tuple(range(len(dimensions) - 1, -1, -1))
+        field_data = np.transpose(field_data, perm_order)
+    else:
+        # Version 2: Data is already in correct order
+        field_data = field_data.reshape(dimensions, order='C')
+    
+    logger.info(
+        f"✓ Read {data_format} field data (version {version}): {field_data.shape} ({file_size} bytes)"
+    )
+    
+    return field_data
+
+
+def write_array_to_binary(
+    data_array: np.ndarray,
+    file_path: Union[str, Path],
+    data_type: str = "float32"
+) -> Path:
+    """
+    Write a numpy array to a binary file
+    
+    Helper function to create binary files locally before uploading.
+    
+    Args:
+        data_array: Numpy array to write
+        file_path: Path where to save the binary file
+        data_type: Data type - 'float32', 'float64', 'complex64', 'complex128'
+    
+    Returns:
+        Path: Path to the created file
+    
+    Example:
+        import numpy as np
+        w = np.ones((50, 40, 200), dtype=np.float32)
+        file_path = write_array_to_binary(w, 'ri_data.bin', 'float32')
+    """
+    
+    file_path = Path(file_path)
+    
+    # Determine data format and prepare data
+    data_type_lower = data_type.lower()
+    
+    if data_type_lower == 'float32':
+        data = data_array.astype(np.float32).flatten(order='C')
+        
+    elif data_type_lower == 'float64':
+        data = data_array.astype(np.float64).flatten(order='C')
+        
+    elif data_type_lower == 'complex64':
+        # Interleave real and imaginary parts
+        data_flat = data_array.astype(np.complex64).flatten(order='C')
+        data = np.empty(data_flat.size * 2, dtype=np.float32)
+        data[0::2] = data_flat.real
+        data[1::2] = data_flat.imag
+        
+    elif data_type_lower == 'complex128':
+        # Interleave real and imaginary parts
+        data_flat = data_array.astype(np.complex128).flatten(order='C')
+        data = np.empty(data_flat.size * 2, dtype=np.float64)
+        data[0::2] = data_flat.real
+        data[1::2] = data_flat.imag
+        
+    else:
+        raise ValueError(
+            f"Unknown data type: {data_type}. "
+            f"Valid options: 'float32', 'float64', 'complex64', 'complex128'"
+        )
+    
+    # Write to file
+    data.tofile(file_path)
+
+    logger.info(f"✓ Wrote {data_array.shape} array to {file_path} ({file_path.stat().st_size} bytes)")
+
+    return file_path
+
+
+def write_monitor_binary(
+    file_path: Union[str, Path],
+    data: np.ndarray,
+    name: str = "",
+    monitor_type: int = RMON_MONITOR_FIELD,
+    plane: int = RMON_PLANE_XY,
+    field_mask: int = 0,
+    voxel_size_um: float = 0.0,
+    origin_um: Tuple[float, float, float] = (0.0, 0.0, 0.0),
+    wavelength_um: float = 0.0,
+) -> Path:
+    """
+    Write a numpy array as an RMON (Rayfos MONitor) self-describing binary file.
+
+    The RMON format contains a full metadata header (monitor type, plane, voxel size,
+    world-space origin, wavelength, etc.) so the file can be interpreted without
+    external context.
+
+    Args:
+        file_path: Output file path
+        data: Numpy array of shape (nx, ny, nz) or (nComponents, nx, ny, nz).
+              Complex arrays are stored as interleaved real/imag pairs.
+        name: Monitor name (stored in header)
+        monitor_type: RMON_MONITOR_* constant (0=Permittivity, 1=Field, 2=Flux, 3=Diffraction)
+        plane: RMON_PLANE_* constant (0=XY, 1=YZ, 2=XZ, 3=Volume)
+        field_mask: Bitmask of recorded field components (bit0=Ex, bit1=Ey, etc.)
+        voxel_size_um: Voxel size in micrometers
+        origin_um: World-space origin (x, y, z) in micrometers
+        wavelength_um: Simulation wavelength in micrometers
+
+    Returns:
+        Path to the created file
+
+    Example:
+        import numpy as np
+        E = np.random.rand(50, 40, 1) + 1j * np.random.rand(50, 40, 1)
+        write_monitor_binary('monitor_Field_0.bin', E, name='Field_0',
+                             voxel_size_um=0.05, origin_um=(-1.25, -1.0, 0.0))
+    """
+    file_path = Path(file_path)
+
+    # Determine shape and components
+    if data.ndim == 4:
+        n_components, nx, ny, nz = data.shape
+    elif data.ndim == 3:
+        n_components = 1
+        nx, ny, nz = data.shape
+        data = data[np.newaxis, ...]  # Add component dimension
+    else:
+        raise ValueError(f"data must be 3D or 4D, got {data.ndim}D")
+
+    # Determine data type
+    if np.iscomplexobj(data):
+        data_type_code = RMON_DATATYPE_COMPLEX64
+        write_dtype = np.float32
+    else:
+        data_type_code = RMON_DATATYPE_FLOAT32
+        write_dtype = np.float32
+
+    # Encode name
+    name_bytes = name.encode('utf-8')
+    name_length = len(name_bytes)
+
+    # Calculate total header size (aligned to 4 bytes)
+    variable_size = 4 + name_length  # NameLength + Name
+    total_header = RMON_FIXED_HEADER_SIZE + variable_size
+    total_header = (total_header + 3) & ~3  # Align to 4 bytes
+    padding = total_header - (RMON_FIXED_HEADER_SIZE + variable_size)
+
+    with open(file_path, 'wb') as f:
+        # Fixed header (64 bytes)
+        f.write(RMON_MAGIC)                                         # 0-3: Magic
+        f.write(struct.pack('<i', RMON_VERSION))                    # 4-7: Version
+        f.write(struct.pack('<i', total_header))                    # 8-11: HeaderSize
+        f.write(struct.pack('<i', data_type_code))                  # 12-15: DataType
+        f.write(struct.pack('<i', monitor_type))                    # 16-19: MonitorType
+        f.write(struct.pack('<i', plane))                           # 20-23: Plane
+        f.write(struct.pack('<i', field_mask))                      # 24-27: FieldMask
+        f.write(struct.pack('<i', n_components))                    # 28-31: nComponents
+        f.write(struct.pack('<i', nx))                              # 32-35: ShapeX
+        f.write(struct.pack('<i', ny))                              # 36-39: ShapeY
+        f.write(struct.pack('<i', nz))                              # 40-43: ShapeZ
+        f.write(struct.pack('<f', voxel_size_um))                   # 44-47: VoxelSize_um
+        f.write(struct.pack('<f', origin_um[0]))                    # 48-51: OriginX_um
+        f.write(struct.pack('<f', origin_um[1]))                    # 52-55: OriginY_um
+        f.write(struct.pack('<f', origin_um[2]))                    # 56-59: OriginZ_um
+        f.write(struct.pack('<f', wavelength_um))                   # 60-63: Wavelength_um
+
+        # Variable header
+        f.write(struct.pack('<i', name_length))                     # 64-67: NameLength
+        f.write(name_bytes)                                         # 68+: Name
+        f.write(b'\x00' * padding)                                  # Padding
+
+        # Data section: component-major, then X -> Y -> Z
+        for comp in range(n_components):
+            comp_data = data[comp]
+            if np.iscomplexobj(comp_data):
+                # Interleave real/imag
+                flat = comp_data.astype(np.complex64).flatten(order='C')
+                interleaved = np.empty(flat.size * 2, dtype=np.float32)
+                interleaved[0::2] = flat.real
+                interleaved[1::2] = flat.imag
+                interleaved.tofile(f)
+            else:
+                comp_data.astype(write_dtype).flatten(order='C').tofile(f)
+
+    file_size = file_path.stat().st_size
+    logger.info(
+        f"✓ Wrote RMON file: {file_path} ({nx}×{ny}×{nz}, {n_components} comp, {file_size} bytes)"
+    )
+
+    return file_path
+
+
+def read_monitor_binary(
+    file_path_or_data: Union[str, Path, bytes],
+) -> Tuple[Dict[str, Any], np.ndarray]:
+    """
+    Read an RMON (Rayfos MONitor) binary file.
+
+    Auto-detects RMON format by checking for "RMON" magic bytes. If the data
+    is not RMON format, raises ValueError.
+
+    Args:
+        file_path_or_data: Path to binary file or bytes data
+
+    Returns:
+        Tuple of (header_dict, data_array):
+        - header_dict: Dictionary with all RMON header fields
+        - data_array: Numpy array of shape (nComponents, nx, ny, nz).
+          Complex data is returned as complex64 dtype.
+
+    Example:
+        header, data = read_monitor_binary('monitor_Field_0.bin')
+        print(f"Monitor: {header['name']}, Shape: {data.shape}")
+        magnitude = np.abs(data[0])  # First component magnitude
+    """
+    # Read data
+    if isinstance(file_path_or_data, bytes):
+        file_data = file_path_or_data
+    else:
+        file_path = Path(file_path_or_data)
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        with open(file_path, 'rb') as f:
+            file_data = f.read()
+
+    # Check magic bytes
+    if len(file_data) < RMON_FIXED_HEADER_SIZE:
+        raise ValueError("Data too small for RMON header")
+
+    if file_data[:4] != RMON_MAGIC:
+        raise ValueError(
+            f"Not an RMON file: magic bytes are {file_data[:4]!r}, expected {RMON_MAGIC!r}"
+        )
+
+    # Parse fixed header
+    (version,) = struct.unpack_from('<i', file_data, 4)
+    if version != 3:
+        raise ValueError(f"Unsupported RMON version: {version}. Expected 3.")
+
+    (header_size,) = struct.unpack_from('<i', file_data, 8)
+    (data_type_code,) = struct.unpack_from('<i', file_data, 12)
+    (monitor_type,) = struct.unpack_from('<i', file_data, 16)
+    (plane,) = struct.unpack_from('<i', file_data, 20)
+    (field_mask,) = struct.unpack_from('<i', file_data, 24)
+    (n_components,) = struct.unpack_from('<i', file_data, 28)
+    (nx,) = struct.unpack_from('<i', file_data, 32)
+    (ny,) = struct.unpack_from('<i', file_data, 36)
+    (nz,) = struct.unpack_from('<i', file_data, 40)
+    (voxel_size_um,) = struct.unpack_from('<f', file_data, 44)
+    (origin_x_um,) = struct.unpack_from('<f', file_data, 48)
+    (origin_y_um,) = struct.unpack_from('<f', file_data, 52)
+    (origin_z_um,) = struct.unpack_from('<f', file_data, 56)
+    (wavelength_um,) = struct.unpack_from('<f', file_data, 60)
+
+    # Parse variable header (name)
+    name = ""
+    if header_size > 68:
+        (name_length,) = struct.unpack_from('<i', file_data, 64)
+        if 0 < name_length < 1024:
+            name = file_data[68:68 + name_length].decode('utf-8', errors='replace')
+
+    monitor_type_names = {0: 'Permittivity', 1: 'Field', 2: 'Flux', 3: 'Diffraction'}
+    plane_names = {0: 'XY', 1: 'YZ', 2: 'XZ', 3: 'Volume'}
+
+    header = {
+        'version': version,
+        'header_size': header_size,
+        'data_type': data_type_code,
+        'monitor_type': monitor_type,
+        'monitor_type_name': monitor_type_names.get(monitor_type, f'unknown({monitor_type})'),
+        'plane': plane,
+        'plane_name': plane_names.get(plane, f'unknown({plane})'),
+        'field_mask': field_mask,
+        'n_components': n_components,
+        'shape': (nx, ny, nz),
+        'voxel_size_um': voxel_size_um,
+        'origin_um': (origin_x_um, origin_y_um, origin_z_um),
+        'wavelength_um': wavelength_um,
+        'name': name,
+    }
+
+    # Parse data section
+    raw_data = file_data[header_size:]
+    is_complex = data_type_code in (RMON_DATATYPE_COMPLEX64, RMON_DATATYPE_COMPLEX128)
+
+    total_voxels = n_components * nx * ny * nz
+
+    if is_complex:
+        if data_type_code == RMON_DATATYPE_COMPLEX64:
+            floats = np.frombuffer(raw_data, dtype=np.float32)
+        else:
+            floats = np.frombuffer(raw_data, dtype=np.float64)
+
+        real_part = floats[0::2]
+        imag_part = floats[1::2]
+        flat_complex = real_part + 1j * imag_part
+        data = flat_complex[:total_voxels].reshape((n_components, nx, ny, nz), order='C')
+        if data_type_code == RMON_DATATYPE_COMPLEX64:
+            data = data.astype(np.complex64)
+    else:
+        if data_type_code == RMON_DATATYPE_FLOAT32:
+            flat = np.frombuffer(raw_data, dtype=np.float32)
+        else:
+            flat = np.frombuffer(raw_data, dtype=np.float64)
+        data = flat[:total_voxels].reshape((n_components, nx, ny, nz), order='C')
+
+    logger.info(
+        f"✓ Read RMON file: name='{name}', type={header['monitor_type_name']}, "
+        f"shape=({nx},{ny},{nz}), {n_components} comp"
+    )
+
+    return header, data
+
+
+def is_rmon_file(file_path_or_data: Union[str, Path, bytes]) -> bool:
+    """
+    Check if a file or bytes data is in RMON format by checking magic bytes.
+
+    Args:
+        file_path_or_data: Path to file or bytes data
+
+    Returns:
+        True if the data starts with RMON magic bytes
+    """
+    if isinstance(file_path_or_data, bytes):
+        return len(file_path_or_data) >= 4 and file_path_or_data[:4] == RMON_MAGIC
+
+    file_path = Path(file_path_or_data)
+    if not file_path.exists() or file_path.stat().st_size < 4:
+        return False
+
+    with open(file_path, 'rb') as f:
+        magic = f.read(4)
+    return magic == RMON_MAGIC
+
+
+def _prepare_binary_data(
+    data_array: np.ndarray,
+    data_type: str,
+    header_version: int,
+) -> Tuple[bytes, str, list]:
+    """
+    Prepare binary data with header for upload.
+
+    Args:
+        data_array: Numpy array
+        data_type: 'float32', 'float64', 'complex64', 'complex128'
+        header_version: 1 for source fields, 2 for RI/permittivity
+
+    Returns:
+        Tuple of (binary_data_bytes, format_string, shape_3d_list)
+    """
+    if not isinstance(data_array, np.ndarray):
+        raise TypeError(f"data_array must be a numpy array, got {type(data_array)}")
+    if data_array.size == 0:
+        raise ValueError("data_array cannot be empty")
+
+    original_shape = data_array.shape
+    shape_3d = list(original_shape)
+    while len(shape_3d) < 3:
+        shape_3d.append(1)
+    nx, ny, nz = shape_3d[0], shape_3d[1], shape_3d[2]
+
+    data_type_lower = data_type.lower()
+
+    format_code_map = {
+        'float32': (VoxelDataFormat.FLOAT32, 1),
+        'float64': (VoxelDataFormat.FLOAT64, 2),
+        'complex64': (VoxelDataFormat.COMPLEX64, 0),
+        'complex128': (VoxelDataFormat.COMPLEX128, 3),
+    }
+
+    if data_type_lower not in format_code_map:
+        raise ValueError(
+            f"Unknown data type: {data_type}. "
+            f"Valid options: 'float32', 'float64', 'complex64', 'complex128'"
+        )
+
+    format_str, data_type_code = format_code_map[data_type_lower]
+    is_complex = data_type_lower in ('complex64', 'complex128')
+
+    # Permute and flatten based on header version
+    if header_version == 2:
+        # Version 2 (RI/permittivity): XYZ order, Z-fastest
+        # C-order flatten of (nx, ny, nz) gives Z-fastest directly — no transpose needed.
+        # (The old transpose + flatten('C') produced X-fastest, which was wrong.)
+        flat = data_array.reshape(nx, ny, nz).flatten(order='C')
+    else:
+        # Version 1 (source fields): C-order flatten (z-slowest, x-fastest)
+        reshaped = data_array.reshape(nx, ny, nz)
+        flat = np.empty(nx * ny * nz, dtype=data_array.dtype)
+        idx = 0
+        for iz in range(nz):
+            for iy in range(ny):
+                for ix in range(nx):
+                    flat[idx] = reshaped[ix, iy, iz]
+                    idx += 1
+
+    # Convert to interleaved real/imag for complex types
+    if is_complex:
+        if data_type_lower == 'complex64':
+            flat_c = flat.astype(np.complex64)
+            write_dtype = np.float32
+        else:
+            flat_c = flat.astype(np.complex128)
+            write_dtype = np.float64
+        interleaved = np.empty(flat_c.size * 2, dtype=write_dtype)
+        interleaved[0::2] = flat_c.real
+        interleaved[1::2] = flat_c.imag
+        data_bytes_payload = interleaved.tobytes()
+    else:
+        if data_type_lower == 'float32':
+            data_bytes_payload = flat.astype(np.float32).tobytes()
+        else:
+            data_bytes_payload = flat.astype(np.float64).tobytes()
+
+    # Build header
+    header = struct.pack('<5i', header_version, data_type_code, nx, ny, nz)
+
+    return header + data_bytes_payload, format_str, [nx, ny, nz]
+
+
+def upload_source_field_as_binary(
+    client,
+    project_id: str,
+    version_id: str,
+    data_array: np.ndarray,
+    filename: str,
+    data_type: str = "complex64",
+) -> dict:
+    """
+    Upload a source field array as a binary file with Version 1 header.
+
+    Source fields use Version 1 header format with C-order data layout
+    (z-slowest, x-fastest), matching MATLAB's uploadSourceFieldAsBinary.
+
+    Args:
+        client: RayfosClient instance
+        project_id: Project UUID
+        version_id: Version UUID
+        data_array: Numpy array (typically complex)
+        filename: Desired filename for upload
+        data_type: 'float32', 'float64', 'complex64', 'complex128'
+
+    Returns:
+        dict: Upload result with fileId/id/blobName, dataFormat, dimensions
+    """
+    binary_data, format_str, dims = _prepare_binary_data(data_array, data_type, header_version=1)
+
+    with tempfile.NamedTemporaryFile(mode='wb', suffix='.bin', delete=False) as tmp:
+        temp_path = tmp.name
+        tmp.write(binary_data)
+
+    try:
+        file_info = client.upload_file(project_id, version_id, temp_path, 'input')
+        file_info['dataFormat'] = format_str
+        file_info['dimensions'] = dims
+        file_info['originalDataType'] = data_type
+        logger.info(f"Uploaded source field as {format_str} ({filename}): {dims}")
+        return file_info
+    finally:
+        Path(temp_path).unlink(missing_ok=True)
+
+
+def upload_array_as_binary_zipped(
+    client,
+    project_id: str,
+    version_id: str,
+    data_array: np.ndarray,
+    filename: str,
+    data_type: str = "float32",
+) -> dict:
+    """
+    Upload a numpy array as a gzip-compressed binary file with Version 2 header.
+
+    Used for refractive index / permittivity data. Version 2 header with
+    permuted data order (z-fastest after permutation), matching MATLAB's
+    uploadArrayAsBinaryZipped.
+
+    Args:
+        client: RayfosClient instance
+        project_id: Project UUID
+        version_id: Version UUID
+        data_array: Numpy array
+        filename: Desired filename (without .gz)
+        data_type: 'float32', 'float64', 'complex64', 'complex128'
+
+    Returns:
+        dict: Upload result with fileId, dataFormat, dimensions, isCompressed
+    """
+    binary_data, format_str, dims = _prepare_binary_data(data_array, data_type, header_version=2)
+
+    gz_filename = filename + '.gz'
+    with tempfile.NamedTemporaryFile(mode='wb', suffix='.bin.gz', delete=False) as tmp:
+        temp_path = tmp.name
+        tmp.write(gzip.compress(binary_data))
+
+    try:
+        file_info = client.upload_file(project_id, version_id, temp_path, 'input')
+        file_info['dataFormat'] = format_str
+        file_info['dimensions'] = dims
+        file_info['originalDataType'] = data_type
+        file_info['isCompressed'] = True
+        file_info['compressionType'] = 'gzip'
+        file_info['uncompressedSize'] = len(binary_data)
+        logger.info(f"Uploaded compressed array as {format_str} ({gz_filename}): {dims}")
+        return file_info
+    finally:
+        Path(temp_path).unlink(missing_ok=True)
+
+
+def upload_source_field_as_binary_zipped(
+    client,
+    project_id: str,
+    version_id: str,
+    data_array: np.ndarray,
+    filename: str,
+    data_type: str = "complex64",
+) -> dict:
+    """
+    Upload a source field as a gzip-compressed binary file with Version 1 header.
+
+    Combines the source field binary format (Version 1 header, C-order data)
+    with gzip compression, matching MATLAB's uploadSourceFieldAsBinaryZipped.
+
+    Args:
+        client: RayfosClient instance
+        project_id: Project UUID
+        version_id: Version UUID
+        data_array: Numpy array (typically complex)
+        filename: Desired filename (without .gz)
+        data_type: 'float32', 'float64', 'complex64', 'complex128'
+
+    Returns:
+        dict: Upload result with fileId, dataFormat, dimensions, isCompressed
+    """
+    binary_data, format_str, dims = _prepare_binary_data(data_array, data_type, header_version=1)
+
+    gz_filename = filename + '.gz'
+    with tempfile.NamedTemporaryFile(mode='wb', suffix='.bin.gz', delete=False) as tmp:
+        temp_path = tmp.name
+        tmp.write(gzip.compress(binary_data))
+
+    try:
+        file_info = client.upload_file(project_id, version_id, temp_path, 'input')
+        file_info['dataFormat'] = format_str
+        file_info['dimensions'] = dims
+        file_info['originalDataType'] = data_type
+        file_info['isCompressed'] = True
+        file_info['compressionType'] = 'gzip'
+        file_info['uncompressedSize'] = len(binary_data)
+        logger.info(f"Uploaded compressed source field as {format_str} ({gz_filename}): {dims}")
+        return file_info
+    finally:
+        Path(temp_path).unlink(missing_ok=True)
+