viewinline 0.4.0__tar.gz → 0.5.0__tar.gz

{viewinline-0.4.0 → viewinline-0.5.0}/CITATION.cff

@@ -11,26 +11,27 @@ type: software
 authors:
   - given-names: Keiko
     family-names: Nomura
-    # orcid: "https://orcid.org/0000-0000-0000-0000"   # optional: add if you have one
+    orcid: "https://orcid.org/0000-0002-5218-3414"   
   - given-names: Filip
     family-names: Kral
-    # orcid: "https://orcid.org/0000-0000-0000-0000"   # optional: add if you have one
+  - given-names: Luis
+    family-names: Manrique Ruiz
 repository-code: "https://github.com/nkeikon/inlineviewer"
 url: "https://github.com/nkeikon/inlineviewer"
 license: Apache-2.0
-version: 0.3.2
-date-released: 2026-06-06
+version: 0.5.0
+date-released: 2026-10-21
 # ---------------------------------------------------------------------------
 # The DOI below is the VERSION DOI for v0.3.2 (a specific archived snapshot).
 # To make citations always resolve to your LATEST release, replace it with the
 # Zenodo CONCEPT / "all versions" DOI, shown on the record under "Cite all
 # versions". The version DOI stays useful in `identifiers` for reproducibility.
 # ---------------------------------------------------------------------------
-doi: "10.5281/zenodo.20564266"
+doi: "10.5281/zenodo.19700943"
 identifiers:
   - type: doi
-    value: "10.5281/zenodo.20564266"
-    description: "Zenodo archive of version v0.3.2"
+    value: "10.5281/zenodo.19700943"
+    description: "Zenodo archive"
 keywords:
   - geospatial
   - raster

{viewinline-0.4.0 → viewinline-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: viewinline
-Version: 0.4.0
+Version: 0.5.0
 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
@@ -86,6 +86,12 @@ viewinline path/to/file.tif --export out.png   # save the rendered image as PNG
 viewinline scene.tif --rgb 4 3 2 --export rgb.png
 viewinline dem.tif --colormap terrain --display 1 --export dem.png   # full-res with colormap
 
+# Axis and grid overlay
+viewinline path/to/file.tif --grid           # ticks + grid in the raster's CRS units (5 divisions)
+viewinline path/to/file.tif --grid 10        # 10 divisions instead of the default 5
+viewinline boundaries.geoparquet --grid      # ticks + grid in the vector's CRS units
+viewinline photo.png --grid                  # pixel positions (no CRS)
+
 # CSV and Parquet
 viewinline data.csv                          # preview rows and columns
 viewinline data.parquet --describe           # summary statistics
@@ -222,6 +228,7 @@ General:
   --display DISPLAY     Resize only the displayed image (0.5=smaller, 2=bigger). Default: auto-fit to terminal.
   --info                Print file metadata and statistics as JSON, then exit (agent-facing). For NetCDF/HDF, lists variables; combine with --subset N to inspect one. Always returns JSON, including on error.
   --export PATH         Save the rendered image to PATH (.png/.jpg) and open it. Works with any display flag. Prints {"path": "..."} as the final line.
+  --grid [N]            Overlay axis ticks and a light grid (N divisions, default 5). Labels are in the file's CRS units (degrees or metres) for georeferenced rasters and vectors; pixel positions for PNG/JPG, NetCDF, and non-georeferenced files.
 
 Raster:
   --band BAND           Band number to display (single raster), or slice number for NetCDF. (default: 1)

{viewinline-0.4.0 → viewinline-0.5.0}/README.md

@@ -53,6 +53,12 @@ viewinline path/to/file.tif --export out.png   # save the rendered image as PNG
 viewinline scene.tif --rgb 4 3 2 --export rgb.png
 viewinline dem.tif --colormap terrain --display 1 --export dem.png   # full-res with colormap
 
+# Axis and grid overlay
+viewinline path/to/file.tif --grid           # ticks + grid in the raster's CRS units (5 divisions)
+viewinline path/to/file.tif --grid 10        # 10 divisions instead of the default 5
+viewinline boundaries.geoparquet --grid      # ticks + grid in the vector's CRS units
+viewinline photo.png --grid                  # pixel positions (no CRS)
+
 # CSV and Parquet
 viewinline data.csv                          # preview rows and columns
 viewinline data.parquet --describe           # summary statistics
@@ -189,6 +195,7 @@ General:
   --display DISPLAY     Resize only the displayed image (0.5=smaller, 2=bigger). Default: auto-fit to terminal.
   --info                Print file metadata and statistics as JSON, then exit (agent-facing). For NetCDF/HDF, lists variables; combine with --subset N to inspect one. Always returns JSON, including on error.
   --export PATH         Save the rendered image to PATH (.png/.jpg) and open it. Works with any display flag. Prints {"path": "..."} as the final line.
+  --grid [N]            Overlay axis ticks and a light grid (N divisions, default 5). Labels are in the file's CRS units (degrees or metres) for georeferenced rasters and vectors; pixel positions for PNG/JPG, NetCDF, and non-georeferenced files.
 
 Raster:
   --band BAND           Band number to display (single raster), or slice number for NetCDF. (default: 1)

{viewinline-0.4.0 → viewinline-0.5.0}/llms.txt

@@ -7,7 +7,7 @@
 - Command name: `viewinline`
 - Requires: Python 3.9+
 - License: Apache-2.0 © 2026 Keiko Nomura
-- Latest release: v0.4.0 (2026-06-06)
+- Latest release: v0.5.0 (2026-10-21)
 - Combines the core display logic of `viewtif` and `viewgeom`, but is **non-interactive**: no zoom/pan/colormap-switching on the fly. Everything is controlled via CLI options (e.g. `--display`, `--color-by`, `--colormap`).
 
 ## Installation
@@ -136,6 +136,8 @@ General:
 - `--display DISPLAY` — resize only the displayed image (0.5 = smaller, 2 = bigger). Default: auto-fit to terminal.
 - `--info` — print file metadata as JSON, then exit (no image drawn). Works with rasters (GeoTIFF, NetCDF, HDF) and vectors (GeoJSON, Shapefile, GeoPackage, GeoParquet). For NetCDF/HDF, lists variables; combine with `--subset N` to inspect one. Always returns JSON, including a `{"readable": false, "error": ...}` object on unreadable input. Aimed at AI coding agents.
 - `--export PATH` — save the rendered image to PATH (`.png`/`.jpg`, chosen by extension) and open it; prints `{"path": "..."}` as the final line. Works with any display flag (`--rgb`, `--colormap`, `--band`, `--display`), saving exactly what viewinline would render. Useful for saving quick-looks and for AI agents inspecting outputs visually.
+- `--grid [N]` — overlay axis ticks and a light grid (N divisions, default 5). Labels are in the file's CRS units (degrees or metres) for georeferenced rasters and vectors; pixel positions for PNG/JPG, NetCDF, and non-georeferenced files. Works with `--export`.
+
 Raster:
 - `--band BAND` — band number for a 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`).
@@ -236,6 +238,7 @@ Optional: `chafa` (terminal coverage; system binary), `duckdb` (filter/sort/SQL)
 - **v0.2.0 (2026-02-17):** Inline-only display (OSC 1337); removed ANSI fallback and /tmp save; DuckDB integration for `--where`/`--sort`/`--select`/`--limit`/`--sql`; license switched MIT → Apache-2.0.
 - **v0.1.5 (2026-02-13):** Fixed duplicate band-display prints; optimized uint8 normalization; minor perf.
 - **v0.4.0 (2026-08-23):** New agent-facing inspection commands: `--info` (file metadata + statistics as JSON, for rasters and vectors; lists variables for NetCDF/HDF with `--subset`; always returns JSON including structured errors) and `--export` (save the rendered image to PNG/JPEG, works with any display flag). Existing viewer behavior unchanged.
+- **v0.5.0 (2026-10-21):** New `--grid [N]` flag: axis ticks and a light grid overlay. Georeferenced rasters and vectors are labelled in real CRS coordinates; photos, NetCDF, and non-georeferenced files in pixel positions. Grid contributed by @luismanriqueruiz.
 
 ## Support & links
 

{viewinline-0.4.0 → viewinline-0.5.0}/pyproject.toml

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

{viewinline-0.4.0 → viewinline-0.5.0}/src/viewinline/viewinline.py

@@ -35,7 +35,7 @@ warnings.filterwarnings("ignore", message="invalid scale_factor or add_offset at
 _EXPORT_PATH = None
 _EXPORT_RESULT = None
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 AVAILABLE_COLORMAPS = [
     "viridis", "inferno", "magma", "plasma",
@@ -923,6 +923,123 @@ def normalize_to_uint8(band: np.ndarray, vmin=None, vmax=None, nodata=None) -> n
     return (band * 255).astype(np.uint8)
 
 
+# def add_axis_and_grid(img: np.ndarray, n_ticks: int = 5) -> np.ndarray:
+#     """Overlay pixel-coordinate axis ticks/labels and a light grid on an image.
+
+#     Operates on the final (already resized) array, right before display, so
+#     ticks reflect the pixel coordinates of the rendered image, not the
+#     source raster. Grid lines are alpha-blended so image content stays
+#     visible; ticks/labels live in an added margin along the left and
+#     bottom edges.
+#     """
+#     h, w = img.shape[:2]
+#     n_ticks = max(1, n_ticks)
+
+#     base = Image.fromarray(img).convert("RGBA")
+#     overlay = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+#     odraw = ImageDraw.Draw(overlay)
+#     grid_color = (255, 255, 255, 110)
+
+#     xs = [min(int(round(i * w / n_ticks)), w - 1) for i in range(n_ticks + 1)]
+#     ys = [min(int(round(i * h / n_ticks)), h - 1) for i in range(n_ticks + 1)]
+
+#     for x in xs:
+#         odraw.line([(x, 0), (x, h - 1)], fill=grid_color, width=1)
+#     for y in ys:
+#         odraw.line([(0, y), (w - 1, y)], fill=grid_color, width=1)
+
+#     composed = Image.alpha_composite(base, overlay).convert("RGB")
+
+#     margin_l, margin_b, margin_r = 42, 22, 30
+#     canvas = Image.new("RGB", (w + margin_l + margin_r, h + margin_b), (24, 24, 24))
+#     canvas.paste(composed, (margin_l, 0))
+#     draw = ImageDraw.Draw(canvas)
+
+#     try:
+#         font = ImageFont.load_default()
+#     except Exception:
+#         font = None
+
+#     label_color = (255, 255, 0)
+
+#     for x in xs:
+#         px = margin_l + x
+#         draw.line([(px, h), (px, h + 3)], fill=label_color)
+#         draw.text((px + 2, h + 4), str(x), fill=label_color, font=font)
+
+#     for y in ys:
+#         label = str(y)
+#         tw = draw.textlength(label, font=font) if font else len(label) * 6
+#         draw.line([(margin_l - 3, y), (margin_l, y)], fill=label_color)
+#         draw.text((margin_l - 6 - tw, max(0, y - 5)), label, fill=label_color, font=font)
+
+#     return np.array(canvas)
+
+def add_axis_and_grid(img: np.ndarray, n_ticks: int = 5, bounds=None) -> np.ndarray:
+    """Overlay axis ticks/labels and a light grid on an image.
+
+    If ``bounds`` (left, bottom, right, top) is given, labels show real map
+    coordinates in the raster's CRS. Otherwise they show pixel positions of
+    the rendered image (used for plain photos and non-georeferenced files).
+    """
+    h, w = img.shape[:2]
+    n_ticks = max(1, n_ticks)
+    fracs = [i / n_ticks for i in range(n_ticks + 1)]
+
+    xs = [min(int(round(f * w)), w - 1) for f in fracs]
+    ys = [min(int(round(f * h)), h - 1) for f in fracs]
+
+    if bounds is not None:
+        left, bottom, right, top = bounds
+        step = max(abs(right - left), abs(top - bottom)) / n_ticks
+        # Enough decimals to tell neighbouring ticks apart (0 for metres, ~2-4 for degrees)
+        decimals = 0 if step >= 10 else max(0, int(-np.floor(np.log10(step))) + 1)
+        x_labels = [f"{left + f * (right - left):.{decimals}f}" for f in fracs]
+        y_labels = [f"{top - f * (top - bottom):.{decimals}f}" for f in fracs]
+    else:
+        x_labels = [str(x) for x in xs]
+        y_labels = [str(y) for y in ys]
+
+    base = Image.fromarray(img).convert("RGBA")
+    overlay = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+    odraw = ImageDraw.Draw(overlay)
+    grid_color = (255, 255, 255, 110)
+    for x in xs:
+        odraw.line([(x, 0), (x, h - 1)], fill=grid_color, width=1)
+    for y in ys:
+        odraw.line([(0, y), (w - 1, y)], fill=grid_color, width=1)
+    composed = Image.alpha_composite(base, overlay).convert("RGB")
+
+    try:
+        font = ImageFont.load_default()
+    except Exception:
+        font = None
+    probe = ImageDraw.Draw(Image.new("RGB", (1, 1)))
+
+    def text_w(s):
+        return probe.textlength(s, font=font) if font else len(s) * 6
+
+    # Margins sized to the longest labels so nothing gets clipped
+    margin_l = int(max(text_w(s) for s in y_labels)) + 10
+    margin_r = int(text_w(x_labels[-1])) + 6
+    margin_b = 22
+
+    canvas = Image.new("RGB", (w + margin_l + margin_r, h + margin_b), (24, 24, 24))
+    canvas.paste(composed, (margin_l, 0))
+    draw = ImageDraw.Draw(canvas)
+    label_color = (255, 255, 0)
+
+    for x, label in zip(xs, x_labels):
+        px = margin_l + x
+        draw.line([(px, h), (px, h + 3)], fill=label_color)
+        draw.text((px + 2, h + 4), label, fill=label_color, font=font)
+
+    for y, label in zip(ys, y_labels):
+        draw.line([(margin_l - 3, y), (margin_l, y)], fill=label_color)
+        draw.text((margin_l - 6 - text_w(label), max(0, y - 5)), label, fill=label_color, font=font)
+
+    return np.array(canvas)
+
 def render_simple_image(filepath: str, args) -> None:
     """Render a simple PNG/JPG image using PIL (no geospatial processing)."""
     try:
@@ -945,7 +1062,10 @@ def render_simple_image(filepath: str, args) -> None:
         else:
             img_array, scale = resize_to_terminal(img_array)
             print(f"[VIEW] Rendered image size → {img_array.shape[1]}×{img_array.shape[0]}px (size={scale:.2f})")
-        
+
+        if getattr(args, "grid", None):
+            img_array = add_axis_and_grid(img_array, n_ticks=args.grid)
+
         show_image_auto(img_array, getattr(args, "display", None), is_vector=False)
         
     except Exception as e:
@@ -1102,6 +1222,8 @@ def render_netcdf_via_netcdf4(path, args):
                         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))
+                if getattr(args, "grid", None):
+                    img = add_axis_and_grid(img, n_ticks=args.grid)
                 show_image_auto(img, getattr(args, "display", None), is_vector=False)
                 return
             except ValueError as e:
@@ -1177,8 +1299,11 @@ def render_netcdf_via_netcdf4(path, args):
             # (matches the width_pct logic in show_inline_image)
                 display_pct = args.display if args.display is not None else 0.33
             
-                print(f"[VIEW] Rendered image size → {img.shape[1]}×{img.shape[0]}px (size={display_pct:.2f})")  
-       
+                print(f"[VIEW] Rendered image size → {img.shape[1]}×{img.shape[0]}px (size={display_pct:.2f})")
+
+    if getattr(args, "grid", None):
+        img = add_axis_and_grid(img, n_ticks=args.grid)
+
     show_image_auto(img, getattr(args, "display", None), is_vector=False)
 
 def render_raster(paths: list[str], args) -> None:
@@ -1255,6 +1380,7 @@ def render_raster(paths: list[str], args) -> None:
             # Continue with normal raster opening
             with rasterio.open(path) as ds:
                 H, W = ds.height, ds.width
+                grid_bounds = tuple(ds.bounds) if ds.crs is not None else None 
                 print(f"[DATA] Raster loaded: {os.path.basename(paths[0])} ({W}×{H})")
                 band_count = ds.count
                 
@@ -1372,6 +1498,7 @@ def render_raster(paths: list[str], args) -> None:
             for p in paths:
                 with rasterio.open(p) as ds:
                     bands.append(ds.read(1))
+                    grid_bounds = tuple(ds.bounds) if ds.crs is not None else None
             shapes = {b.shape for b in bands}
             if len(shapes) != 1:
                 print("[ERROR] Raster sizes do not match.")
@@ -1396,6 +1523,10 @@ def render_raster(paths: list[str], args) -> None:
             img, scale = resize_to_terminal(img)
             print(f"[VIEW] Rendered image size → {img.shape[1]}×{img.shape[0]}px (size={scale:.2f})")
 
+        if getattr(args, "grid", None):
+            # img = add_axis_and_grid(img, n_ticks=args.grid)
+            img = add_axis_and_grid(img, n_ticks=args.grid, bounds=grid_bounds)
+
         # Use unified display
         show_image_auto(img, getattr(args, "display", None), is_vector=False)
 
@@ -1648,7 +1779,18 @@ def render_vector(path, args):
     # Figure setup
     fig, ax = plt.subplots(figsize=(6, 6), dpi=150, facecolor="gray")
     ax.set_facecolor("gray")
-    ax.set_axis_off()
+    show_grid = getattr(args, "grid", None)
+    if show_grid:
+        # Keep axis on: real coordinate ticks (CRS units) plus a light grid,
+        # instead of the pixel-based overlay used for raster images.
+        ax.tick_params(colors="white", labelsize=6)
+        for spine in ax.spines.values():
+            spine.set_color("white")
+        ax.locator_params(nbins=show_grid)
+        ax.grid(True, color="white", alpha=0.3, linewidth=0.5)
+        ax.ticklabel_format(style="plain", useOffset=False)
+    else:
+        ax.set_axis_off()
 
     # Determine colormap
     column = args.color_by if args.color_by in gdf.columns else None
@@ -1965,6 +2107,10 @@ def main() -> None:
     
     general.add_argument("--export", metavar="PATH", default=None,
     help="Also save the displayed image to PATH (.png/.jpg). Prints {\"path\": ...}.")
+    general.add_argument(
+        "--grid", nargs="?", type=int, const=5, default=None, metavar="N",
+        help="Overlay coordinate axis ticks and a light grid on the image (N divisions, default 5)."
+    )
 
     # Raster options
     raster = parser.add_argument_group("Raster")

{viewinline-0.4.0 → viewinline-0.5.0/viewinline}/SKILL.md

@@ -62,6 +62,7 @@ Note: `--info` and `--export` report what a file *is* and what it *looks like*
 **Inspection (JSON output, no image):**
 - `--info` — print metadata + statistics as JSON, then exit (rasters and vectors; lists variables for NetCDF/HDF with `--subset N`)
 - `--export PATH` — save the rendered image to PATH (`.png`/`.jpg`); prints `{"path": "..."}`
+- `--grid [N]` — overlay axis ticks and a light grid (N divisions, default 5). Labels are in the file's CRS units for georeferenced rasters and vectors, pixel positions otherwise. Combine with `--export` to save a quick-look with readable coordinates, e.g. to check a file covers the expected area.
 
 **Raster Display:**
 - `--rgb R G B` — Specify band order for RGB (e.g., `--rgb 4 3 2`)