viewinline 0.2.2__tar.gz → 0.2.3__tar.gz

viewinline-0.2.2/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/)
@@ -17,7 +50,7 @@ Particularly useful on HPC systems and remote servers accessed via SSH. Images r
 
 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.  
@@ -63,18 +96,30 @@ 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`.
 
@@ -137,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

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

@@ -1,33 +1,3 @@
-Metadata-Version: 2.4
-Name: viewinline
-Version: 0.2.2
-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/)
@@ -47,7 +17,7 @@ Particularly useful on HPC systems and remote servers accessed via SSH. Images r
 
 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.  
@@ -93,18 +63,30 @@ 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`.
 
@@ -167,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

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

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viewinline"
-version = "0.2.2"
-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.2 → viewinline-0.2.3}/src/viewinline/viewinline.py

@@ -33,7 +33,7 @@ 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.2"
+__version__ = "0.2.3"
 
 AVAILABLE_COLORMAPS = [
     "viridis", "inferno", "magma", "plasma",
@@ -41,12 +41,61 @@ 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 = [
-    'unknown', 'cygwin', 'tmux', 'screen',
-    'vscode', 'xterm', 'rxvt', 'alacritty', 'foot', 'st', 'kitty',
-    'gnome-terminal', 'xfce4-terminal', 'lxterminal', 'terminator',
-    'tilix', 'hyper', 'windows terminal', 'putty', 'sakura',
-    'terminology', 'eterm', 'guake', 'tilda', 'deepin-terminal',
+    # 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]:
@@ -136,40 +185,57 @@ def show_inline_image(image_array: np.ndarray, display_scale = None, is_vector:
     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", "-"],  
+                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))
@@ -593,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