decompress: option to only process user selected components

Author: Grok Compression

src/lib/codec/apps/GrkDecompress.cpp

@@ -29,6 +29,7 @@
 #endif /* _WIN32 */
 #include <climits>
 #include <string>
+#include <sstream>
 #include <chrono>
 #include <thread>
 #include <algorithm>
@@ -340,7 +341,8 @@ GrkRC GrkDecompress::parseCommandLine(int argc, const char* argv[],
   CLI::App cmd("grk_decompress command line", grk_version());
 
   std::string outDir, compression, decodeRegion, pluginPathStr, inputFile, outputFile, outFor,
-      precision, logfile, inDir;
+      precision, logfile, inDir, components;
+  auto& compIndices = initParams->compIndices;
   uint32_t repetitions = 0, numThreads = 0, kernelBuildOptions = 0,
            compressionLevel = std::numeric_limits<uint32_t>::max(), disableRandomAccess = 0,
            tile = 0, duration = 0;
@@ -369,6 +371,9 @@ GrkRC GrkDecompress::parseCommandLine(int argc, const char* argv[],
       cmd.add_option("-L,--compression-level", compressionLevel, "Output compression Level");
   auto randomAccessOpt = cmd.add_option("-m,--random-access", disableRandomAccess,
                                         "Toggle support for random access into code stream");
+  auto componentsOpt = cmd.add_option(
+      "-n,--components", components,
+      "Comma-separated list of 0-based component indices to decode (e.g. '0' or '0,2')");
   auto outputFileOpt = cmd.add_option("-o,--out-file", outputFile, "Output file");
   auto outForOpt = cmd.add_option("-O,--out-fmt", outFor, "Output Format");
   auto precisionOpt = cmd.add_option("-p,--precision", precision, "Force precision");
@@ -563,6 +568,34 @@ GrkRC GrkDecompress::parseCommandLine(int argc, const char* argv[],
     parameters->core.reduce = reduce;
   if(layerOpt->count() > 0)
     parameters->core.layers_to_decompress = layer;
+  if(componentsOpt->count() > 0)
+  {
+    std::istringstream iss(components);
+    std::string token;
+    while(std::getline(iss, token, ','))
+    {
+      try
+      {
+        int val = std::stoi(token);
+        if(val < 0 || val > 16383)
+        {
+          spdlog::error("Component index {} out of range [0, 16383]", val);
+          return GrkRCParseArgsFailed;
+        }
+        compIndices.push_back((uint16_t)val);
+      }
+      catch(...)
+      {
+        spdlog::error("Invalid component index: {}", token);
+        return GrkRCParseArgsFailed;
+      }
+    }
+    if(!compIndices.empty())
+    {
+      parameters->core.comps_to_decode = compIndices.data();
+      parameters->core.num_comps_to_decode = (uint16_t)compIndices.size();
+    }
+  }
   if(randomAccessOpt->count() > 0)
     parameters->core.disable_random_access_flags = disableRandomAccess;
   parameters->single_tile_decompress = tileOpt->count() > 0;

src/lib/codec/apps/GrkDecompress.h

@@ -19,6 +19,7 @@
 #include "common.h"
 #include "IImageFormat.h"
 #include "CLI/CLI.hpp"
+#include <vector>
 
 namespace grk
 {
@@ -38,6 +39,7 @@ struct DecompressInitParams
   }
   bool initialized;
   grk_decompress_parameters parameters;
+  std::vector<uint16_t> compIndices;
   char pluginPath[GRK_PATH_LEN];
   grk_img_fol inputFolder;
   grk_img_fol outFolder;

src/lib/core/codestream/CodingParams.cpp

@@ -195,6 +195,11 @@ void CodingParams::init(grk_decompress_parameters* parameters,
     tileCache->setDirty(true);
   }
   codingParams_.dec_.layersToDecompress_ = core->layers_to_decompress;
+  if(core->num_comps_to_decode > 0 && core->comps_to_decode)
+    compsToDecompress_.assign(core->comps_to_decode,
+                              core->comps_to_decode + core->num_comps_to_decode);
+  else
+    compsToDecompress_.clear();
 }
 
 bool CodingParams::hasTLM(void) const noexcept

src/lib/core/codestream/CodingParams.h

@@ -448,6 +448,8 @@ struct CodingParams
     DecodingParams dec_;
     EncodingParams enc_;
   } codingParams_;
+  /** Component indices to decode during decompression. Empty = decode all. */
+  std::vector<uint16_t> compsToDecompress_;
   std::unique_ptr<TLMMarker> tlmMarkers_;
   std::unique_ptr<PLMarker> plmMarkers_;
   bool asynchronous_;

src/lib/core/codestream/decompress/CodeStreamDecompress.cpp

@@ -834,6 +834,7 @@ bool CodeStreamDecompress::postProcess(GrkImage* img)
 {
   if(!img->postProcess())
     return false;
+  img->filterComponents(cp_.compsToDecompress_);
   return postPostProcess_ ? postPostProcess_(img) : true;
 }
 

src/lib/core/grok.h

@@ -645,6 +645,15 @@ typedef struct _grk_decompress_core_params
   grk_io_pixels_callback io_buffer_callback; /* IO buffer callback */
   void* io_user_data; /* IO user data */
   grk_io_register_reclaim_callback io_register_client_callback; /* IO register client callback */
+  /**
+   * Array of 0-based component indices to decode.
+   * Only these components will be fully decoded (T1, DWT, etc.).
+   * When MCT is active, components 0-2 will always be decoded if any of them is requested.
+   * If num_comps_to_decode is 0 or comps_to_decode is nullptr, all components are decoded.
+   * Memory is owned by the caller.
+   */
+  uint16_t* comps_to_decode;
+  uint16_t num_comps_to_decode;
 } grk_decompress_core_params;
 
 /**

src/lib/core/scheduling/standard/DecompressScheduler.cpp

@@ -129,6 +129,10 @@ bool DecompressScheduler::scheduleT1(ITileProcessor* tileProcessor)
 
   for(uint16_t compno = 0; compno < numcomps_; ++compno)
   {
+    // skip components not selected for decoding
+    if(!tileProcessor->shouldDecodeComponent(compno))
+      continue;
+
     // schedule blocks
     auto tccp = tcp->tccps_ + compno;
     // nominal code block dimensions

src/lib/core/tile_processor/ITileProcessor.h

@@ -279,6 +279,14 @@ struct ITileProcessor
    */
   virtual bool needsMctDecompress(void) = 0;
 
+  /**
+   * @brief Check if a component should be decoded based on user selection.
+   * When MCT=1 is active and any of components 0-2 is requested, all three are decoded.
+   * @param compno 0-based component index
+   * @return true if the component should be decoded
+   */
+  virtual bool shouldDecodeComponent(uint16_t compno) = 0;
+
   /**
    * @brief Gets the MCT (Multi-Component Transform) object
    * @return Pointer to Mct

src/lib/core/tile_processor/TileProcessor.cpp

@@ -24,6 +24,7 @@
 #include "GrkObjectWrapper.h"
 #include "Quantizer.h"
 
+#include <algorithm>
 #include "ImageComponentFlow.h"
 #include "TileFutureManager.h"
 
@@ -1149,6 +1150,10 @@ void TileProcessor::scheduleAndRunDecompress(CoderPool* coderPool, Rect32 unredu
       return;
     for(uint16_t compno = 0; compno < tile_->numcomps_; ++compno)
     {
+      // skip allocation for components not selected for decoding
+      if(!shouldDecodeComponent(compno))
+        continue;
+
       auto tilec = tile_->comps_ + compno;
 
       if(Scheduling::isExcalibur())
@@ -1278,5 +1283,28 @@ bool TileProcessor::needsMctDecompress(uint16_t compno)
 {
   return needsMctDecompress() && (compno <= 2);
 }
+bool TileProcessor::shouldDecodeComponent(uint16_t compno)
+{
+  auto& comps = cp_->compsToDecompress_;
+  if(comps.empty())
+    return true; // decode all
+
+  // Check if this component is directly requested
+  bool requested = std::find(comps.begin(), comps.end(), compno) != comps.end();
+  if(requested)
+    return true;
+
+  // If MCT=1 is active and any of components 0-2 is requested, decode all three
+  if(needsMctDecompress() && compno <= 2)
+  {
+    for(auto c : comps)
+    {
+      if(c <= 2)
+        return true;
+    }
+  }
+
+  return false;
+}
 
 } // namespace grk

src/lib/core/tile_processor/TileProcessor.h

@@ -288,6 +288,8 @@ struct TileProcessor : virtual public ITileProcessor
    */
   bool needsMctDecompress(void) override;
 
+  bool shouldDecodeComponent(uint16_t compno) override;
+
   /**
    * @brief gets @ref Mct
    *