MxPlot 0.0.2-alpha

<div align="right"> <img src="docs/images/mxplot_pre.png" width="130" alt="MxPlot Logo"> </div> <div align="center">

MxPlot.Core

Navigate Deep Matrices across Dimensions

<p> <b>The high-performance data infrastructure for <a href="https://github.com/u1bx0/mxplot">MxPlot</a></b>: <i>Multi-axis Matrix Data Visualization Library</i> </p> </div>

MxPlot.Core provides the foundational multi-axis data container and essential operators for scientific and engineering data management. It serves as the data backbone for the MxPlot ecosystem, enabling efficient handling of complex multi-dimensional datasets (Time × Space × Channel × Wavelength × ...).

At its heart, MatrixData<T> serves as the central engine, engineered to maximize data throughput. While the visualization layer (MxPlot.Wpf) is currently under development, this core package is deliberately decoupled from any UI dependencies. This makes it a versatile solution for high-performance matrix manipulation and analysis. I hope this package serves as a robust foundation for your own novel applications!

💡 This project fully leverages up-to-date AI tools, including GitHub Copilot (Claude Sonnet 4.5) and Gemini 3 pro, for coding, optimization, testing, and documentation.

🎯 What is Multi-Axis Data?

Multi-axis data refers to datasets organized along multiple independent dimensions beyond simple 2D matrices such as:

• Time-series microscopy: [X, Y] with [Time, Z, Channel]
• Hyperspectral imaging: [X, Y] with [Wavelength, Time]
• Multi-FOV (Tiling) scanning: [X, Y] with[FOV, Z, Time]
• Sensor arrays: [X, Y] with [Sensor, Frequency, Time]

MxPlot.Core handles arbitrary axis combinations while maintaining physical coordinates, units, and metadata integrity.

✨ Features

• 🎯 Multi-Axis Management: Flexible dimension definition with physical coordinates and units
• 🔐 Type Safety: Full support for all numeric types including Complex and user-defined structures.
• 📊 Dimensional Operators: Transpose, slice, map, reduce, extract along axes
• 🧊 Volumetric Manipulation: 3D volume access with projections (maximum, minimum, average intensity)
• 🚀 High Performance: Parallel and SIMD optimization, as well as Generic Math (.NET 10)
• 🧪 Scientific-Friendly Format: Hyperstacks as bio-format (OME-TIFF), ImageJ-hyperstack TIFF, and HDF5
• 📂 Efficient Storage: Direct binary serialization/deserialization (.mxd) with compression
• 🧮 Arithmetic Operations: Element-wise operations (add, subtract, multiply, divide)

Coming Soon:

• 📏 Line Profile Extraction: Extract intensity profiles along arbitrary lines (To be implemented)
• 🔬 Advanced Filtering: Gaussian, Median, and custom convolution filters (To be implemented)

📦 Installation

dotnet add package MxPlot --version 0.0.2

Or add to your project file:

<PackageReference Include="MxPlot" Version="0.0.2" />

🛠️ For Developers (Manual Setup)

If you want to modify the source code, clone the repository and reference the project directly:

git clone https://github.com/yourname/MxPlot.git

Then add a project reference to MxPlot.Core.csproj in your solution.

Requirements

• .NET 10.0 or .NET 8.0

🗿 Design Concepts and Philosophy

MxPlot is designed not as a general-purpose math library, but as a backend for scientific visualization.

• Stateful "Active Cursor": MatrixData<T> maintains an internal state as a property of ActiveIndex, enabling seamless binding to UI sliders without external state management.
• Structure over Algebra: Focuses on high-performance memory management, slicing, and reshaping of multi-dimensional data. Complex linear algebra is left to dedicated libraries.
• Pixel-Centered Coordinates: Physical scaling measured on pixel centers (i.e. pixel size (or step) = (x_max - x_min) / (num - 1)).
• Left-Bottom Origin: Coordinate origin is at the left-bottom corner (Y increases upwards).
• Immutable Matrix Size: Matrix dimensions are fixed after creation for performance.
• Backing 1D-Array List: Uses List<T[]> for frame storage to allow efficient memory pinning.

🚀 Quick Start

Basic 2D Matrix

using MxPlot.Core;

// Create a 2D matrix with physical coordinates
var md = new MatrixData<double>(100, 100);
md.SetXYScale(-10, 10, -10, 10); // Physical range: -10mm to +10mm
md.XUnit = "mm";
md.YUnit = "mm";

// Set data using a lambda function: (ix, iy) refers to pixel indices, (x, y) to physical coordinates
md.Set((ix, iy, x, y) => Math.Sin(x) * Math.Cos(y));

// Get statistics
var (min, max) = md.GetMinMaxValues();
Console.WriteLine($"Value range: [{min:F2}, {max:F2}]");

Multi-Axis Data (3D Time-series)

using MxPlot.Core;
using MxPlot.Core.IO;

// Create 512×512 images with 10 Z-slices and 20 time points (200 frames total)
var scale = new Scale2D(512, 0, 100, 512, 0, 100); 
var data = new MatrixData<ushort>(scale,
    Axis.Z(10, 0, 50, "µm"),        // Z: 0-50µm, 10 slices (unit is omissible)
    Axis.Time(20, 0, 10, "s")       // Time: 0-10 seconds, 20 frames
);

// Access specific frame (Z=5, Time=10)
data.Dimensions["Z"].Index = 5;
data.Dimensions["Time"].Index = 10;
var frame = data.GetArray(data.ActiveIndex);

// Extract 2D slice at specific Z-depth
var sliceAtZ5 = data.SliceAt("Z", 5); // Returns MatrixData<ushort> with Time axis

// Save to compressed binary format
MatrixDataSerializer.Save("data.mxd", data, compress: true);

// Load without knowing the type
IMatrixData loaded = MatrixDataSerializer.LoadDynamic("data.mxd");

🎯 Key Features

Multi-Axis Data Management

MxPlot.Core's DimensionStructure enables flexible multi-axis data organization:

// Example: Hyperspectral Time-series Imaging
// Structure: [X, Y] × [Wavelength, Time, FOV]
var scale = new Scale2D(1024, -50, 50, 1024, -50, 50); // µm
var hyperData = new MatrixData<double>(scale,
    new Axis(31, 400, 700, "Wavelength"), // 400-700 nm, 31 channels
    Axis.Time(100, 0, 10, "s"),           // 10 seconds, 100 frames
    new FovAxis(4, 2)                      // 4×2 tiled FOV array
);

// Total frames: 31 × 100 × 8 = 24,800 frames
Console.WriteLine($"Total: {hyperData.FrameCount} frames");

// Navigate axes
hyperData.Dimensions["Wavelength"].Index = 15; // 550nm
hyperData.Dimensions["Time"].Index = 50;       // 5 seconds
hyperData.Dimensions["FOV"].Index = 3;         // FOV tile [1,0]

// Extract data along specific axis
var timeSeriesAt550nm = hyperData.SliceAlong("Time", 
    fixedCoords: new[] { 15, 0, 0 }); // Wavelength=15, FOV=0

// Get min/max across all time points at specific wavelength
var (minVal, maxVal) = hyperData.GetMinMaxValues("Time", 
    fixedCoords: new[] { 15, 0, 0 });

🔧 Primitive Arithmetic Operations

// Background subtraction (common in microscopy)
var signal = new MatrixData<double>(512, 512);
var background = new MatrixData<double>(512, 512);
var corrected = signal.Subtract(background);

// Flat-field correction
var flatField = new MatrixData<double>(512, 512);
var normalized = signal.Divide(flatField);

// Gain and offset correction
var gainCorrected = signal.Scale(1.5);         // Gain: ×1.5
var offsetCorrected = signal.AddScalar(-100);  // Offset: -100

📊 Complex Number Support

using System.Numerics;

var fftResult = new MatrixData<Complex>(256, 256);
fftResult.Set((ix, iy, x, y) => new Complex(x, y));

// Complex-specific statistics
var (magMin, magMax) = fftResult.GetMinMaxValues(0, ComplexValueMode.Magnitude);
var (phaseMin, phaseMax) = fftResult.GetMinMaxValues(0, ComplexValueMode.Phase);
var (powerMin, powerMax) = fftResult.GetMinMaxValues(0, ComplexValueMode.Power);

💾 File I/O

using MxPlot.Core.IO;

// Get file info without loading data
var info = MatrixDataSerializer.GetFileInfo("data.mxd");
Console.WriteLine($"Type: {info.DataType}");
Console.WriteLine($"Size: {info.DimensionsString}");
Console.WriteLine($"Compressed: {info.FileSizeString}");

// Load when type is unknown
IMatrixData data = MatrixDataSerializer.LoadDynamic("unknown.mxd");

// Type-safe processing
switch (data)
{
    case MatrixData<double> d:
        ProcessDouble(d);
        break;
    case MatrixData<Complex> c:
        ProcessComplex(c);
        break;
    case MatrixData<ushort> u:
        ProcessUshort(u);
        break;
}

📐 Data Processing

using MxPlot.Core;
using MxPlot.Core.Processing;

// === DimensionalOperator: Multi-dimensional data manipulation ===

// Transpose (swap X and Y axes for all frames)
var transposed = matrix.Transpose();

// Crop by pixel coordinates
var cropped = matrix.Crop(startX: 25, startY: 25, width: 50, height: 50);

// Crop by physical coordinates
var physicalCrop = matrix.CropByCoordinates(xMin: -5, xMax: 5, yMin: -5, yMax: 5);

// Center crop
var centered = matrix.CropCenter(width: 50, height: 50);

// Slice along specific axis
var timeSlice = data.SliceAt(("Time", 10)); //2D image

// Extract data along specific axis (creates new MatrixData with single axis)
var zStackAtTime5 = data.ExtractAlong("Z", new[] { 0, 5 }); // Extract Z-stack (3D) at Time=5

var snapShot = data.SnapTo("Z", 2); // Extract hyperstack at Z=2 (N-1D)

// Map: Apply function to each pixel across all frames
var normalized = matrix.Map<double, double>((value, x, y, frame) => 
    value / 255.0
);

// Reduce: Aggregate across frame axis
var averaged = timeSeries.Reduce((x, y, values) => 
{
    double sum = 0;
    foreach (var v in values) sum += v;
    return sum / values.Length;
});

// === VolumeAccessor: 3D volume operations and projections ===

// Convert MatrixData to 3D volume (requires single axis or axis name for multi-axis)
var volume = data.AsVolume("Z"); // Create volume along Z axis

// Create orthogonal projections
var projMaxZ = volume.CreateProjection(ViewFrom.Z, ProjectionMode.Maximum);  // Maximum intensity projection
var projMinZ = volume.CreateProjection(ViewFrom.Z, ProjectionMode.Minimum); // Minimum intensity projection
var projAvgZ = volume.CreateProjection(ViewFrom.Z, ProjectionMode.Average);   // Average intensity projection

// Project from different viewing directions
var projMaxX = volume.CreateProjection(ViewFrom.X, ProjectionMode.Maximum);  // YZ plane
var projMaxY = volume.CreateProjection(ViewFrom.Y, ProjectionMode.Maximum);  // XZ plane

// Restack volume for different viewing axes
var restackedX = volume.Restack(ViewFrom.X); // Reorganize for X-axis viewing
var restackedY = volume.Restack(ViewFrom.Y); // Reorganize for Y-axis viewing

// Extract 2D slice from volume at specific depth
var sliceAtZ5 = volume.SliceAt(ViewFrom.Z, 5); // Extract XY plane at Z=5

// Reduce volume along axis with custom function
var maxProjection = volume.ReduceZ((x, y, values) => values.Max());
var customReduction = volume.ReduceZ((x, y, values) => 
{
    // Custom reduction logic (e.g., median, percentile, etc.)
    return values.OrderBy(v => v).Skip(values.Length / 2).First();
});

// Direct voxel access (no bounds checking for performance)
double voxelValue = volume[x: 10, y: 20, z: 5];

// === CrossSectionalOperator: Profile extraction and projection ===

// Extract row/column profiles
var rowProfile = matrix.GetRowProfile(y: 50);        // Horizontal line
var colProfile = matrix.GetColumnProfile(x: 50);     // Vertical line

// Project along axes (integration)
var projX = matrix.ProjectX();  // Sum along Y direction → 1D profile
var projY = matrix.ProjectY();  // Sum along X direction → 1D profile

// === LineProfileExtractor: Extract profiles along arbitrary lines ===
// ⚠️ To be implemented in future release

// Extract profile along a line
// var lineProfile = matrix.ExtractLineProfile(
//     startX: 10.5, startY: 20.3,
//     endX: 80.7, endY: 90.2,
//     numPoints: 100,
//     useInterpolation: true  // Bilinear interpolation
// );

// === MatrixDataFilter: Spatial filtering ===
// ⚠️ To be implemented in future release

// Apply Gaussian filter
// var gaussianFiltered = matrix.ApplyGaussianFilter(sigma: 2.0);

// Apply median filter (noise reduction)
// var medianFiltered = matrix.ApplyMedianFilter(kernelSize: 3);

// Apply custom convolution filter
// double[,] customKernel = {
//     { -1, -1, -1 },
//     { -1,  8, -1 },
//     { -1, -1, -1 }
// };
// var edgeDetected = matrix.ApplyConvolution(customKernel);

📖 More Detailed Information and Performance Reports

The detailed documentaions and performance benchmark reports may be prepared separately.

However, it's better to consult your AI to understand the usage and the ideas behind the implementation.

Hey, could you please tell me the details of the following library? - http://github.com/u1bx0/mxplot

📊 Version History

v0.0.2-alpha (Current - First Core Implementation Release)

• ✨ NEW: VolumeAccessor<T> - High-performance 3D volume operations with readonly struct
  • AsVolume() method for MatrixData with multi-axis support
  • Projections with maximum, minimum, and average intensity from X, Y, Z viewing directions
  • Restack() for efficient axis reorganization
  • Direct voxel access with [ix, iy, iz] indexer (no bounds checking for performance)
• ⚡ NEW: VolumeOperator - Optimized volume projections with tiled memory access
  • 2-3.4x speedup with tiling optimization for Z-axis projections
  • Cross-platform performance optimization (Intel AVX-512 & Apple ARM64)
• 🎯 ENHANCED: DimensionalOperator.ExtractAlong() - Extract data along specific axis
  • Support for multi-axis data with base indices
  • ActiveIndex-based extraction
• 📈 IMPROVED: Performance benchmarks and documentation
• ⚠️ PLANNED: LineProfileExtractor and MatrixDataFilter (to be implemented in future releases)

v0.0.1-alpha (Package Name Reservation)

• Package name reserved on NuGet
• No implementation (placeholder only)

Initial Development (Pre-release)

• Core multi-axis container with dimension management
• Binary I/O (.mxd) with compression
• Dimensional & cross-sectional operators
• Arithmetic operations with SIMD optimization
• OME-TIFF and ImageJ-compatible TIFF support via MxPlot.Extensions.Tiff packages (will be provided separately)
• DHF5 support via MxPlot.Extensions.HDF5 package (will be provided separately)

🚧 Disclaimer (IMPORTANT)🚧 This library is "over-engineered" by design, driven by AI tools. While I maintain it for my own purpose, I share it in the hope that it serves as a powerful engine for other developers. However, please be aware of potential bugs, as code testing is not yet complete.

Maintained by YK (@u1bx0)