PERF: Enlarge zlib read buffer in NIfTI reader for NAS performance

The NIfTI reader opened files with a bare gzopen(), leaving zlib at its
8 KB default internal buffer. zlib refills from the underlying file in
buffer-sized chunks, so a multi-GB .nii.gz triggered hundreds of
thousands of small reads. On network attached storage each refill is a
latency-bound round-trip, making reads disproportionately slow compared
to a local disk.

Call gzbuffer() with a 4 MiB buffer (new shared constant
nifti::k_GzReadBufferSize) immediately after every gzopen(), before the
first read/seek. This cuts the number of NAS round-trips by ~512x on a
2 GB file while costing only a few MiB of working memory. Larger buffers
yield diminishing returns once they exceed the link's bandwidth-delay
product and client read-ahead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: imikejackson

src/Plugins/SimplnxCore/src/SimplnxCore/Filters/Algorithms/ReadNIfTIFile.cpp

@@ -378,6 +378,12 @@ Result<> ReadNIfTIFile::operator()()
     return MakeErrorResult(-34720, fmt::format("Could not open NIfTI file for reading: '{}'", m_InputValues->InputFilePath.string()));
   }
 
+  // Enlarge zlib's internal buffer before the first read/seek so the file is
+  // refilled in large chunks instead of zlib's 8 KB default. This drastically
+  // reduces the number of latency-bound network round-trips when the input
+  // lives on a NAS. See nifti::k_GzReadBufferSize for the rationale.
+  gzbuffer(gz, static_cast<unsigned int>(nx::core::nifti::k_GzReadBufferSize));
+
   const z_off_t targetOffset = static_cast<z_off_t>(md.voxOffset);
   if(gzseek(gz, targetOffset, SEEK_SET) != targetOffset)
   {

src/Plugins/SimplnxCore/src/SimplnxCore/utils/NiftiUtilities.cpp

@@ -119,6 +119,11 @@ Result<NiftiMetadata> ReadNiftiHeader(const std::filesystem::path& filePath, boo
     return MakeErrorResult<NiftiMetadata>(-34700, fmt::format("Could not open NIfTI file for reading: '{}'", pathStr));
   }
 
+  // Match the voxel reader's enlarged zlib buffer so the (single) header read
+  // is served by one large refill rather than zlib's 8 KB default. Harmless
+  // here since only 348 bytes are read, but keeps the two open sites consistent.
+  gzbuffer(gz, static_cast<unsigned int>(k_GzReadBufferSize));
+
   nifti_1_header hdr{};
   int bytesRead = gzread(gz, &hdr, static_cast<unsigned int>(k_HeaderSize));
   gzclose(gz);

src/Plugins/SimplnxCore/src/SimplnxCore/utils/NiftiUtilities.hpp

@@ -46,6 +46,23 @@ inline constexpr usize k_HeaderSize = 348;
  */
 inline constexpr usize k_MinVoxOffset = 352;
 
+/**
+ * @brief Size (in bytes) of zlib's internal input/output buffer, set via
+ *        `gzbuffer()` immediately after every `gzopen()`.
+ *
+ * zlib defaults to an 8 KB internal buffer, which means it refills from
+ * the underlying file in 8 KB chunks of compressed data — one `read()`
+ * syscall each. On a local disk that is negligible, but on network
+ * attached storage (NAS) every refill is a separate network round-trip,
+ * so a multi-GB `.nii.gz` triggers hundreds of thousands of small,
+ * latency-bound reads. Raising the buffer to 4 MiB cuts the number of
+ * round-trips by ~512x while costing only a few × this size in working
+ * memory (negligible next to the voxel volume). Larger values yield
+ * diminishing returns once the buffer exceeds the link's
+ * bandwidth-delay product and the client's own read-ahead.
+ */
+inline constexpr usize k_GzReadBufferSize = 1u << 22; // 4 MiB
+
 /**
  * @brief Magic bytes that identify the single-file `.nii` / `.nii.gz`
  *        format. Trailing null is included per the spec.