add support for header skip option to adjust planar data offset

Author: codengine

AmigaRawImageConverter/Options.cs

@@ -22,6 +22,10 @@ internal class Options
         HelpText = "Require palette footer; if false, use grayscale palette and treat all bytes as planar data.")]
     public bool RequirePalette { get; set; }
 
+    [Option("header-skip", Default = 0,
+        HelpText = "Number of bytes to skip at the start of the file before reading planar data.")]
+    public int HeaderSkip { get; set; }
+
     [Option("min-planes", Default = 3, HelpText = "Minimum bitplane count to evaluate when guessing geometry.")]
     public int MinPlanes { get; set; }
 

AmigaRawImageConverter/Program.cs

@@ -68,23 +68,34 @@ private static int Run(Options opts)
     private static void ConvertOne(string inputPath, string outputPath, Options opts)
     {
         var raw = File.ReadAllBytes(inputPath);
+        if (opts.HeaderSkip < 0)
+        {
+            throw new InvalidOperationException("Header skip cannot be negative.");
+        }
+
+        if (opts.HeaderSkip > raw.Length)
+        {
+            throw new InvalidOperationException("Header skip exceeds file size.");
+        }
+
+        var data = raw.AsSpan(opts.HeaderSkip);
         ReadOnlySpan<byte> planar;
         Rgba32[] palette;
 
         if (opts.RequirePalette)
         {
-            if (raw.Length < PaletteLength)
+            if (data.Length < PaletteLength)
             {
                 throw new InvalidOperationException("File too small to contain palette.");
             }
 
-            var paletteTail = raw.AsSpan(raw.Length - PaletteLength, PaletteLength);
+            var paletteTail = data.Slice(data.Length - PaletteLength, PaletteLength);
             palette = DecodePalette(paletteTail);
-            planar = raw.AsSpan(0, raw.Length - PaletteLength);
+            planar = data[..^PaletteLength];
         }
         else
         {
-            planar = raw;
+            planar = data;
             var maxPlanes = Math.Max(opts.MinPlanes, opts.MaxPlanes);
             var paletteSize = 1 << Math.Max(1, maxPlanes);
             palette = BuildGrayscalePalette(paletteSize);

README.md

@@ -52,6 +52,7 @@ Candidate PNGs are written under the chosen output directory with names based on
 - `-n`, `--max-candidates` (default: 5): How many best geometry candidates to emit per file.
 - `-p`, `--raw-file-pattern` (default: `*.raw`): Filename pattern to match for RAW files when input is a directory.
 - `--require-palette` (default: true): If true, expect a palette footer; if false, use all bytes as planar data and generate a grayscale palette.
+- `--header-skip` (default: 0): Number of bytes to skip at the start of the file before reading planar data.
 - `--min-planes` (default: 3): Minimum bitplane count to evaluate when guessing geometry.
 - `--max-planes` (default: 6): Maximum bitplane count to evaluate when guessing geometry.
 - `--min-width` (default: 64): Minimum image width (pixels) to evaluate when guessing geometry.
@@ -61,7 +62,7 @@ Candidate PNGs are written under the chosen output directory with names based on
 - `--width-increment` (default: 16): Step (pixels) between tested widths when scanning candidates.
 
 ## Notes on geometry detection
-- Defaults to scanning 3–6 bitplanes (common Amiga modes); plane counts that need more palette entries than are present are skipped. With `--require-palette false`, a grayscale palette sized to the maximum plane count is generated.
+- Defaults to scanning 3–6 bitplanes (common Amiga modes); plane counts that need more palette entries than are present are skipped. With `--require-palette false`, a grayscale palette sized to the maximum plane count is generated. `--header-skip` is applied before reading planar data or palettes.
 - By default scans widths from 64 to 640 pixels in steps of 16 (`--min-width`, `--max-width`, `--width-increment`).
 - Width must be divisible by 8 and exactly consume the planar data (given height and plane count) or the candidate is skipped.
 - Scores candidates by row smoothness (mean + stddev of row deltas); lower is better.
@@ -72,7 +73,7 @@ The last 32 bytes are 16 big-endian words, layout `0RRR GGGG BBBB` (4 bits/chann
 each channel is scaled to 0–255 for PNG output.
 
 ## Limitations & gotchas
-- When `--require-palette` is true, expects the palette to be the final 32 bytes; extra non-planar data at the end will confuse detection.
+- When `--require-palette` is true, expects the palette to be the final 32 bytes (after honoring `--header-skip`); extra non-planar data at the end will confuse detection.
 - With autogenerated grayscale palette, bitplane counts requiring more colors than the generated palette size (based on max planes) are ignored.
 - Width/height search ranges are controlled via CLI options; exotic sizes outside the search window will not be considered.
 - Smoothness scoring can still pick a wrong candidate for very noisy or synthetic images—inspect the outputs.