viewinline 0.3.0__tar.gz → 0.3.2__tar.gz

{viewinline-0.3.0 → viewinline-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: viewinline
-Version: 0.3.0
+Version: 0.3.2
 Summary: Quick look geospatial viewer for the terminal, with inline image previews
 Project-URL: Homepage, https://github.com/nkeikon/viewinline
 Project-URL: Repository, https://github.com/nkeikon/viewinline
@@ -64,9 +64,9 @@ pip install viewinline
 # Rasters
 viewinline path/to/file.tif
 viewinline R.tif G.tif B.tif                 # RGB composite (also works with --rgbfiles)
-viewinline hyperspectral.nc --band 50
 viewinline path/to/multiband.tif --rgb 3 2 1
-viewinline path/to/folder --gallery 4x3      # show image gallery (e.g. 4x3 grid)
+viewinline path/to/folder --gallery 4x3      # show image gallery of all files in the folder (e.g. 4x3 grid)
+viewinline path/to/hyperspectral.tif --bands 10-50 # show image gallery of selected bands (also works with --bands 11,15,30,45; --gallery 5x5)
 
 # NetCDF and HDF
 viewinline file.nc                           # list variables
@@ -74,6 +74,8 @@ viewinline file.nc --subset 2                # display variable 2
 viewinline file.nc --subset 1 --band 10      # variable 1, timestep 10 --band or --timestep
 viewinline temp.nc --subset 1 --colormap plasma --vmin 273 --vmax 310
 viewinline hyperspectral.nc --subset 1 --reduce NumberOfScanlines  # override auto-detected axis
+viewinline hyperspectral.nc --subset 22 --band 50 # show image gallery of selected bands
+viewinline hyperspectral.nc --subset 22 --bands 10-54 --gallery 5x11
 
 # Vectors
 viewinline path/to/vector.geojson
@@ -169,6 +171,7 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 
 **Gallery view**
 - Display all images in a folder with `--gallery 4x4`
+- Display selected bands of a single raster as a grid with `--bands 101-120` or `--bands 11,12,45,55`. Works with GeoTIFF and NetCDF files.
 
 **NetCDF/HDF notes:**
 - viewinline lists only variables that can be displayed as 2D or 3D arrays
@@ -213,12 +216,13 @@ General:
 
 Raster:
   --band BAND           Band number to display (single raster), or slice number for NetCDF. (default: 1)
+  --bands BANDS         Display multiple bands as a grid. Accepts ranges (30-40), lists (3,4,5), or mixed (1,5,10-15).
+  --rgb R G B           Three band numbers for RGB display (e.g., --rgb 4 3 2). Overrides default 1 2 3.
+  --rgbfiles R G B      Three single-band rasters for RGB composite. Can also provide as positional arguments.
   --timestep INTEGER    Alias for --band when working with NetCDF files.
   --subset INTEGER      Variable index for NetCDF/HDF files (e.g., --subset 1).
   --reduce DIM_NAME     For 3D NetCDF variables, specify which dimension to use as the band/slider axis.  Auto-detected if omitted.
   --colormap            Apply colormap to single-band rasters. Flag without the color scheme → 'terrain'.
-  --rgb R G B           Three band numbers for RGB display (e.g., --rgb 4 3 2). Overrides default 1 2 3.
-  --rgbfiles R G B      Three single-band rasters for RGB composite. Can also provide as positional arguments.
   --vmin VMIN           Minimum pixel value for raster display scaling.
   --vmax VMAX           Maximum pixel value for raster display scaling.
   --nodata NODATA       Override nodata value for rasters if dataset metadata is missing or incorrect.

{viewinline-0.3.0 → viewinline-0.3.2}/README.md

@@ -31,9 +31,9 @@ pip install viewinline
 # Rasters
 viewinline path/to/file.tif
 viewinline R.tif G.tif B.tif                 # RGB composite (also works with --rgbfiles)
-viewinline hyperspectral.nc --band 50
 viewinline path/to/multiband.tif --rgb 3 2 1
-viewinline path/to/folder --gallery 4x3      # show image gallery (e.g. 4x3 grid)
+viewinline path/to/folder --gallery 4x3      # show image gallery of all files in the folder (e.g. 4x3 grid)
+viewinline path/to/hyperspectral.tif --bands 10-50 # show image gallery of selected bands (also works with --bands 11,15,30,45; --gallery 5x5)
 
 # NetCDF and HDF
 viewinline file.nc                           # list variables
@@ -41,6 +41,8 @@ viewinline file.nc --subset 2                # display variable 2
 viewinline file.nc --subset 1 --band 10      # variable 1, timestep 10 --band or --timestep
 viewinline temp.nc --subset 1 --colormap plasma --vmin 273 --vmax 310
 viewinline hyperspectral.nc --subset 1 --reduce NumberOfScanlines  # override auto-detected axis
+viewinline hyperspectral.nc --subset 22 --band 50 # show image gallery of selected bands
+viewinline hyperspectral.nc --subset 22 --bands 10-54 --gallery 5x11
 
 # Vectors
 viewinline path/to/vector.geojson
@@ -136,6 +138,7 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 
 **Gallery view**
 - Display all images in a folder with `--gallery 4x4`
+- Display selected bands of a single raster as a grid with `--bands 101-120` or `--bands 11,12,45,55`. Works with GeoTIFF and NetCDF files.
 
 **NetCDF/HDF notes:**
 - viewinline lists only variables that can be displayed as 2D or 3D arrays
@@ -180,12 +183,13 @@ General:
 
 Raster:
   --band BAND           Band number to display (single raster), or slice number for NetCDF. (default: 1)
+  --bands BANDS         Display multiple bands as a grid. Accepts ranges (30-40), lists (3,4,5), or mixed (1,5,10-15).
+  --rgb R G B           Three band numbers for RGB display (e.g., --rgb 4 3 2). Overrides default 1 2 3.
+  --rgbfiles R G B      Three single-band rasters for RGB composite. Can also provide as positional arguments.
   --timestep INTEGER    Alias for --band when working with NetCDF files.
   --subset INTEGER      Variable index for NetCDF/HDF files (e.g., --subset 1).
   --reduce DIM_NAME     For 3D NetCDF variables, specify which dimension to use as the band/slider axis.  Auto-detected if omitted.
   --colormap            Apply colormap to single-band rasters. Flag without the color scheme → 'terrain'.
-  --rgb R G B           Three band numbers for RGB display (e.g., --rgb 4 3 2). Overrides default 1 2 3.
-  --rgbfiles R G B      Three single-band rasters for RGB composite. Can also provide as positional arguments.
   --vmin VMIN           Minimum pixel value for raster display scaling.
   --vmax VMAX           Maximum pixel value for raster display scaling.
   --nodata NODATA       Override nodata value for rasters if dataset metadata is missing or incorrect.

{viewinline-0.3.0 → viewinline-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viewinline"
-version = "0.3.0"
+version = "0.3.2"
 description = "Quick look geospatial viewer for the terminal, with inline image previews"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{viewinline-0.3.0 → viewinline-0.3.2}/src/viewinline/viewinline.py

@@ -9,14 +9,11 @@ Supports:
 
 Display:
   Sends iTerm2-style inline image escape sequences. Works in terminals that support
-  the iTerm2 inline image protocol (iTerm2, WezTerm, Konsole, etc.). In other
-  terminals, the escape codes are ignored.
+  the iTerm2 inline image protocol (iTerm2, WezTerm, Konsole, etc.). For others,
+  please see line 48-58. 
   
   Particularly useful on HPC systems and remote servers accessed via SSH — images
   render on your local terminal without X11 forwarding, VNC, or file downloads.
-  
-  No detection, no fallbacks. If images are not shown, it means that the terminal 
-  is not compatible.
 """
 
 import sys, os, base64, shutil, argparse
@@ -28,19 +25,13 @@ from matplotlib import colormaps
 import matplotlib as mpl
 import subprocess
 
-try:
-    import netCDF4
-    HAS_NETCDF4 = True
-except ImportError:
-    HAS_NETCDF4 = False
-
 import warnings
 
 warnings.filterwarnings("ignore", message="More than one layer found", category=UserWarning)
 warnings.filterwarnings("ignore", message="Dataset has no geotransform", category=UserWarning)
 warnings.filterwarnings("ignore", message="invalid scale_factor or add_offset attribute", category=UserWarning)
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 AVAILABLE_COLORMAPS = [
     "viridis", "inferno", "magma", "plasma",
@@ -248,6 +239,41 @@ def resize_to_terminal(img: np.ndarray) -> tuple[np.ndarray, float]:
     pil_img = ImageOps.contain(pil_img, (new_w, new_h))
     return np.array(pil_img), scale
 
+def parse_bands(s: str) -> list[int]:
+    """Parse --bands argument: accepts ranges (30-40), lists (3,4,5), or mixed (1,3,10-15)."""
+    bands = []
+    for part in s.split(","):
+        part = part.strip()
+        if "-" in part:
+            try:
+                start, end = map(int, part.split("-", 1))
+                bands.extend(range(start, end + 1))
+            except ValueError:
+                print(f"[WARN] Could not parse band range: {part}")
+        else:
+            try:
+                bands.append(int(part))
+            except ValueError:
+                print(f"[WARN] Could not parse band: {part}")
+    return sorted(set(bands))
+
+def parse_rgb(values: list[str]) -> list[int]:
+    """Parse --rgb: accepts '4 3 2' or '4,3,2'."""
+    if len(values) == 1:
+        # comma-separated: '4,3,2'
+        parts = values[0].split(",")
+    else:
+        # space-separated: '4' '3' '2'
+        parts = values
+    try:
+        result = [int(p.strip()) for p in parts]
+        if len(result) != 3:
+            raise ValueError
+        return result
+    except ValueError:
+        print("[WARN] --rgb requires exactly 3 band numbers. e.g. --rgb 4 3 2 or --rgb 4,3,2")
+        return None
+    
 # ---------------------------------------------------------------------
 # CSV handling
 # ---------------------------------------------------------------------
@@ -286,11 +312,18 @@ def preview_df(df, max_rows: int = 10, query_mode: bool = False, filename: str =
     # -------------------------------------------------------------
     if n_rows <= max_rows:
         rows_to_show = df
+    elif query_mode:
+        ans = input(f"Filtered results: {n_rows} rows. Show first {max_rows} or all? [first/all]: ").strip().lower()
+        if ans == "all":
+            rows_to_show = df
+        else:
+            rows_to_show = df.head(max_rows)
     else:
-        ans = input(f"Preview first {max_rows} rows? [y/N]: ").strip().lower()
-        if ans not in ("y", "yes"):
-            return
-        rows_to_show = df.head(max_rows)
+        ans = input(f"Large file: {n_rows} rows. Show first {max_rows} or all? [first/all]: ").strip().lower()
+        if ans == "all":
+            rows_to_show = df
+        else:
+            rows_to_show = df.head(max_rows)        
 
     # -------------------------------------------------------------
     # Build pretty table
@@ -592,8 +625,15 @@ def normalize_to_uint8(band: np.ndarray, vmin=None, vmax=None, nodata=None) -> n
     valid_vals = band[valid]
 
     # --- Manual scaling ---
-    if vmin is not None and vmax is not None:
-        mn, mx = vmin, vmax
+    if vmin is not None or vmax is not None:
+        # Use percentile for whichever end is not specified
+        if valid_vals.size < 1_000_000:
+            sample = valid_vals
+        else:
+            sample = np.random.choice(valid_vals, 1_000_000, replace=False)
+        p2, p98 = np.percentile(sample, (2, 98))
+        mn = vmin if vmin is not None else p2
+        mx = vmax if vmax is not None else p98
         print(f"[VIEW] Using manual scaling: {mn} to {mx}")
 
     # --- Percentile fallback ---
@@ -646,7 +686,9 @@ def render_netcdf_via_netcdf4(path, args):
     """Read a NetCDF file via netCDF4 (bypassing GDAL). Handles hierarchical
     groups and hyperspectral cubes where GDAL aborts or interprets axes wrong.
     """
-    if not HAS_NETCDF4:
+    try:
+        import netCDF4
+    except ImportError:
         print("[ERROR] netCDF4 not installed. Install with:")
         print("        pip install netCDF4")
         print("        or:  pip install viewinline[netcdf]")
@@ -737,6 +779,66 @@ def render_netcdf_via_netcdf4(path, args):
         band_count = var.shape[spectral_axis]
         band_num = args.band if args.band is not None else 1
         band_idx = max(0, min(band_num - 1, band_count - 1))
+
+        # BANDS GALLERY for NetCDF
+        if getattr(args, "bands", None):
+            band_list = parse_bands(args.bands)
+            # print(f"[DEBUG] band_count={band_count}, band_list={band_list}")
+            valid_bands = [b for b in band_list if 1 <= b <= band_count]
+            if not valid_bands:
+                print(f"[ERROR] No valid bands. Variable has {band_count} bands along '{var.dimensions[spectral_axis]}'.")
+                nc.close()
+                return
+            slices = []
+            for b in valid_bands:
+                slicer = [slice(None)] * 3
+                slicer[spectral_axis] = b - 1
+                slices.append(np.asarray(var[tuple(slicer)], dtype=np.float64))
+            nc.close()
+            colormap = args.colormap if args.colormap else "viridis"
+            render_bands_gallery(np.stack(slices, axis=0), valid_bands, band_count,
+                                 grid=getattr(args, "gallery", None),
+                                 display_scale=getattr(args, "display", None),
+                                 colormap=colormap)
+            return
+
+        # RGB COMPOSITE for NetCDF
+        if getattr(args, "rgb", None):
+            try:
+                # rgb_bands = args.rgb
+                rgb_bands = parse_rgb(args.rgb)
+                if rgb_bands is None:
+                    return
+                if len(rgb_bands) != 3:
+                    raise ValueError("exactly 3 bands required")
+                slices = []
+                for b in rgb_bands:
+                    if b < 1 or b > band_count:
+                        raise ValueError(f"band {b} out of range (1-{band_count})")
+                    slicer = [slice(None)] * 3
+                    slicer[spectral_axis] = b - 1
+                    slices.append(np.asarray(var[tuple(slicer)], dtype=np.float64))
+                nc.close()
+                print(f"[INFO] Using RGB bands: {rgb_bands}")
+                img = np.stack([normalize_to_uint8(s, vmin=args.vmin, vmax=args.vmax, nodata=args.nodata)
+                                for s in slices], axis=-1)
+                H, W = img.shape[:2]
+                if args.display:
+                    new_w = max(1, int(W * args.display))
+                    new_h = max(1, int(H * args.display))
+                    img = np.array(Image.fromarray(img).resize((new_w, new_h), Image.BILINEAR))
+                else:
+                    max_dim = 2000
+                    if max(H, W) > max_dim:
+                        scale = max_dim / max(H, W)
+                        new_w, new_h = int(W * scale), int(H * scale)
+                        img = np.array(Image.fromarray(img).resize((new_w, new_h), Image.BILINEAR))
+                show_image_auto(img, getattr(args, "display", None), is_vector=False)
+                return
+            except ValueError as e:
+                print(f"[WARN] Invalid --rgb: {e}. Falling back to band 1.")
+
+        # Single band slicer
         slicer = [slice(None)] * 3
         slicer[spectral_axis] = band_idx
         data = np.asarray(var[tuple(slicer)], dtype=np.float64)
@@ -793,9 +895,6 @@ def render_netcdf_via_netcdf4(path, args):
         new_w, new_h = max(1, int(W * args.display)), max(1, int(H * args.display))
         img = np.array(Image.fromarray(img).resize((new_w, new_h), Image.BILINEAR))
         print(f"[VIEW] Manual resize ×{args.display:.2f} → {new_w}×{new_h}px")
-    # else:
-    #     img, scale = resize_to_terminal(img)
-    #     print(f"[VIEW] Rendered image size → {img.shape[1]}×{img.shape[0]}px (size={scale:.2f})")
     else:
             max_dim = 2000
             if max(img.shape[:2]) > max_dim:
@@ -803,7 +902,7 @@ def render_netcdf_via_netcdf4(path, args):
                 new_w = int(img.shape[1] * scale)
                 new_h = int(img.shape[0] * scale)
                 img = np.array(Image.fromarray(img).resize((new_w, new_h), Image.BILINEAR))
-                print(f"[VIEW] Downsampled from {W}×{H}px to {new_w}×{new_h}px (scale={scale:.2f})")
+                print(f"[VIEW] Downsampled from {W}×{H}px to {new_w}×{new_h}px (display scale={scale:.2f})")
                 print(f"[INFO] Use --display 1 for full resolution.")
             else:
             # (matches the width_pct logic in show_inline_image)
@@ -907,7 +1006,8 @@ def render_raster(paths: list[str], args) -> None:
                         resampling=rasterio.enums.Resampling.bilinear
                     )
 
-                    print(f"[VIEW] Downsampled for preview → {out_w}×{out_h}px (scale={scale:.3f})")
+                    print(f"[VIEW] Downsampled for preview → {out_w}×{out_h}px (display scale={scale:.3f})")
+                    print(f"[INFO] Use --display 1 for full resolution.")
                 else:
                     data = ds.read()
 
@@ -918,22 +1018,27 @@ def render_raster(paths: list[str], args) -> None:
                 else:
                     print(f"[INFO] Multi-band raster detected ({band_count} bands)")
 
-            # MULTI BAND RGB (skip for NetCDF - treat as slices/timesteps, not RGB)
-            # if band_count >= 3 and not paths[0].lower().endswith('.nc'):
-            # Auto-composite to RGB only when user didn't explicitly ask for a single band
-            # user_specified_band = args.band is not None and args.band != 1
+            # BANDS GALLERY
+            if getattr(args, "bands", None):
+                band_list = parse_bands(args.bands)
+                colormap = args.colormap if args.colormap else "viridis"
+                render_bands_gallery(data, band_list, band_count,
+                                    grid=getattr(args, "gallery", None),
+                                    display_scale=getattr(args, "display", None),
+                                    colormap=colormap)
+                return
+
             user_specified_band = args.band is not None
-            if band_count >= 3 and not paths[0].lower().endswith('.nc') and not user_specified_band:
+            if band_count >= 3 and not paths[0].lower().endswith('.nc') and not user_specified_band and getattr(args, 'rgb', None):
 
                 if getattr(args, "rgb", None):
-                    try:
-                        rgb_idx = [b - 1 for b in args.rgb]
-                        if len(rgb_idx) != 3:
-                            raise ValueError
-                        print(f"[INFO] Using RGB bands: {args.rgb}")
-                    except Exception:
+                    rgb_parsed = parse_rgb(args.rgb)
+                    if rgb_parsed is None:
                         print("[WARN] Invalid --rgb. Using default 1 2 3")
                         rgb_idx = [0, 1, 2]
+                    else:
+                        rgb_idx = [b - 1 for b in rgb_parsed]
+                        print(f"[INFO] Using RGB bands: {rgb_parsed}")
                 else:
                     rgb_idx = [0, 1, 2]
 
@@ -1045,26 +1150,30 @@ def render_gallery(folder: str, grid: str = "4x4", display_scale=None, is_vector
             cols, rows = 4, 4
         nmax = cols * rows
 
-        # Collect files
-        exts = (".png", ".jpg", ".jpeg", ".tif", ".tiff")
+        # Collect all files, let the loader decide what's valid
         files = [os.path.join(folder, f) for f in sorted(os.listdir(folder))
-                 if f.lower().endswith(exts)]
+                 if os.path.isfile(os.path.join(folder, f))]
         if not files:
-            print(f"[WARN] No image/raster files found in {folder}")
+            print(f"[WARN] No files found in {folder}")
             return
 
         files = files[:nmax]
 
         # Load thumbnails
         thumbs = []
+        loaded_files = []
         thumb_size = (128, 128)
         for f in files:
             try:
                 ext = os.path.splitext(f)[1].lower()
                 if ext in [".tif", ".tiff"]:
                     import rasterio
+                    from rasterio.enums import Resampling
                     with rasterio.open(f) as ds:
-                        arr = ds.read()
+                        arr = ds.read(
+                            out_shape=(ds.count, thumb_size[1], thumb_size[0]),
+                            resampling=Resampling.nearest
+                        )
                         if arr.shape[0] >= 3:
                             rgb = np.stack([normalize_to_uint8(arr[i]) for i in range(3)], axis=-1)
                         else:
@@ -1075,8 +1184,10 @@ def render_gallery(folder: str, grid: str = "4x4", display_scale=None, is_vector
                     img = Image.open(f).convert("RGB")
                 img.thumbnail(thumb_size)
                 thumbs.append(img)
+                loaded_files.append(f)
+
             except Exception as e:
-                print(f"[WARN] Skipped {os.path.basename(f)} ({e})")
+                print(f"[SKIP] {os.path.basename(f)} — {e}")
 
         if not thumbs:
             print("[WARN] No valid images loaded.")
@@ -1099,11 +1210,103 @@ def render_gallery(folder: str, grid: str = "4x4", display_scale=None, is_vector
             canvas.paste(img, (x, y))
 
         print(f"[INFO] Displaying {n} images ({cols}×{rows} grid)")
-        show_image_auto(np.array(canvas), display_scale, is_vector)
 
+        for r in range(rows):
+            row_files = loaded_files[r * cols:(r + 1) * cols]
+            print("  ".join(f"{os.path.basename(f):<20}" for f in row_files))
+
+        show_image_auto(np.array(canvas), display_scale, is_vector)
     except Exception as e:
         print(f"[ERROR] Failed to render gallery: {e}")
 
+def render_bands_gallery(data: np.ndarray, band_list: list[int], band_count: int,
+                          grid: str = None, display_scale=None, colormap: str = "viridis") -> None:
+    """Render multiple bands from a single raster as a grid of thumbnails."""
+    import math
+
+    # Validate bands
+    valid_bands = [b for b in band_list if 1 <= b <= band_count]
+    if not valid_bands:
+        print(f"[ERROR] No valid bands. File has {band_count} bands.")
+        return
+    skipped = set(band_list) - set(valid_bands)
+    if skipped:
+        print(f"[WARN] Skipped out-of-range bands: {sorted(skipped)}")
+
+    n = len(valid_bands)
+
+    # Auto grid or user-specified
+    if grid:
+        try:
+            cols, rows = map(int, grid.lower().split("x"))
+        except Exception:
+            cols = math.ceil(math.sqrt(n))
+            rows = math.ceil(n / cols)
+    else:
+        cols = math.ceil(math.sqrt(n))
+        rows = math.ceil(n / cols)
+
+    # Use fixed longest dimension to preserve aspect ratio
+    max_thumb = 256
+    label_height = 14  # space below each thumbnail for band label
+    margin = 8
+    cmap = colormaps[colormap]
+
+    thumbs = []
+    thumb_w = thumb_h = max_thumb  # will be updated from first image
+
+    for i, b in enumerate(valid_bands):
+        arr = data[i].astype(float)
+        normalized = normalize_to_uint8(arr)
+        colored = cmap(normalized / 255.0)
+        rgb = (colored[:, :, :3] * 255).astype(np.uint8)
+        img = Image.fromarray(rgb)
+        img.thumbnail((max_thumb, max_thumb), Image.LANCZOS)
+        if i == 0:
+            thumb_w, thumb_h = img.size
+        thumbs.append(img)
+
+    # Build canvas with extra height per row for labels
+    cols = min(cols, n)
+    rows = math.ceil(n / cols)
+    cell_w = thumb_w + margin
+    cell_h = thumb_h + label_height + margin
+    canvas_w = cols * cell_w + margin
+    canvas_h = rows * cell_h + margin
+    canvas = Image.new("RGB", (canvas_w, canvas_h), (220, 220, 220))
+    draw = ImageDraw.Draw(canvas)
+    from PIL import ImageFont
+    try:
+        font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 10)
+    except Exception:
+        try:
+            font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 10)
+        except Exception:
+            font = ImageFont.load_default()
+
+    for i, img in enumerate(thumbs):
+        r, c = divmod(i, cols)
+        x = margin + c * cell_w
+        y = margin + r * cell_h
+        canvas.paste(img, (x, y))
+        if _TERMINAL_SUPPORTS_IMAGES:
+            # Draw label on canvas background below the thumbnail
+            label = f"B{valid_bands[i]}"
+            lx = x + (thumb_w - len(label) * 6) // 2
+            ly = y + thumb_h + 2
+            draw.text((lx, ly), label, fill=(0, 0, 0), font=font)
+
+    print(f"[INFO] Displaying {n} bands ({cols}×{rows} grid, colormap: {colormap})")
+    # print(f"[DEBUG] canvas size: {canvas_w}×{canvas_h}px")
+
+    if not _TERMINAL_SUPPORTS_IMAGES:
+        # Print band labels as text grid
+        for r in range(rows):
+            row_bands = valid_bands[r * cols:(r + 1) * cols]
+            print("  ".join(f"B{b:<4}" for b in row_bands))
+
+    show_image_auto(np.array(canvas), display_scale)
+
 # ---------------------------------------------------------------------
 # Vector handling
 # ---------------------------------------------------------------------
@@ -1463,147 +1666,140 @@ def main() -> None:
         formatter_class=SmartDefaults
     )
 
-    # File input
+# File input
     parser.add_argument(
-        "paths", nargs="*",  # Zero or more (optional)
+        "paths", nargs="*",
         help="Path to raster(s), vector, or CSV file. Provide 1 file or exactly 3 rasters for RGB (R G B)."
     )
-    # Display options
-    parser.add_argument(
+
+    # General options
+    general = parser.add_argument_group("General")
+    general.add_argument(
         "--display", type=float, default=None,
         help="Resize only the displayed image (0.5=smaller, 2=bigger). Default: auto-fit to terminal."
     )
+    general.add_argument(
+        "--gallery", nargs="?", const="4x4", metavar="GRID",
+        help="Display all image files in a folder as thumbnails (e.g., --gallery 5x4). Incompatible files are skipped."
+    )
 
     # Raster options
-    parser.add_argument(
+    raster = parser.add_argument_group("Raster")
+    raster.add_argument(
         "--band", type=int, default=None,
-        help="Band number to display (single raster case), or slice number for NetCDF."
+        help="Band number to display (single raster), or slice number for NetCDF. (default: 1)"
     )
-    parser.add_argument(
+    raster.add_argument(
+        "--bands", type=str,
+        help="Display multiple bands as a grid. Accepts ranges (30-40), lists (3,4,5), or mixed (1,3,10-15)."
+    )
+    raster.add_argument(
         "--timestep", type=int, default=None,
-        help="Alias for --band when working with NetCDF files (1-based index)."
+        help="Alias for --band when working with NetCDF files."
     )
-    parser.add_argument(
+    raster.add_argument(
+        "--subset", type=int, default=None,
+        help="Variable index for NetCDF/HDF files (e.g., --subset 1)."
+    )
+    raster.add_argument(
+        "--reduce", dest="reduce_dim", type=str, default=None, metavar="DIM_NAME",
+        help="For 3D NetCDF variables, specify which dimension to use as the band/slider axis. Auto-detected if omitted."
+    )
+    raster.add_argument(
         "--colormap", nargs="?", const="terrain",
         choices=AVAILABLE_COLORMAPS, default=None,
-        help="Apply colormap to single-band rasters or vector coloring. Flag without value → 'terrain'."
+        help="Apply colormap to single-band rasters. Flag without value → 'terrain'."
     )
-    parser.add_argument(
-        "--rgb", nargs=3, type=int, metavar=('R', 'G', 'B'), default=None,
-        help="Three band numbers for RGB display (e.g., --rgb 4 3 2). Overrides default 1 2 3."
+    raster.add_argument(
+        "--rgb", nargs='+', type=str, metavar='BAND', default=None,
+        help="Three band numbers for RGB display (e.g., --rgb 4 3 2 or --rgb 4,3,2). Overrides default 1 2 3."
     )
-    parser.add_argument(
+    raster.add_argument(
         "--rgbfiles", nargs=3, type=str, metavar=('R', 'G', 'B'),
-        help="Three single-band rasters for RGB composite (e.g., --rgbfiles R.tif G.tif B.tif). Can also provide as positional arguments without the flag."
+        help="Three single-band rasters for RGB composite. Can also provide as positional arguments."
     )
-    parser.add_argument(
+    raster.add_argument(
         "--vmin", type=float, default=None,
         help="Minimum pixel value for raster display scaling."
     )
-    parser.add_argument(
+    raster.add_argument(
         "--vmax", type=float, default=None,
         help="Maximum pixel value for raster display scaling."
     )
-    parser.add_argument(
+    raster.add_argument(
         "--nodata", type=float, default=None,
         help="Override nodata value for rasters if dataset metadata is missing or incorrect."
     )
-    parser.add_argument(
-    "--gallery", nargs="?", const="4x4", metavar="GRID",
-    help="Display all PNG/JPG/TIF images in a folder as thumbnails (e.g., 5x5 grid)."
-)
-    parser.add_argument(
-        "--subset", type=int, default=None,
-        help="Variable index for NetCDF files (e.g. --subset 1)."
+
+    # Vector options
+    vector = parser.add_argument_group("Vector")
+    vector.add_argument(
+        "--color-by", type=str, default=None,
+        help="Numeric column to color vector features by."
     )
-    parser.add_argument(
-        "--reduce", dest="reduce_dim", type=str, default=None,
-        metavar="DIM_NAME",
-        help="For 3D NetCDF variables, specify which dimension to use as the band axis (auto-detected if omitted)."
+    vector.add_argument(
+        "--width", type=float, default=0.7,
+        help="Line width for vector boundaries."
+    )
+    vector.add_argument(
+        "--edgecolor", type=str, default="#F6FF00",
+        help="Edge color for vector outlines (hex or named color)."
+    )
+    vector.add_argument(
+        "--layer", type=str, default=None,
+        help="Layer name for GeoPackage/multi-layer files, or variable name for NetCDF files."
+    )
+    vector.add_argument(
+        "--table", action="store_true",
+        help="Display vector/parquet file as tabular data instead of rendering geometry."
     )
 
-    # CSV options
-    parser.add_argument(
-    "--hist",
-    nargs="?",
-    const=True,
-    help="Show histograms for all numeric columns or specify one column name."
+    # Tabular options
+    tabular = parser.add_argument_group("Tabular")
+    tabular.add_argument(
+        "--hist", nargs="?", const=True,
+        help="Show histograms for all numeric columns or specify one column name."
     )
-    parser.add_argument(
-        "--describe",
-        nargs="?",
-        const=True,
+    tabular.add_argument(
+        "--describe", nargs="?", const=True,
         help="Show summary statistics for all numeric columns or specify one column name."
     )
-    parser.add_argument(
-    "--bins", type=int, default=20,
-    help="Number of bins for CSV histograms (used with --hist)."
+    tabular.add_argument(
+        "--bins", type=int, default=20,
+        help="Number of bins for histograms (used with --hist)."
     )
-    parser.add_argument(
-    "--scatter", nargs=2, metavar=("X", "Y"),
-    help="Plot scatter of two numeric CSV columns (e.g. --scatter area_km2 year)."
+    tabular.add_argument(
+        "--scatter", nargs=2, metavar=("X", "Y"),
+        help="Scatter plot of two numeric columns (e.g. --scatter area_km2 year)."
     )
-    parser.add_argument(
-    "--unique",
-    metavar="COLUMN",
-    help="Show unique values for a categorical column and exit"
+    tabular.add_argument(
+        "--unique", metavar="COLUMN",
+        help="Show unique values for a categorical column."
     )
-    parser.add_argument(
-        "--where",
-        type=str,
-        default=None,
-        help="Filter rows using SQL WHERE clause (DuckDB required). Example: --where \"year > 2010\""
+    tabular.add_argument(
+        "--where", type=str, default=None,
+        help="Filter rows using SQL WHERE clause (e.g. --where \"year > 2010\")."
     )
-    parser.add_argument(
-        "--sort",
-        type=str,
-        default=None,
-        help="Sort rows by values in the specified column, ascending by default (e.g. --sort population). Use --desc to reverse."
+    tabular.add_argument(
+        "--sort", type=str, default=None,
+        help="Sort rows by column, ascending by default. Use --desc to reverse."
     )
-    parser.add_argument(
-        "--desc",
-        action="store_true",
+    tabular.add_argument(
+        "--desc", action="store_true",
         help="Sort in descending order."
     )
-    parser.add_argument(
-        "--limit",
-        type=int,
-        default=None,
+    tabular.add_argument(
+        "--limit", type=int, default=None,
         help="Limit number of rows shown (e.g. --limit 100)."
     )
-    parser.add_argument(
-        "--select",
-        nargs="+",
-        help="Select specific columns (space separated) (e.g. --select Country City)"
-    )
-    parser.add_argument(
-        "--sql",
-        type=str,
-        help="Execute full DuckDB SQL query against CSV (advanced mode)."
-    )
-
-    # Vector options
-    parser.add_argument(
-        "--color-by", type=str, default=None,
-        help="Numeric column to color vector features by (optional)."
-    )
-    parser.add_argument(
-    "--width", type=float, default=0.7,
-    help="Line width for vector boundaries"
-    )
-    parser.add_argument(
-        "--edgecolor", type=str, default="#F6FF00",
-        help="Edge color for vector outlines (hex or named color)."
+    tabular.add_argument(
+        "--select", nargs="+",
+        help="Select specific columns (e.g. --select Country City)."
     )
-    parser.add_argument(
-        "--layer", type=str, default=None,
-        # help="Layer name for GeoPackage or multi-layer files."
-        help="Layer name for GeoPackage/multi-layer files, or variable name for NetCDF files."
+    tabular.add_argument(
+        "--sql", type=str,
+        help="Execute full DuckDB SQL query against CSV/parquet (advanced mode)."
     )
-    parser.add_argument(
-    "--table", action="store_true",
-    help="Display vector/parquet file as tabular data instead of rendering geometry."
-    ) 
 
     parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")