viewinline 0.2.1__tar.gz → 0.2.3__tar.gz

viewinline-0.2.1/README.md → viewinline-0.2.3/PKG-INFO

@@ -1,3 +1,36 @@
+Metadata-Version: 2.4
+Name: viewinline
+Version: 0.2.3
+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
+Project-URL: Issues, https://github.com/nkeikon/viewinline/issues
+Author: Keiko Nomura
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: geopandas
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pillow
+Requires-Dist: pyogrio
+Requires-Dist: rasterio
+Provides-Extra: all
+Requires-Dist: duckdb; extra == 'all'
+Requires-Dist: h5py; extra == 'all'
+Requires-Dist: netcdf4; extra == 'all'
+Requires-Dist: pyarrow; extra == 'all'
+Provides-Extra: hdf5
+Requires-Dist: h5py; extra == 'hdf5'
+Provides-Extra: netcdf
+Requires-Dist: netcdf4; extra == 'netcdf'
+Provides-Extra: parquet
+Requires-Dist: pyarrow; extra == 'parquet'
+Provides-Extra: sql
+Requires-Dist: duckdb; extra == 'sql'
+Description-Content-Type: text/markdown
+
 # viewinline
 [![Downloads](https://static.pepy.tech/badge/viewinline)](https://pepy.tech/project/viewinline)
 [![PyPI version](https://img.shields.io/pypi/v/viewinline)](https://pypi.org/project/viewinline/)
@@ -6,13 +39,18 @@
 **Quick-look geospatial viewer for compatible terminals.**  
 Displays rasters, vectors, and tabular data directly in the terminal with no GUI and no temporary files.
 
+<p align="center">
+  <a href="viewinline_gif1.gif"><img src="viewinline_gif1.gif" width="49%"></a>
+  <a href="viewinline_gif2.gif"><img src="viewinline_gif2.gif" width="49%"></a>
+</p>
+
 Think of it as `ls` for geospatial files — designed for quick visual inspection at the command line, not a replacement for QGIS, ArcGIS, or analytical workflows.
 
 Particularly useful on HPC systems and remote servers accessed via SSH. Images render on your local terminal without X11 forwarding, VNC, or file downloads.
 
 This tool combines the core display logic of `viewtif` and `viewgeom`, but is **non-interactive**: you can't zoom, pan, or switch colormaps on the fly. Instead, you control everything through command-line options (e.g. --display, --color-by, --colormap).
 
-It uses the iTerm2 inline image protocol (OSC 1337) to render previews. In incompatible terminals, the escape codes are silently ignored with no errors or crashes.
+It uses the iTerm2 inline image protocol (OSC 1337) in supported terminals, and falls back to `chafa` in others, which displays real high-res images in terminals like kitty and Ghostty, and colored block-art (ASCII art) previews in Terminal.app, VS Code, and most Linux terminals. Without `chafa` installed, non-iTerm2-family terminals show an info message instead.
 
 ## Installation  
 Requires Python 3.9 or later.  
@@ -58,18 +96,32 @@ viewinline data.geoparquet --table --where "POP > 100000" --sort POP --desc
 
 ## Compatible terminals
 
-The iTerm2 inline image protocol (OSC 1337) is supported by:
+Native (no extra install required): images render via the iTerm2 inline image protocol on:
 
 - **iTerm2** (macOS)
 - **WezTerm** (cross-platform)
 - **Konsole** (Linux/KDE)
 - **Rio**, **Contour** (cross-platform)
 
-**Not compatible:** Mac Terminal, GNOME Terminal, Kitty (uses different protocol), Ghostty, Alacritty
+Via `chafa` (recommended for everyone else): install chafa and viewinline works in nearly every terminal:
+- kitty, Ghostty, foot — real high-resolution images via the kitty graphics protocol or sixel
+- Terminal.app, VS Code, GNOME Terminal, Alacritty, Warp, Hyper — colored block-art previews with 24-bit color
+
+Install chafa once (it's a system binary, available across all conda/virtualenv environments):
+
+```
+brew install chafa          # macOS
+sudo apt install chafa      # Debian/Ubuntu
+sudo dnf install chafa      # Fedora
+```
+Without chafa, terminals outside the native list above show an info message instead of an image.
+You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGINE=chafa`.
 
 **SSH/HPC usage:** Works over SSH when connecting from a compatible terminal. Images render on your local machine, not the remote server. No X11 forwarding or VNC required.
 
-**tmux/screen:** Inline images don't work inside tmux or screen sessions, even with `allow-passthrough on`. Use a plain terminal tab.
+**tmux/screen:** Inline images work inside tmux only when the outer terminal is iTerm2 (or WezTerm/Konsole/Rio/Contour). In tmux with other outer terminals (kitty, Terminal.app, etc.), viewinline displays ASCII art previews instead of full-quality images.
+
+**Fallback:** In terminals that do not support inline images, you can fallback to ASCII art by installing [`chafa`](https://hpjansson.org/chafa/) command-line tool. Install `chafa` with your package manager (e.g. `brew install chafa` or `sudo apt install chafa`). You can also force the use of `chafa` by setting the environment variable `INLINE_VIEWER_ENGINE=chafa`.
 
 ## Features  
 - Previews rasters, vectors, and tabular data directly in the terminal  
@@ -130,6 +182,7 @@ The iTerm2 inline image protocol (OSC 1337) is supported by:
 - `numpy`, `pandas` — data handling
 
 **Optional dependencies:**
+- `chafa` — strongly recommended for terminal coverage beyond iTerm2/WezTerm/Konsole/Rio/Contour. System binary, not a Python package. See "Terminal support" above for install instructions.
 - `duckdb` — required for `--where`, `--sort`, `--sql`, `--limit` with filtering
   ```bash
   pip install duckdb
@@ -188,11 +241,7 @@ CSV and Parquet:
 ```
 
 ## Need help?
-You can ask questions about usage via the documentation-based assistant:
-
-👉 [Ask the viewtif + viewgeom + viewinline Helper](https://chatgpt.com/g/g-698b61c42f788191b884aed1b99dfcd8-viewtif-viewgeom-viewinline-helper)
-
-👉 For NASA staff: find 'viewtif + viewgeom + viewinline Helper' via the ChatGSFC Agent Marketplace
+NASA staff can ask questions about usage via the documentation-based assistant 'viewtif + viewgeom + viewinline Helper' via the ChatGSFC Agent Marketplace.
 
 ## License
 This project is released under the Apache License 2.0 © 2026 Keiko Nomura.

viewinline-0.2.1/PKG-INFO → viewinline-0.2.3/README.md

@@ -1,33 +1,3 @@
-Metadata-Version: 2.4
-Name: viewinline
-Version: 0.2.1
-Summary: Quick look geospatial viewer for iTerm2 compatible terminals
-Project-URL: Homepage, https://github.com/nkeikon/viewinline
-Project-URL: Repository, https://github.com/nkeikon/viewinline
-Project-URL: Issues, https://github.com/nkeikon/viewinline/issues
-Author: Keiko Nomura
-License: Apache-2.0
-License-File: LICENSE
-Requires-Python: >=3.9
-Requires-Dist: geopandas
-Requires-Dist: matplotlib
-Requires-Dist: numpy
-Requires-Dist: pandas
-Requires-Dist: pillow
-Requires-Dist: pyogrio
-Requires-Dist: rasterio
-Provides-Extra: all
-Requires-Dist: duckdb; extra == 'all'
-Requires-Dist: h5py; extra == 'all'
-Requires-Dist: pyarrow; extra == 'all'
-Provides-Extra: hdf5
-Requires-Dist: h5py; extra == 'hdf5'
-Provides-Extra: parquet
-Requires-Dist: pyarrow; extra == 'parquet'
-Provides-Extra: sql
-Requires-Dist: duckdb; extra == 'sql'
-Description-Content-Type: text/markdown
-
 # viewinline
 [![Downloads](https://static.pepy.tech/badge/viewinline)](https://pepy.tech/project/viewinline)
 [![PyPI version](https://img.shields.io/pypi/v/viewinline)](https://pypi.org/project/viewinline/)
@@ -36,13 +6,18 @@ Description-Content-Type: text/markdown
 **Quick-look geospatial viewer for compatible terminals.**  
 Displays rasters, vectors, and tabular data directly in the terminal with no GUI and no temporary files.
 
+<p align="center">
+  <a href="viewinline_gif1.gif"><img src="viewinline_gif1.gif" width="49%"></a>
+  <a href="viewinline_gif2.gif"><img src="viewinline_gif2.gif" width="49%"></a>
+</p>
+
 Think of it as `ls` for geospatial files — designed for quick visual inspection at the command line, not a replacement for QGIS, ArcGIS, or analytical workflows.
 
 Particularly useful on HPC systems and remote servers accessed via SSH. Images render on your local terminal without X11 forwarding, VNC, or file downloads.
 
 This tool combines the core display logic of `viewtif` and `viewgeom`, but is **non-interactive**: you can't zoom, pan, or switch colormaps on the fly. Instead, you control everything through command-line options (e.g. --display, --color-by, --colormap).
 
-It uses the iTerm2 inline image protocol (OSC 1337) to render previews. In incompatible terminals, the escape codes are silently ignored with no errors or crashes.
+It uses the iTerm2 inline image protocol (OSC 1337) in supported terminals, and falls back to `chafa` in others, which displays real high-res images in terminals like kitty and Ghostty, and colored block-art (ASCII art) previews in Terminal.app, VS Code, and most Linux terminals. Without `chafa` installed, non-iTerm2-family terminals show an info message instead.
 
 ## Installation  
 Requires Python 3.9 or later.  
@@ -88,18 +63,32 @@ viewinline data.geoparquet --table --where "POP > 100000" --sort POP --desc
 
 ## Compatible terminals
 
-The iTerm2 inline image protocol (OSC 1337) is supported by:
+Native (no extra install required): images render via the iTerm2 inline image protocol on:
 
 - **iTerm2** (macOS)
 - **WezTerm** (cross-platform)
 - **Konsole** (Linux/KDE)
 - **Rio**, **Contour** (cross-platform)
 
-**Not compatible:** Mac Terminal, GNOME Terminal, Kitty (uses different protocol), Ghostty, Alacritty
+Via `chafa` (recommended for everyone else): install chafa and viewinline works in nearly every terminal:
+- kitty, Ghostty, foot — real high-resolution images via the kitty graphics protocol or sixel
+- Terminal.app, VS Code, GNOME Terminal, Alacritty, Warp, Hyper — colored block-art previews with 24-bit color
+
+Install chafa once (it's a system binary, available across all conda/virtualenv environments):
+
+```
+brew install chafa          # macOS
+sudo apt install chafa      # Debian/Ubuntu
+sudo dnf install chafa      # Fedora
+```
+Without chafa, terminals outside the native list above show an info message instead of an image.
+You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGINE=chafa`.
 
 **SSH/HPC usage:** Works over SSH when connecting from a compatible terminal. Images render on your local machine, not the remote server. No X11 forwarding or VNC required.
 
-**tmux/screen:** Inline images don't work inside tmux or screen sessions, even with `allow-passthrough on`. Use a plain terminal tab.
+**tmux/screen:** Inline images work inside tmux only when the outer terminal is iTerm2 (or WezTerm/Konsole/Rio/Contour). In tmux with other outer terminals (kitty, Terminal.app, etc.), viewinline displays ASCII art previews instead of full-quality images.
+
+**Fallback:** In terminals that do not support inline images, you can fallback to ASCII art by installing [`chafa`](https://hpjansson.org/chafa/) command-line tool. Install `chafa` with your package manager (e.g. `brew install chafa` or `sudo apt install chafa`). You can also force the use of `chafa` by setting the environment variable `INLINE_VIEWER_ENGINE=chafa`.
 
 ## Features  
 - Previews rasters, vectors, and tabular data directly in the terminal  
@@ -160,6 +149,7 @@ The iTerm2 inline image protocol (OSC 1337) is supported by:
 - `numpy`, `pandas` — data handling
 
 **Optional dependencies:**
+- `chafa` — strongly recommended for terminal coverage beyond iTerm2/WezTerm/Konsole/Rio/Contour. System binary, not a Python package. See "Terminal support" above for install instructions.
 - `duckdb` — required for `--where`, `--sort`, `--sql`, `--limit` with filtering
   ```bash
   pip install duckdb
@@ -218,11 +208,7 @@ CSV and Parquet:
 ```
 
 ## Need help?
-You can ask questions about usage via the documentation-based assistant:
-
-👉 [Ask the viewtif + viewgeom + viewinline Helper](https://chatgpt.com/g/g-698b61c42f788191b884aed1b99dfcd8-viewtif-viewgeom-viewinline-helper)
-
-👉 For NASA staff: find 'viewtif + viewgeom + viewinline Helper' via the ChatGSFC Agent Marketplace
+NASA staff can ask questions about usage via the documentation-based assistant 'viewtif + viewgeom + viewinline Helper' via the ChatGSFC Agent Marketplace.
 
 ## License
 This project is released under the Apache License 2.0 © 2026 Keiko Nomura.

{viewinline-0.2.1 → viewinline-0.2.3}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viewinline"
-version = "0.2.1"
-description = "Quick look geospatial viewer for iTerm2 compatible terminals"
+version = "0.2.3"
+description = "Quick look geospatial viewer for the terminal, with inline image previews"
 readme = "README.md"
 license = { text = "Apache-2.0" }
 authors = [
@@ -22,12 +22,12 @@ dependencies = [
   "pyogrio",
   "pandas"
 ]
-
 [project.optional-dependencies]
 sql = ["duckdb"]
 parquet = ["pyarrow"]
 hdf5 = ["h5py"]
-all = ["duckdb", "pyarrow", "h5py"]
+netcdf = ["netCDF4"]
+all = ["duckdb", "pyarrow", "h5py", "netCDF4"]
 
 [project.scripts]
 viewinline = "viewinline.viewinline:main"

{viewinline-0.2.1 → viewinline-0.2.3}/src/viewinline/viewinline.py

@@ -26,13 +26,14 @@ import pandas as pd
 from PIL import Image, ImageOps, ImageDraw, ImageFont
 from matplotlib import colormaps
 import matplotlib as mpl
+import subprocess
 
 import warnings
 
 warnings.filterwarnings("ignore", message="More than one layer found", category=UserWarning)
 warnings.filterwarnings("ignore", message="Dataset has no geotransform", category=UserWarning)
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 AVAILABLE_COLORMAPS = [
     "viridis", "inferno", "magma", "plasma",
@@ -40,6 +41,119 @@ AVAILABLE_COLORMAPS = [
     "Spectral", "cubehelix", "tab10", "turbo"
 ]
 
+# Terminals that don't natively support the iTerm2 OSC 1337 inline image
+# protocol. Output for these is routed through chafa instead.
+#
+# Note: presence in this list does NOT mean "no images." Chafa auto-detects
+# the terminal and picks the best output:
+#   - kitty (xterm-kitty) → real images via kitty graphics protocol
+#   - some others (e.g. foot, Ghostty) → may render real images via sixel
+#     or kitty protocol depending on chafa's detection
+#   - most others → Unicode block-art preview with 24-bit color
+#     (Terminal.app, VS Code, GNOME Terminal, Alacritty, Warp, etc.)
+# Only terminals without chafa installed see no rendering at all.
+
+_TERMINALS_WITHOUT_IMAGES = [
+    # macOS
+    'Apple_Terminal',         # $TERM_PROGRAM for Terminal.app
+
+    # kitty (renders real images via chafa → kitty graphics protocol)
+    'xterm-kitty',            # $TERM in kitty
+
+    # tmux / screen (TERM strings; $TMUX env var also signals tmux)
+    'screen', 'screen-256color',
+    'tmux', 'tmux-256color',
+
+    # Editors / IDE terminals
+    'vscode',                 # $TERM_PROGRAM in VS Code integrated terminal
+
+    # Cross-platform terminals known not to support OSC 1337
+    'alacritty',
+    'foot',                   # supports sixel → chafa renders real images
+    'ghostty', 'xterm-ghostty',
+    'WarpTerminal',           # $TERM_PROGRAM in Warp
+    'Hyper',                  # $TERM_PROGRAM in Hyper
+
+    # Generic / legacy
+    'unknown',
+    'cygwin',
+    'rxvt', 'rxvt-unicode', 'rxvt-unicode-256color',
+    'st-256color',            # suckless st
+
+    # Linux desktop terminals (most are VTE-based, no OSC 1337)
+    'gnome-terminal',
+    'xfce4-terminal',
+    'lxterminal',
+    'terminator',
+    'tilix',
+    'sakura',
+    'terminology',
+    'guake',
+    'tilda',
+    'deepin-terminal',
+    'eterm',
+
+    # Windows
+    'putty',
+    'Windows Terminal',
+]
+
+def detect_terminal() -> dict[str, str]:
+    """Detect terminal emulator by checking environment variables and parent process.
+    Returns a dictionary of detected terminal-related variables.
+    """
+    env = os.environ
+    terms = {}
+    # Check for common terminal-specific variables
+    for var in [
+        "TERM_PROGRAM", "KONSOLE_VERSION", "KONSOLE_PROFILE_NAME",
+        "VTE_VERSION", "TERMINATOR_UUID", "ALACRITTY_SOCKET",
+        "WEZTERM_EXECUTABLE", "ITERM_SESSION_ID"
+    ]:
+        if var in env:
+            term = env[var]
+            if term:
+                terms[var] = term
+    # Fallback: check parent process
+    if not terms:
+        try:
+            ppid = os.getppid()
+            parent = subprocess.check_output(["ps", "-p", str(ppid), "-o", "comm="]).decode().strip()
+            if parent:
+                terms["PARENT_PROCESS"] = parent
+        except Exception:
+            pass
+    term = env.get("TERM")
+    if term:
+        terms["TERM"] = term
+    return terms
+
+def is_terminal_without_images(term_info: dict[str, str]) -> bool:
+    """Determine if the terminal is likely to support inline images based on detected info.
+    Args:
+        term_info: Dictionary of terminal-related environment variables.
+    Returns:
+        True if terminal is likely supported, False if known to be unsupported.
+    """
+    if os.environ.get("INLINE_VIEWER_ENGINE") == "chafa":
+        return True
+    terms = term_info.values()
+    for unsupported in _TERMINALS_WITHOUT_IMAGES:
+        if unsupported in terms:
+            return True
+    return False
+
+def is_chafa_available() -> bool:
+    """Check if the 'chafa' command-line tool is available for ASCII art fallback."""
+    try:
+        subprocess.run(["chafa", "--version"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        return True
+    except FileNotFoundError:
+        return False
+
+_TERMINAL_INFO = detect_terminal()
+_TERMINAL_SUPPORTS_IMAGES = not is_terminal_without_images(_TERMINAL_INFO)
+
 # ---------------------------------------------------------------------
 # Display utilities
 # ---------------------------------------------------------------------
@@ -52,7 +166,8 @@ def show_inline_image(image_array: np.ndarray, display_scale = None, is_vector:
     buffer = BytesIO()
     # Use lower compression level for performance in speed
     Image.fromarray(image_array).save(buffer, format="PNG", compress_level=1, optimize=False)
-    encoded = base64.b64encode(buffer.getvalue()).decode("utf-8")
+    image_bytes = buffer.getvalue()
+    encoded = base64.b64encode(image_bytes).decode("utf-8")
 
     if display_scale is None:
         width_pct = 33  # same default for both
@@ -67,31 +182,60 @@ def show_inline_image(image_array: np.ndarray, display_scale = None, is_vector:
     # Clamp range
     width_pct = max(5, min(width_pct, 400))
 
-    sys.stdout.write(f"\033]1337;File=inline=1;width={width_pct}%:{encoded}\a\n")
+    if _TERMINAL_SUPPORTS_IMAGES:
+        sys.stdout.write(f"\033]1337;File=inline=1;width={width_pct}%:{encoded}\a\n")
+    else:
+        # if is_chafa_available():
+        #     chafa_output = subprocess.check_output(
+        #         ["chafa", "-"],  
+        #         input=image_bytes
+        #     ).decode()
+            
+        #     sys.stdout.write(f"\n{chafa_output}\a\n")
+        if is_chafa_available():
+            # Inside tmux, force chafa to use block-art symbols instead of
+            # graphics protocols. Tmux mangles kitty graphics and sixel
+            # protocols, producing dot-character garbage on screen. Block-art
+            # passes through tmux reliably on every outer terminal.
+            chafa_args = ["chafa", "-"]
+            if os.environ.get("TMUX"):
+                chafa_args = ["chafa", "-f", "symbols", "-"]
+            chafa_output = subprocess.check_output(
+                chafa_args,
+                input=image_bytes
+            ).decode()
+            
+            sys.stdout.write(f"\n{chafa_output}\a\n")
+            
+        else:
+            sys.stdout.write(f"[INFO] Use supported terminal or install 'chafa' for ascii art fallback. Detected: {_TERMINAL_INFO}\n")
+    
     sys.stdout.flush()
 
-
-def show_image_auto(img: np.ndarray, display_scale = None, is_vector: bool = False) -> None:
-    """Attempt inline image display. No fallbacks, no detection.
+def show_image_auto(img: np.ndarray, display_scale=None, is_vector: bool = False) -> None:
+    """Render an image inline, with chafa fallback for non-iTerm2 terminals.
     
-    Just sends the iTerm2 inline image escape sequence. If the terminal supports it,
-    great. If not, the escape codes are ignored and nothing happens.
+    Cascade:
+      1. If terminal supports OSC 1337 → emit iTerm2 inline image sequence.
+      2. Else if chafa is installed → pipe through chafa (which auto-detects
+         and emits the terminal's native graphics protocol or block-art).
+      3. Else → print an info message suggesting chafa installation.
     
+    The branching happens inside show_inline_image(); this wrapper handles
+    status messaging and exception safety.
     """
-    if os.environ.get("TMUX"):
-        print("[WARN] Inside tmux — inline images won't display even with allow-passthrough on (known iTerm2/tmux issue). Use a plain terminal tab.")
-        return
-    
     try:
         show_inline_image(img, display_scale, is_vector)
-        print("[VIEW] Image sent — visible in compatible terminals")
+        if _TERMINAL_SUPPORTS_IMAGES:
+            print("[VIEW] Image rendered")
+        elif is_chafa_available():
+            print("[VIEW] Rendered via chafa")
+        # If neither path applies, show_inline_image already printed the info message
     except Exception as e:
-        # If image encoding fails, print error but don't crash
-        print(f"[ERROR] Failed to encode image: {e}")
+        print(f"[ERROR] Failed to render image: {e}")
         import traceback
         traceback.print_exc()
 
-
 def resize_to_terminal(img: np.ndarray) -> tuple[np.ndarray, float]:
     """Resize image to fit terminal window (approx 8x16 pixel cells)."""
     cols, rows = shutil.get_terminal_size((100, 40))
@@ -515,6 +659,7 @@ def render_raster(paths: list[str], args) -> None:
             # Handle NetCDF/HDF with subdatasets
             if path.lower().endswith(('.nc', '.hdf', '.hdf5', '.h5')):
                 try:
+                
                     with rasterio.open(path) as src:
                         subdatasets = src.subdatasets