Merge pull request #16 from VH-Lab/add-readfile-functions-13897329639786336155

Refactor pyraview MEX and implement readFile functions

Author: stevevanhooser

docs/API.md

@@ -99,3 +99,28 @@ Returns:
 - `D`: A 3D matrix of size `(Samples x Channels x 2)`.
     - `D(:, :, 1)`: Minimum values.
     - `D(:, :, 2)`: Maximum values.
+
+### `HEADER = pyraview.get_header(filename)`
+Reads the binary header from a Pyraview level file.
+
+Arguments:
+- `filename`: String path to the file.
+
+Returns:
+- `HEADER`: Struct containing metadata fields (`magic`, `version`, `dataType`, `channelCount`, `sampleRate`, `nativeRate`, `startTime`, `decimationFactor`).
+
+### `obj = pyraview.Dataset(folderPath, [Name, Value...])`
+Class representing a dataset of multi-resolution files.
+
+Arguments:
+- `folderPath`: (Optional) String path to the folder containing level files.
+- `NativeRate`: (Optional) Original sampling rate.
+- `NativeStartTime`: (Optional) Start time.
+- `Channels`: (Optional) Number of channels.
+- `DataType`: (Optional) Data type string (e.g., 'int16').
+- `decimationLevels`: (Optional) Vector of decimation factors.
+- `Files`: (Optional) Cell array of filenames.
+
+Methods:
+- `[tVec, decimationLevel, sampleStart, sampleEnd] = obj.getLevelForReading(tStart, tEnd, pixels)`
+- `[tVec, dataOut] = obj.getData(tStart, tEnd, pixels)`

src/matlab/+pyraview/Dataset.m

@@ -91,7 +91,7 @@ function scanFolder(obj)
              for i = 1:length(d)
                  fullPath = fullfile(d(i).folder, d(i).name);
                  try
-                     h = pyraview.pyraview_get_header_mex(fullPath);
+                     h = pyraview.get_header(fullPath);
 
                      if firstHeader
                          obj.NativeRate = h.nativeRate;

src/matlab/+pyraview/get_header.m

@@ -0,0 +1,25 @@
+%GET_HEADER Read the Pyraview binary header from a file.
+%
+%   HEADER = pyraview.get_header(FILENAME) reads the standard 1024-byte header
+%   from the specified Pyraview level file.
+%
+%   Inputs:
+%       FILENAME - String or character vector specifying the path to the
+%                  Pyraview level file.
+%
+%   Outputs:
+%       HEADER   - Struct containing the following fields:
+%                  * magic (char): "PYRA" magic string.
+%                  * version (uint32): Format version.
+%                  * dataType (uint32): Enum value for data type (0-9).
+%                  * channelCount (uint32): Number of channels.
+%                  * sampleRate (double): Sample rate of this level.
+%                  * nativeRate (double): Original recording rate.
+%                  * startTime (double): Start time of the recording.
+%                  * decimationFactor (uint32): Cumulative decimation factor.
+%
+%   Example:
+%       h = pyraview.get_header('data_L1.bin');
+%       fprintf('Channels: %d, Rate: %.2f Hz\n', h.channelCount, h.sampleRate);
+%
+%   See also PYRAVIEW.READFILE, PYRAVIEW.DATASET

src/matlab/+pyraview/readFile.m

@@ -40,7 +40,7 @@
 
     % Read header
     try
-        h = pyraview.pyraview_get_header_mex(filename);
+        h = pyraview.get_header(filename);
     catch e
         error('Pyraview:HeaderError', 'Failed to read header: %s', e.message);
     end

src/matlab/build_pyraview.m

@@ -22,9 +22,9 @@
     mex('-v', '-outdir', out_dir, '-output', 'pyraview', include_path, src_path, mex_src);
     fprintf('Build pyraview successful.\n');
 
-    fprintf('Building pyraview_get_header_mex...\n');
-    mex('-v', '-outdir', out_dir, '-output', 'pyraview_get_header_mex', include_path, src_path, header_src);
-    fprintf('Build pyraview_get_header_mex successful.\n');
+    fprintf('Building get_header...\n');
+    mex('-v', '-outdir', out_dir, '-output', 'get_header', include_path, src_path, header_src);
+    fprintf('Build get_header successful.\n');
 catch e
     fprintf('Build failed: %s\n', e.message);
     rethrow(e);