Upload 24 files

app.py

@@ -1,3 +1,19 @@
+import os
+import glob
+import shutil
+import io
+import logging
+import panel as pn
+import xarray as xr
+import numpy as np
+from datetime import datetime
+from types import SimpleNamespace
+from collections import defaultdict
+from ash_animator.converter import NAMEDataProcessor
+from ash_animator.plot_3dfield_data import Plot_3DField_Data
+from ash_animator.plot_horizontal_data import Plot_Horizontal_Data
+from ash_animator import create_grid
+
 import io
 import random
 from typing import List, Tuple
@@ -7,141 +23,867 @@ import panel as pn
 from PIL import Image
 from transformers import CLIPModel, CLIPProcessor
 
-pn.extension(design="bootstrap", sizing_mode="stretch_width")
+pn.extension()
+
+import tempfile
+
+MEDIA_DIR = os.environ.get("NAME_MEDIA_DIR", os.path.join(tempfile.gettempdir(), "name_media"))
+os.makedirs(MEDIA_DIR, exist_ok=True)
+
+# Logging setup
+LOG_FILE = os.path.join(MEDIA_DIR, "app_errors.log")
+logging.basicConfig(filename=LOG_FILE, level=logging.ERROR,
+                    format="%(asctime)s - %(levelname)s - %(message)s")
+
+animator_obj = {}
+
+# ---------------- Widgets ----------------
+file_input = pn.widgets.FileInput(accept=".zip")
+process_button = pn.widgets.Button(name="📦 Process ZIP", button_type="primary")
+reset_button = pn.widgets.Button(name="🔄 Reset App", button_type="danger")
+status = pn.pane.Markdown("### Upload a NAME Model ZIP to begin")
+
+download_button = pn.widgets.FileDownload(
+    label="⬇️ Download All Exports",
+    filename="all_exports.zip",
+    button_type="success",
+    callback=lambda: io.BytesIO(
+        open(shutil.make_archive(
+            os.path.join(MEDIA_DIR, "all_exports").replace(".zip", ""),
+            "zip", MEDIA_DIR
+        ), 'rb').read()
+    )
+)
+
+log_link = pn.widgets.FileDownload(
+    label="🪵 View Error Log", file=LOG_FILE,
+    filename="app_errors.log", button_type="warning"
+)
+
+threshold_slider_3d = pn.widgets.FloatSlider(name='3D Threshold', start=0.0, end=1.0, step=0.05, value=0.1)
+zoom_slider_3d = pn.widgets.IntSlider(name='3D Zoom Level', start=1, end=20, value=19)
+cmap_select_3d = pn.widgets.Select(name='3D Colormap', options=["rainbow", "viridis", "plasma"])
+fps_slider_3d = pn.widgets.IntSlider(name='3D FPS', start=1, end=10, value=2)
+Altitude_slider = pn.widgets.IntSlider(name='Define Ash Altitude', start=1, end=15, value=1)
+
+threshold_slider_2d = pn.widgets.FloatSlider(name='2D Threshold', start=0.0, end=1.0, step=0.01, value=0.005)
+zoom_slider_2d = pn.widgets.IntSlider(name='2D Zoom Level', start=1, end=20, value=19)
+fps_slider_2d = pn.widgets.IntSlider(name='2D FPS', start=1, end=10, value=2)
+cmap_select_2d = pn.widgets.Select(name='2D Colormap', options=["rainbow", "viridis", "plasma"])
+
+# ---------------- Core Functions ----------------
+def process_zip(event=None):
+    if file_input.value:
+        zip_path = os.path.join(MEDIA_DIR, file_input.filename)
+        with open(zip_path, "wb") as f:
+            f.write(file_input.value)
+        status.object = "✅ ZIP uploaded and saved."
+    else:
+        zip_path = os.path.join(MEDIA_DIR, "default_model.zip")
+        if not os.path.exists(zip_path):
+            zip_path = "default_model.zip"  # fallback to local directory
+        if not os.path.exists(zip_path):
+            status.object = "❌ No ZIP uploaded and default_model.zip not found."
+            return
+        status.object = "📦 Using default_model.zip"
+
 
-ICON_URLS = {
-    "brand-github": "https://github.com/holoviz/panel",
-    "brand-twitter": "https://twitter.com/Panel_Org",
-    "brand-linkedin": "https://www.linkedin.com/company/panel-org",
-    "message-circle": "https://discourse.holoviz.org/",
-    "brand-discord": "https://discord.gg/AXRHnJU6sP",
-}
+    try:
+        output_dir = os.path.join("./", "ash_output")
+        os.makedirs(output_dir, exist_ok=True)
+    except PermissionError:
+        output_dir = os.path.join(tempfile.gettempdir(), "name_output")
+        os.makedirs(output_dir, exist_ok=True)
+    shutil.rmtree(output_dir, ignore_errors=True)
+    os.makedirs(output_dir, exist_ok=True)
+
+    try:
+        processor = NAMEDataProcessor(output_root=output_dir)
+        processor.batch_process_zip(zip_path)
 
+        # animator_obj["3d"] = [xr.open_dataset(fp).load()
+        #                       for fp in sorted(glob.glob(os.path.join(output_dir, "3D", "*.nc")))]
+        
+        # animator_obj["3d"] = []
+        # for fp in sorted(glob.glob(os.path.join(output_dir, "3D", "*.nc"))):
+        #     with xr.open_dataset(fp) as ds:
+        #         animator_obj["3d"].append(ds.load())
+        animator_obj["3d"] = []
+        for fp in sorted(glob.glob(os.path.join(output_dir, "3D", "*.nc"))):
+            with xr.open_dataset(fp) as ds:
+                animator_obj["3d"].append(ds.load())
 
-async def random_url(_):
-    pet = random.choice(["cat", "dog"])
-    api_url = f"https://api.the{pet}api.com/v1/images/search"
-    async with aiohttp.ClientSession() as session:
-        async with session.get(api_url) as resp:
-            return (await resp.json())[0]["url"]
+        animator_obj["2d"] = []
+        for fp in sorted(glob.glob(os.path.join(output_dir, "horizontal", "*.nc"))):
+            with xr.open_dataset(fp) as ds:
+                animator_obj["2d"].append(ds.load())
 
+        
+        # animator_obj["2d"] = [xr.open_dataset(fp).load()
+        #                       for fp in sorted(glob.glob(os.path.join(output_dir, "horizontal", "*.nc")))]
 
-@pn.cache
-def load_processor_model(
-    processor_name: str, model_name: str
-) -> Tuple[CLIPProcessor, CLIPModel]:
-    processor = CLIPProcessor.from_pretrained(processor_name)
-    model = CLIPModel.from_pretrained(model_name)
-    return processor, model
+        with open(os.path.join(MEDIA_DIR, "last_run.txt"), "w") as f:
+            f.write(zip_path)
 
+        status.object += f" | ✅ Loaded 3D: {len(animator_obj['3d'])} & 2D: {len(animator_obj['2d'])}"
+        update_media_tabs()
+    except Exception as e:
+        logging.exception("Error during ZIP processing")
+        status.object = f"❌ Processing failed: {e}"
 
-async def open_image_url(image_url: str) -> Image:
-    async with aiohttp.ClientSession() as session:
-        async with session.get(image_url) as resp:
-            return Image.open(io.BytesIO(await resp.read()))
+def reset_app(event=None):
+    animator_obj.clear()
+    file_input.value = None
+    status.object = "🔄 App has been reset."
+    for folder in ["ash_output", "2D", "3D"]:
+        shutil.rmtree(os.path.join(MEDIA_DIR, folder), ignore_errors=True)
+    if os.path.exists(os.path.join(MEDIA_DIR, "last_run.txt")):
+        os.remove(os.path.join(MEDIA_DIR, "last_run.txt"))
+    update_media_tabs()
+
+def restore_previous_session():
+    try:
+        state_file = os.path.join(MEDIA_DIR, "last_run.txt")
+        if os.path.exists(state_file):
+            with open(state_file) as f:
+                zip_path = f.read().strip()
+            if os.path.exists(zip_path):
+                try:
+                    output_dir = os.path.join("./", "ash_output")
+                    os.makedirs(output_dir, exist_ok=True)
+                except PermissionError:
+                    output_dir = os.path.join(tempfile.gettempdir(), "name_output")
+                    os.makedirs(output_dir, exist_ok=True)
 
+                animator_obj["3d"] = []
+                for fp in sorted(glob.glob(os.path.join(output_dir, "3D", "*.nc"))):
+                    with xr.open_dataset(fp) as ds:
+                        animator_obj["3d"].append(ds.load())
 
-def get_similarity_scores(class_items: List[str], image: Image) -> List[float]:
-    processor, model = load_processor_model(
-        "openai/clip-vit-base-patch32", "openai/clip-vit-base-patch32"
+                animator_obj["2d"] = []
+                for fp in sorted(glob.glob(os.path.join(output_dir, "horizontal", "*.nc"))):
+                    with xr.open_dataset(fp) as ds:
+                        animator_obj["2d"].append(ds.load())
+
+                status.object = f"🔁 Restored previous session from {os.path.basename(zip_path)}"
+                update_media_tabs()
+    except Exception as e:
+        logging.exception("Error restoring previous session")
+        status.object = f"⚠️ Could not restore previous session: {e}"
+
+process_button.on_click(process_zip)
+reset_button.on_click(reset_app)
+
+# ---------------- Animator Builders ----------------
+def build_animator_3d():
+    ds = animator_obj["3d"]
+    attrs = ds[0].attrs
+    lons, lats, grid = create_grid(attrs)
+    return SimpleNamespace(
+        datasets=ds,
+        levels=ds[0].altitude.values,
+        lons=lons,
+        lats=lats,
+        lon_grid=grid[0],
+        lat_grid=grid[1],
     )
-    inputs = processor(
-        text=class_items,
-        images=[image],
-        return_tensors="pt",  # pytorch tensors
+
+def build_animator_2d():
+    ds = animator_obj["2d"]
+    lat_grid, lon_grid = xr.broadcast(ds[0]["latitude"], ds[0]["longitude"])
+    return SimpleNamespace(
+        datasets=ds,
+        lats=ds[0]["latitude"].values,
+        lons=ds[0]["longitude"].values,
+        lat_grid=lat_grid.values,
+        lon_grid=lon_grid.values,
     )
-    outputs = model(**inputs)
-    logits_per_image = outputs.logits_per_image
-    class_likelihoods = logits_per_image.softmax(dim=1).detach().numpy()
-    return class_likelihoods[0]
 
+# ---------------- Plot Functions ----------------
+def plot_z_level():
+    try:
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        os.makedirs(out, exist_ok=True)
+        Plot_3DField_Data(animator, out, cmap_select_3d.value,
+                          threshold_slider_3d.value, zoom_slider_3d.value,
+                          fps_slider_3d.value).plot_single_z_level(
+                              Altitude_slider.value, f"ash_altitude{Altitude_slider.value}km_runTimes.gif")
+        update_media_tabs()
+        status.object = "✅ Z-Level animation created."
+    except Exception as e:
+        logging.exception("Error in plot_z_level")
+        status.object = f"❌ Error in Z-Level animation: {e}"
 
-async def process_inputs(class_names: List[str], image_url: str):
-    """
-    High level function that takes in the user inputs and returns the
-    classification results as panel objects.
-    """
+def plot_vertical_profile():
     try:
-        main.disabled = True
-        if not image_url:
-            yield "##### ⚠️ Provide an image URL"
-            return
-    
-        yield "##### ⚙ Fetching image and running model..."
-        try:
-            pil_img = await open_image_url(image_url)
-            img = pn.pane.Image(pil_img, height=400, align="center")
-        except Exception as e:
-            yield f"##### 😔 Something went wrong, please try a different URL!"
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        os.makedirs(out, exist_ok=True)
+        plotter = Plot_3DField_Data(animator, out, cmap_select_3d.value, fps_slider_3d.value,
+                                    threshold_slider_3d.value, zoom_level=zoom_slider_3d.value,
+                                    basemap_type='basemap')
+        plotter.plot_vertical_profile_at_time(Altitude_slider.value - 1,
+                                              filename=f"T{Altitude_slider.value - 1}_profile.gif")
+        update_media_tabs()
+        status.object = "✅ Vertical profile animation created."
+    except Exception as e:
+        logging.exception("Error in plot_vertical_profile")
+        status.object = f"❌ Error in vertical profile animation: {e}"
+
+def animate_all_altitude_profiles():
+    try:
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        Plot_3DField_Data(animator, out, cmap_select_3d.value,
+                          threshold_slider_3d.value, zoom_slider_3d.value).animate_all_altitude_profiles()
+        update_media_tabs()
+        status.object = "✅ All altitude profile animations created."
+    except Exception as e:
+        logging.exception("Error in animate_all_altitude_profiles")
+        status.object = f"❌ Error animating all altitude profiles: {e}"
+
+def export_jpg_frames():
+    try:
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        Plot_3DField_Data(animator, out, cmap_select_3d.value,
+                          threshold_slider_3d.value, zoom_slider_3d.value).export_frames_as_jpgs(include_metadata=True)
+        update_media_tabs()
+        status.object = "✅ JPG frames exported."
+    except Exception as e:
+        logging.exception("Error exporting JPG frames")
+        status.object = f"❌ Error exporting JPG frames: {e}"
+
+def plot_2d_field(field):
+    try:
+        animator = build_animator_2d()
+        out = os.path.join(MEDIA_DIR, "2D")
+        Plot_Horizontal_Data(animator, out, cmap_select_2d.value, fps_slider_2d.value,
+                             include_metadata=True, threshold=threshold_slider_2d.value,
+                             zoom_width_deg=6.0, zoom_height_deg=6.0,
+                             zoom_level=zoom_slider_2d.value,
+                             static_frame_export=True).plot_single_field_over_time(field, f"{field}.gif")
+        update_media_tabs()
+        status.object = f"✅ 2D field `{field}` animation created."
+    except Exception as e:
+        logging.exception(f"Error in plot_2d_field: {field}")
+        status.object = f"❌ Error in 2D field `{field}` animation: {e}"
+
+# ---------------- Layout ----------------
+def human_readable_size(size):
+    for unit in ['B', 'KB', 'MB', 'GB']:
+        if size < 1024: return f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} TB"
+
+# def generate_output_gallery(base_folder):
+#     grouped = defaultdict(lambda: defaultdict(list))
+#     for root, _, files in os.walk(os.path.join(MEDIA_DIR, base_folder)):
+#         for file in files:
+#             ext = os.path.splitext(file)[1].lower()
+#             subfolder = os.path.relpath(root, MEDIA_DIR)
+#             grouped[subfolder][ext].append(os.path.join(root, file))
+
+#     folder_tabs = []
+#     for subfolder, ext_files in sorted(grouped.items()):
+#         type_tabs = []
+#         for ext, paths in sorted(ext_files.items()):
+#             previews = []
+#             for path in sorted(paths, key=os.path.getmtime, reverse=True):
+#                 size = human_readable_size(os.path.getsize(path))
+#                 mod = datetime.fromtimestamp(os.path.getmtime(path)).strftime("%Y-%m-%d %H:%M")
+#                 title = f"**{os.path.basename(path)}**\\n_{size}, {mod}_"
+#                 download = pn.widgets.FileDownload(label="⬇", file=path, filename=os.path.basename(path), width=60)
+#                 if ext in [".gif", ".png", ".jpg", ".jpeg"]:
+#                     preview = pn.pane.Image(path, width=320)
+#                 else:
+#                     with open(path, "r", errors="ignore") as f:
+#                         content = f.read(2048)
+#                     preview = pn.pane.PreText(content, width=320)
+#                 card = pn.Card(pn.pane.Markdown(title), preview, pn.Row(download), width=360)
+#                 previews.append(card)
+#             type_tabs.append((ext.upper(), pn.GridBox(*previews, ncols=2)))
+#         folder_tabs.append((subfolder, pn.Tabs(*type_tabs)))
+#     return pn.Tabs(*folder_tabs)
+
+
+def generate_output_gallery(base_folder):
+    preview_container = pn.Column(width=640, height=550)
+    preview_container.append(pn.pane.Markdown("👈 Click a thumbnail to preview"))
+    folder_cards = []
+
+    def make_preview(file_path):
+        ext = os.path.splitext(file_path)[1].lower()
+        title = pn.pane.Markdown(f"### {os.path.basename(file_path)}")
+        download_button = pn.widgets.FileDownload(file=file_path, filename=os.path.basename(file_path),
+                                                  label="⬇ Download", button_type="success", width=150)
+
+        if ext in [".gif", ".png", ".jpg", ".jpeg"]:
+            content = pn.pane.Image(file_path, width=640, height=450, sizing_mode="fixed")
+        else:
+            try:
+                with open(file_path, 'r', errors="ignore") as f:
+                    text = f.read(2048)
+                content = pn.pane.PreText(text, width=640, height=450)
+            except:
+                content = pn.pane.Markdown("*Unable to preview this file.*")
+
+        return pn.Column(title, content, download_button)
+
+    grouped = defaultdict(list)
+    for root, _, files in os.walk(os.path.join(MEDIA_DIR, base_folder)):
+        for file in sorted(files):
+            full_path = os.path.join(root, file)
+            if not os.path.exists(full_path):
+                continue
+            rel_folder = os.path.relpath(root, os.path.join(MEDIA_DIR, base_folder))
+            grouped[rel_folder].append(full_path)
+
+    for folder, file_paths in sorted(grouped.items()):
+        thumbnails = []
+        for full_path in file_paths:
+            filename = os.path.basename(full_path)
+            ext = os.path.splitext(full_path)[1].lower()
+
+            if ext in [".gif", ".png", ".jpg", ".jpeg"]:
+                img = pn.pane.Image(full_path, width=140, height=100)
+            else:
+                img = pn.pane.Markdown("📄", width=140, height=100)
+
+            view_button = pn.widgets.Button(name="👁", width=40, height=30, button_type="primary")
+
+            def click_handler(path=full_path):
+                def inner_click(event):
+                    preview_container[:] = [make_preview(path)]
+                return inner_click
+
+            view_button.on_click(click_handler())
+
+            overlay = pn.Column(pn.Row(pn.Spacer(width=90), view_button), img, width=160)
+            label_md = pn.pane.Markdown(f"**{filename}**", width=140, height=35)
+            thumb_card = pn.Column(overlay, label_md, width=160)
+            thumbnails.append(thumb_card)
+
+        folder_card = pn.Card(pn.GridBox(*thumbnails, ncols=2), title=f"📁 {folder}", width=400, collapsible=True)
+        folder_cards.append(folder_card)
+
+    folder_scroll = pn.Column(*folder_cards, scroll=True, height=600, width=420)
+    return pn.Row(preview_container, pn.Spacer(width=20), folder_scroll)
+
+def update_media_tabs():
+    media_tab_2d.objects[:] = [generate_output_gallery("2D")]
+    media_tab_3d.objects[:] = [generate_output_gallery("3D")]
+
+media_tab_2d = pn.Column(generate_output_gallery("2D"))
+media_tab_3d = pn.Column(generate_output_gallery("3D"))
+
+media_tab = pn.Tabs(
+    ("2D Outputs", media_tab_2d),
+    ("3D Outputs", media_tab_3d)
+)
+
+
+tab3d = pn.Column(
+    threshold_slider_3d, zoom_slider_3d, fps_slider_3d, Altitude_slider, cmap_select_3d,
+    pn.widgets.Button(name="🎞 Generate animation at selected altitude level", button_type="primary", on_click=lambda e: tab3d.append(plot_z_level())),
+    pn.widgets.Button(name="📈 Generate vertical profile animation at time index", button_type="primary", on_click=lambda e: tab3d.append(plot_vertical_profile())),
+    pn.widgets.Button(name="📊 Generate all altitude level animations", button_type="primary", on_click=lambda e: tab3d.append(animate_all_altitude_profiles())),
+    pn.widgets.Button(name="🖼 Export all animation frames as JPG", button_type="primary", on_click=lambda e: tab3d.append(export_jpg_frames())),
+)
+
+tab2d = pn.Column(
+    threshold_slider_2d, zoom_slider_2d, fps_slider_2d, cmap_select_2d,
+    pn.widgets.Button(name="🌫 Animate Air Concentration", button_type="primary", on_click=lambda e: tab2d.append(plot_2d_field("air_concentration"))),
+    pn.widgets.Button(name="🌧 Animate Dry Deposition Rate", button_type="primary", on_click=lambda e: tab2d.append(plot_2d_field("dry_deposition_rate"))),
+    pn.widgets.Button(name="💧 Animate Wet Deposition Rate", button_type="primary", on_click=lambda e: tab2d.append(plot_2d_field("wet_deposition_rate"))),
+)
+
+help_tab = pn.Column(pn.pane.Markdown("""
+## ❓ How to Use the NAME Ash Visualizer
+
+This dashboard allows users to upload and visualize outputs from the NAME ash dispersion model.
+
+### 🧭 Workflow
+1. **Upload ZIP** containing NetCDF files from the NAME model.
+2. Use **3D and 2D tabs** to configure and generate animations.
+3. Use **Media Viewer** to preview and download results.
+
+### 🧳 ZIP Structure
+```
+## 🗂 How Uploaded ZIP is Processed
+
+```text
+┌────────────────────────────────────────────┐
+│           Uploaded ZIP (.zip)              │
+│  (e.g. Taal_273070_20200112_scenario_*.zip)│
+└────────────────────────────────────────────┘
+                    │
+                    ▼
+      ┌───────────────────────────────┐
+      │ Contains: raw .txt outputs    │
+      │  - AQOutput_3DField_*.txt     │
+      │  - AQOutput_horizontal_*.txt  │
+      └───────────────────────────────┘
+                    │
+                    ▼
+  ┌────────────────────────────────────────┐
+  │   NAMEDataProcessor.batch_process_zip()│
+  └────────────────────────────────────────┘
+                    │
+                    ▼
+      ┌─────────────────────────────┐
+      │   Converts to NetCDF files  │
+      │     - ash_output/3D/*.nc    │
+      │     - ash_output/horizontal/*.nc │
+      └─────────────────────────────┘
+                    │
+                    ▼
+   ┌─────────────────────────────────────┐
+   │ View & animate in 3D/2D tabs        │
+   │ Download results in Media Viewer    │
+   └─────────────────────────────────────┘
+
+```
+
+### 📢 Tips
+- Reset the app with 🔄 if needed.
+- View logs if an error occurs.
+- Outputs are temporary per session.
+""", sizing_mode="stretch_width"))
+
+tabs = pn.Tabs(
+    ("🧱 3D Field", tab3d),
+    ("🌍 2D Field", tab2d),
+    ("📁 Media Viewer", media_tab),
+    ("❓ Help", help_tab)
+)
+
+sidebar = pn.Column(
+    pn.pane.Markdown("## 🌋 NAME Ash Visualizer", sizing_mode="stretch_width"),
+    pn.Card(pn.Column(file_input, process_button, reset_button, sizing_mode="stretch_width"),
+            title="📂 File Upload & Processing", collapsible=True, sizing_mode="stretch_width"),
+    pn.Card(pn.Column(download_button, log_link, sizing_mode="stretch_width"),
+            title="📁 Downloads & Logs", collapsible=True, sizing_mode="stretch_width"),
+    pn.Card(status, title="📢 Status", collapsible=True, sizing_mode="stretch_width"),
+    sizing_mode="stretch_width")
+
+restore_previous_session()
+
+pn.template.FastListTemplate(
+    title="NAME Visualizer Dashboard",
+    sidebar=sidebar,
+    main=[tabs],
+).servable()
+
+''' 
+import os
+import glob
+import shutil
+import io
+import logging
+import panel as pn
+import xarray as xr
+import numpy as np
+from datetime import datetime
+from types import SimpleNamespace
+from collections import defaultdict
+from ash_animator.converter import NAMEDataProcessor
+from ash_animator.plot_3dfield_data import Plot_3DField_Data
+from ash_animator.plot_horizontal_data import Plot_Horizontal_Data
+from ash_animator import create_grid
+import tempfile
+
+pn.extension()
+
+MEDIA_DIR = os.environ.get("NAME_MEDIA_DIR", os.path.join(tempfile.gettempdir(), "name_media"))
+os.makedirs(MEDIA_DIR, exist_ok=True)
+
+LOG_FILE = os.path.join(MEDIA_DIR, "app_errors.log")
+logging.basicConfig(filename=LOG_FILE, level=logging.ERROR, format="%(asctime)s - %(levelname)s - %(message)s")
+
+animator_obj = {}
+
+file_input = pn.widgets.FileInput(accept=".zip")
+process_button = pn.widgets.Button(name="📦 Process ZIP", button_type="primary")
+reset_button = pn.widgets.Button(name="🔄 Reset App", button_type="danger")
+status = pn.pane.Markdown("### Upload a NAME Model ZIP to begin")
+
+download_button = pn.widgets.FileDownload(
+    label="⬇️ Download All Exports", filename="all_exports.zip", button_type="success",
+    callback=lambda: io.BytesIO(open(shutil.make_archive(os.path.join(MEDIA_DIR, "all_exports").replace(".zip", ""), "zip", MEDIA_DIR), 'rb').read())
+)
+
+log_link = pn.widgets.FileDownload(label="🪵 View Error Log", file=LOG_FILE, filename="app_errors.log", button_type="warning")
+
+threshold_slider_3d = pn.widgets.FloatSlider(name='3D Threshold', start=0.0, end=1.0, step=0.05, value=0.1)
+zoom_slider_3d = pn.widgets.IntSlider(name='3D Zoom Level', start=1, end=20, value=19)
+cmap_select_3d = pn.widgets.Select(name='3D Colormap', options=["rainbow", "viridis", "plasma"])
+fps_slider_3d = pn.widgets.IntSlider(name='3D FPS', start=1, end=10, value=2)
+Altitude_slider = pn.widgets.IntSlider(name='Define Ash Altitude', start=1, end=15, value=1)
+
+threshold_slider_2d = pn.widgets.FloatSlider(name='2D Threshold', start=0.0, end=1.0, step=0.01, value=0.005)
+zoom_slider_2d = pn.widgets.IntSlider(name='2D Zoom Level', start=1, end=20, value=19)
+fps_slider_2d = pn.widgets.IntSlider(name='2D FPS', start=1, end=10, value=2)
+cmap_select_2d = pn.widgets.Select(name='2D Colormap', options=["rainbow", "viridis", "plasma"])
+
+def process_zip(event=None):
+    if file_input.value:
+        zip_path = os.path.join(MEDIA_DIR, file_input.filename)
+        with open(zip_path, "wb") as f:
+            f.write(file_input.value)
+        status.object = "✅ ZIP uploaded and saved."
+    else:
+        zip_path = os.path.join(MEDIA_DIR, "default_model.zip")
+        if not os.path.exists(zip_path):
+            zip_path = "default_model.zip"
+        if not os.path.exists(zip_path):
+            status.object = "❌ No ZIP uploaded and default_model.zip not found."
             return
-    
-        class_items = class_names.split(",")
-        class_likelihoods = get_similarity_scores(class_items, pil_img)
-    
-        # build the results column
-        results = pn.Column("##### 🎉 Here are the results!", img)
-    
-        for class_item, class_likelihood in zip(class_items, class_likelihoods):
-            row_label = pn.widgets.StaticText(
-                name=class_item.strip(), value=f"{class_likelihood:.2%}", align="center"
-            )
-            row_bar = pn.indicators.Progress(
-                value=int(class_likelihood * 100),
-                sizing_mode="stretch_width",
-                bar_color="secondary",
-                margin=(0, 10),
-                design=pn.theme.Material,
-            )
-            results.append(pn.Column(row_label, row_bar))
-        yield results
-    finally:
-        main.disabled = False
-
-
-# create widgets
-randomize_url = pn.widgets.Button(name="Randomize URL", align="end")
-
-image_url = pn.widgets.TextInput(
-    name="Image URL to classify",
-    value=pn.bind(random_url, randomize_url),
+        status.object = "📦 Using default_model.zip"
+
+    try:
+        output_dir = os.path.join("./", "ash_output")
+        os.makedirs(output_dir, exist_ok=True)
+    except PermissionError:
+        output_dir = os.path.join(tempfile.gettempdir(), "name_output")
+        os.makedirs(output_dir, exist_ok=True)
+    shutil.rmtree(output_dir, ignore_errors=True)
+    os.makedirs(output_dir, exist_ok=True)
+
+    try:
+        processor = NAMEDataProcessor(output_root=output_dir)
+        processor.batch_process_zip(zip_path)
+
+        animator_obj["3d"] = [xr.open_dataset(fp).load() for fp in sorted(glob.glob(os.path.join(output_dir, "3D", "*.nc")))]
+        animator_obj["2d"] = [xr.open_dataset(fp).load() for fp in sorted(glob.glob(os.path.join(output_dir, "horizontal", "*.nc")))]
+
+        with open(os.path.join(MEDIA_DIR, "last_run.txt"), "w") as f:
+            f.write(zip_path)
+
+        status.object += f" | ✅ Loaded 3D: {len(animator_obj['3d'])} & 2D: {len(animator_obj['2d'])}"
+        update_media_tabs()
+    except Exception as e:
+        logging.exception("Error during ZIP processing")
+        status.object = f"❌ Processing failed: {e}"
+
+def reset_app(event=None):
+    animator_obj.clear()
+    file_input.value = None
+    status.object = "🔄 App has been reset."
+    for folder in ["ash_output", "2D", "3D"]:
+        shutil.rmtree(os.path.join(MEDIA_DIR, folder), ignore_errors=True)
+    if os.path.exists(os.path.join(MEDIA_DIR, "last_run.txt")):
+        os.remove(os.path.join(MEDIA_DIR, "last_run.txt"))
+    update_media_tabs()
+
+def restore_previous_session():
+    try:
+        state_file = os.path.join(MEDIA_DIR, "last_run.txt")
+        if os.path.exists(state_file):
+            with open(state_file) as f:
+                zip_path = f.read().strip()
+            if os.path.exists(zip_path):
+                output_dir = os.path.join("./", "ash_output")
+                os.makedirs(output_dir, exist_ok=True)
+                animator_obj["3d"] = [xr.open_dataset(fp).load() for fp in sorted(glob.glob(os.path.join(output_dir, "3D", "*.nc")))]
+                animator_obj["2d"] = [xr.open_dataset(fp).load() for fp in sorted(glob.glob(os.path.join(output_dir, "horizontal", "*.nc")))]
+                status.object = f"🔁 Restored previous session from {os.path.basename(zip_path)}"
+                update_media_tabs()
+    except Exception as e:
+        logging.exception("Error restoring previous session")
+        status.object = f"⚠️ Could not restore previous session: {e}"
+
+process_button.on_click(process_zip)
+reset_button.on_click(reset_app)
+
+def build_animator_3d():
+    ds = animator_obj["3d"]
+    attrs = ds[0].attrs
+    lons, lats, grid = create_grid(attrs)
+    return SimpleNamespace(datasets=ds, levels=ds[0].altitude.values, lons=lons, lats=lats,
+                           lon_grid=grid[0], lat_grid=grid[1])
+
+def build_animator_2d():
+    ds = animator_obj["2d"]
+    lat_grid, lon_grid = xr.broadcast(ds[0]["latitude"], ds[0]["longitude"])
+    return SimpleNamespace(datasets=ds, lats=ds[0]["latitude"].values,
+                           lons=ds[0]["longitude"].values,
+                           lat_grid=lat_grid.values, lon_grid=lon_grid.values)
+
+def plot_z_level():
+    try:
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        os.makedirs(out, exist_ok=True)
+        Plot_3DField_Data(animator, out, cmap_select_3d.value, threshold_slider_3d.value,
+                          zoom_slider_3d.value, fps_slider_3d.value).plot_single_z_level(
+                              Altitude_slider.value, f"ash_altitude{Altitude_slider.value}km_runTimes.gif")
+        update_media_tabs()
+        status.object = "✅ Z-Level animation created."
+    except Exception as e:
+        logging.exception("Error in plot_z_level")
+        status.object = f"❌ Error in Z-Level animation: {e}"
+
+def plot_vertical_profile():
+    try:
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        os.makedirs(out, exist_ok=True)
+        Plot_3DField_Data(animator, out, cmap_select_3d.value, fps_slider_3d.value,
+                          threshold_slider_3d.value, zoom_level=zoom_slider_3d.value).plot_vertical_profile_at_time(
+                              Altitude_slider.value - 1, f"T{Altitude_slider.value - 1}_profile.gif")
+        update_media_tabs()
+        status.object = "✅ Vertical profile animation created."
+    except Exception as e:
+        logging.exception("Error in plot_vertical_profile")
+        status.object = f"❌ Error in vertical profile animation: {e}"
+
+def animate_all_altitude_profiles():
+    try:
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        Plot_3DField_Data(animator, out, cmap_select_3d.value, threshold_slider_3d.value,
+                          zoom_slider_3d.value).animate_all_altitude_profiles()
+        update_media_tabs()
+        status.object = "✅ All altitude profile animations created."
+    except Exception as e:
+        logging.exception("Error in animate_all_altitude_profiles")
+        status.object = f"❌ Error animating all altitude profiles: {e}"
+
+def export_jpg_frames():
+    try:
+        animator = build_animator_3d()
+        out = os.path.join(MEDIA_DIR, "3D")
+        Plot_3DField_Data(animator, out, cmap_select_3d.value, threshold_slider_3d.value,
+                          zoom_slider_3d.value).export_frames_as_jpgs(include_metadata=True)
+        update_media_tabs()
+        status.object = "✅ JPG frames exported."
+    except Exception as e:
+        logging.exception("Error exporting JPG frames")
+        status.object = f"❌ Error exporting JPG frames: {e}"
+
+def plot_2d_field(field):
+    try:
+        animator = build_animator_2d()
+        out = os.path.join(MEDIA_DIR, "2D")
+        Plot_Horizontal_Data(animator, out, cmap_select_2d.value, fps_slider_2d.value,
+                             include_metadata=True, threshold=threshold_slider_2d.value,
+                             zoom_width_deg=6.0, zoom_height_deg=6.0,
+                             zoom_level=zoom_slider_2d.value,
+                             static_frame_export=True).plot_single_field_over_time(field, f"{field}.gif")
+        update_media_tabs()
+        status.object = f"✅ 2D field `{field}` animation created."
+    except Exception as e:
+        logging.exception(f"Error in plot_2d_field: {field}")
+        status.object = f"❌ Error in 2D field `{field}` animation: {e}"
+
+def human_readable_size(size):
+    for unit in ['B', 'KB', 'MB', 'GB']:
+        if size < 1024: return f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} TB"
+
+# def generate_output_gallery(base_folder):
+#     grouped = defaultdict(lambda: defaultdict(list))
+#     for root, _, files in os.walk(os.path.join(MEDIA_DIR, base_folder)):
+#         for file in files:
+#             ext = os.path.splitext(file)[1].lower()
+#             subfolder = os.path.relpath(root, MEDIA_DIR)
+#             grouped[subfolder][ext].append(os.path.join(root, file))
+
+#     folder_panels = []
+#     for subfolder, ext_files in sorted(grouped.items()):
+#         section = []
+#         for ext, paths in sorted(ext_files.items()):
+#             previews = []
+#             for path in sorted(paths, key=os.path.getmtime, reverse=True):
+#                 size = human_readable_size(os.path.getsize(path))
+#                 mod = datetime.fromtimestamp(os.path.getmtime(path)).strftime("%Y-%m-%d %H:%M")
+#                 title = f"**{os.path.basename(path)}**\n_{size}, {mod}_"
+#                 download = pn.widgets.FileDownload(label="⬇", file=path, filename=os.path.basename(path), width=60)
+#                 if ext in [".gif", ".png", ".jpg", ".jpeg"]:
+#                     preview = pn.pane.Image(path, width=320)
+#                 else:
+#                     with open(path, "r", errors="ignore") as f:
+#                         content = f.read(2048)
+#                     preview = pn.pane.PreText(content, width=320)
+#                 card = pn.Card(pn.pane.Markdown(title), preview, pn.Row(download), width=360)
+#                 previews.append(card)
+#             section.append(pn.Column(f"### {ext.upper()}", pn.GridBox(*previews, ncols=2)))
+#         folder_section = pn.Card(f"📁 {subfolder}", *section, collapsible=True, width_policy="max")
+#         folder_panels.append(folder_section)
+
+#     return pn.Column(*folder_panels, height=600, scroll=True, sizing_mode='stretch_width', styles={'overflow': 'auto'})
+
+
+
+def generate_output_gallery(base_folder):
+    preview_container = pn.Column(width=640, height=550)
+    preview_container.append(pn.pane.Markdown("👈 Click a thumbnail to preview"))
+    folder_cards = []
+
+    def make_preview(file_path):
+        ext = os.path.splitext(file_path)[1].lower()
+        title = pn.pane.Markdown(f"### {os.path.basename(file_path)}", width=640)
+        download_button = pn.widgets.FileDownload(file=file_path, filename=os.path.basename(file_path),
+                                                  label="⬇ Download", button_type="success", width=150)
+
+        if ext in [".gif", ".png", ".jpg", ".jpeg"]:
+            content = pn.pane.Image(file_path, width=640, height=450, sizing_mode="fixed")
+        else:
+            try:
+                with open(file_path, 'r', errors="ignore") as f:
+                    text = f.read(2048)
+                content = pn.pane.PreText(text, width=640, height=450)
+            except:
+                content = pn.pane.Markdown("*Unable to preview this file.*")
+
+        return pn.Column(title, content, download_button)
+
+    grouped = defaultdict(list)
+    for root, _, files in os.walk(os.path.join(MEDIA_DIR, base_folder)):
+        for file in sorted(files):
+            full_path = os.path.join(root, file)
+            if not os.path.exists(full_path):
+                continue
+            rel_folder = os.path.relpath(root, os.path.join(MEDIA_DIR, base_folder))
+            grouped[rel_folder].append(full_path)
+
+    for folder, file_paths in sorted(grouped.items()):
+        thumbnails = []
+        for full_path in file_paths:
+            filename = os.path.basename(full_path)
+            ext = os.path.splitext(full_path)[1].lower()
+
+            if ext in [".gif", ".png", ".jpg", ".jpeg"]:
+                img = pn.pane.Image(full_path, width=140, height=100)
+            else:
+                img = pn.pane.Markdown("📄", width=140, height=100)
+
+            view_button = pn.widgets.Button(name="👁", width=40, height=30, button_type="primary")
+
+            def click_handler(path=full_path):
+                def inner_click(event):
+                    preview_container[:] = [make_preview(path)]
+                return inner_click
+
+            view_button.on_click(click_handler())
+
+            overlay = pn.Column(pn.Row(pn.Spacer(width=90), view_button), img, width=160)
+            label_md = pn.pane.Markdown(f"**{filename}**", width=140, height=35)
+            thumb_card = pn.Column(overlay, label_md, width=160)
+            thumbnails.append(thumb_card)
+
+        folder_card = pn.Card(pn.GridBox(*thumbnails, ncols=2), title=f"📁 {folder}", width=400, collapsible=True)
+        folder_cards.append(folder_card)
+
+    folder_scroll = pn.Column(*folder_cards, scroll=True, height=600, width=420)
+    return pn.Row(preview_container, pn.Spacer(width=20), folder_scroll)
+
+def update_media_tabs():
+    media_tab_2d.objects[:] = [generate_output_gallery("2D")]
+    media_tab_3d.objects[:] = [generate_output_gallery("3D")]
+
+media_tab_2d = pn.Column(generate_output_gallery("2D"))
+media_tab_3d = pn.Column(generate_output_gallery("3D"))
+
+media_tab = pn.Tabs(
+    ("🖼 2D Output Gallery", media_tab_2d),
+    ("🖼 3D Output Gallery", media_tab_3d),
+    dynamic=True
 )
-class_names = pn.widgets.TextInput(
-    name="Comma separated class names",
-    placeholder="Enter possible class names, e.g. cat, dog",
-    value="cat, dog, parrot",
+
+tab3d = pn.Column(
+    threshold_slider_3d, zoom_slider_3d, fps_slider_3d, Altitude_slider, cmap_select_3d,
+    pn.widgets.Button(name="🎞 Generate animation at selected altitude level", button_type="primary", on_click=lambda e: tab3d.append(plot_z_level())),
+    pn.widgets.Button(name="📈 Generate vertical profile animation at time index", button_type="primary", on_click=lambda e: tab3d.append(plot_vertical_profile())),
+    pn.widgets.Button(name="📊 Generate all altitude level animations", button_type="primary", on_click=lambda e: tab3d.append(animate_all_altitude_profiles())),
+    pn.widgets.Button(name="🖼 Export all animation frames as JPG", button_type="primary", on_click=lambda e: tab3d.append(export_jpg_frames())),
 )
 
-input_widgets = pn.Column(
-    "##### 😊 Click randomize or paste a URL to start classifying!",
-    pn.Row(image_url, randomize_url),
-    class_names,
+tab2d = pn.Column(
+    threshold_slider_2d, zoom_slider_2d, fps_slider_2d, cmap_select_2d,
+    pn.widgets.Button(name="🌫 Animate Air Concentration", button_type="primary", on_click=lambda e: tab2d.append(plot_2d_field("air_concentration"))),
+    pn.widgets.Button(name="🌧 Animate Dry Deposition Rate", button_type="primary", on_click=lambda e: tab2d.append(plot_2d_field("dry_deposition_rate"))),
+    pn.widgets.Button(name="💧 Animate Wet Deposition Rate", button_type="primary", on_click=lambda e: tab2d.append(plot_2d_field("wet_deposition_rate"))),
 )
 
-# add interactivity
-interactive_result = pn.panel(
-    pn.bind(process_inputs, image_url=image_url, class_names=class_names),
-    height=600,
+help_tab = pn.Column(pn.pane.Markdown("""
+## ❓ How to Use the NAME Ash Visualizer
+
+This dashboard allows users to upload and visualize outputs from the NAME ash dispersion model.
+
+### 🧭 Workflow
+1. **Upload ZIP** containing NetCDF files from the NAME model.
+2. Use **3D and 2D tabs** to configure and generate animations.
+3. Use **Media Viewer** to preview and download results.
+
+### 🧳 ZIP Structure
+```
+## 🗂 How Uploaded ZIP is Processed
+
+```text
+┌────────────────────────────────────────────┐
+│           Uploaded ZIP (.zip)              │
+│  (e.g. Taal_273070_20200112_scenario_*.zip)│
+└────────────────────────────────────────────┘
+                    │
+                    ▼
+      ┌───────────────────────────────┐
+      │ Contains: raw .txt outputs    │
+      │  - AQOutput_3DField_*.txt     │
+      │  - AQOutput_horizontal_*.txt  │
+      └───────────────────────────────┘
+                    │
+                    ▼
+  ┌────────────────────────────────────────┐
+  │   NAMEDataProcessor.batch_process_zip()│
+  └────────────────────────────────────────┘
+                    │
+                    ▼
+      ┌─────────────────────────────┐
+      │   Converts to NetCDF files  │
+      │     - ash_output/3D/*.nc    │
+      │     - ash_output/horizontal/*.nc │
+      └─────────────────────────────┘
+                    │
+                    ▼
+   ┌─────────────────────────────────────┐
+   │ View & animate in 3D/2D tabs        │
+   │ Download results in Media Viewer    │
+   └─────────────────────────────────────┘
+
+```
+
+### 📢 Tips
+- Reset the app with 🔄 if needed.
+- View logs if an error occurs.
+- Outputs are temporary per session.
+""", sizing_mode="stretch_width", width=800))
+
+tabs = pn.Tabs(
+    ("🧱 3D Field", tab3d),
+    ("🌍 2D Field", tab2d),
+    ("📁 Media Viewer", media_tab),
+    ("❓ Help", help_tab)
 )
 
-# add footer
-footer_row = pn.Row(pn.Spacer(), align="center")
-for icon, url in ICON_URLS.items():
-    href_button = pn.widgets.Button(icon=icon, width=35, height=35)
-    href_button.js_on_click(code=f"window.open('{url}')")
-    footer_row.append(href_button)
-footer_row.append(pn.Spacer())
-
-# create dashboard
-main = pn.WidgetBox(
-    input_widgets,
-    interactive_result,
-    footer_row,
+sidebar = pn.Column(
+    pn.pane.Markdown("## 🌋 NAME Ash Visualizer", sizing_mode="stretch_width"),
+    pn.Card(pn.Column(file_input, process_button, reset_button, sizing_mode="stretch_width"),
+            title="📂 File Upload & Processing", collapsible=True, sizing_mode="stretch_width"),
+    pn.Card(pn.Column(download_button, log_link, sizing_mode="stretch_width"),
+            title="📁 Downloads & Logs", collapsible=True, sizing_mode="stretch_width"),
+    pn.Card(status, title="📢 Status", collapsible=True, sizing_mode="stretch_width"),
+    sizing_mode="stretch_width", width=300
 )
 
-title = "Panel Demo - Image Classification"
-pn.template.BootstrapTemplate(
-    title=title,
-    main=main,
-    main_max_width="min(50%, 698px)",
-    header_background="#F08080",
-).servable(title=title)
+restore_previous_session()
+
+pn.template.FastListTemplate(
+    title="NAME Visualizer Dashboard",
+    sidebar=sidebar,
+    main=[tabs],
+).servable()
+ '''

ash_animator/__init__.py

@@ -0,0 +1,12 @@
+
+# Auto-generated __init__.py to import all modules
+from .basemaps import *
+from .converter import *
+from .interpolation import *
+from .plot_3dfield_data import *
+from .plot_horizontal_data import *
+from .utils import *
+from .animation_all import *
+from .animation_single import *
+from .animation_vertical import *
+from .export import *

ash_animator/animation_all.py

@@ -0,0 +1,516 @@
+
+# import os
+# import numpy as np
+# import matplotlib.pyplot as plt
+# import matplotlib.animation as animation
+# import matplotlib.ticker as mticker
+# import cartopy.crs as ccrs
+# import cartopy.feature as cfeature
+# from adjustText import adjust_text
+# import cartopy.io.shapereader as shpreader
+# from .interpolation import interpolate_grid
+# from .basemaps import draw_etopo_basemap
+
+# def animate_all_z_levels(animator, output_folder: str, fps: int = 2, threshold: float = 0.1):
+#     os.makedirs(output_folder, exist_ok=True)
+
+#     countries_shp = shpreader.natural_earth(resolution='110m', category='cultural', name='admin_0_countries')
+#     reader = shpreader.Reader(countries_shp)
+#     country_geoms = list(reader.records())
+
+#     for z_index, z_val in enumerate(animator.levels):
+#         fig = plt.figure(figsize=(16, 7))
+#         proj = ccrs.PlateCarree()
+#         ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+#         ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+#         valid_mask = np.stack([
+#             ds['ash_concentration'].values[z_index] for ds in animator.datasets
+#         ]).max(axis=0) > 0
+#         y_idx, x_idx = np.where(valid_mask)
+
+#         if y_idx.size == 0 or x_idx.size == 0:
+#             print(f"Z level {z_val} km has no valid data. Skipping...")
+#             plt.close()
+#             continue
+
+#         y_min, y_max = y_idx.min(), y_idx.max()
+#         x_min, x_max = x_idx.min(), x_idx.max()
+
+#         buffer_y = int((y_max - y_min) * 0.5)
+#         buffer_x = int((x_max - x_min) * 0.5)
+
+#         y_start = max(0, y_min - buffer_y)
+#         y_end = min(animator.lat_grid.shape[0], y_max + buffer_y + 1)
+#         x_start = max(0, x_min - buffer_x)
+#         x_end = min(animator.lon_grid.shape[1], x_max + buffer_x + 1)
+
+#         lat_zoom = animator.lats[y_start:y_end]
+#         lon_zoom = animator.lons[x_start:x_end]
+#         lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+
+#         valid_frames = []
+#         for t in range(len(animator.datasets)):
+#             data = animator.datasets[t]['ash_concentration'].values[z_index]
+#             interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+#             interp = np.where(interp < 0, np.nan, interp)
+#             if np.isfinite(interp).sum() > 0:
+#                 valid_frames.append(t)
+
+#         if not valid_frames:
+#             print(f"No valid frames for Z={z_val} km. Skipping animation.")
+#             plt.close()
+#             continue
+
+#         def update(t):
+#             ax1.clear()
+#             ax2.clear()
+
+#             data = animator.datasets[t]['ash_concentration'].values[z_index]
+#             interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+#             interp = np.where(interp < 0, np.nan, interp)
+#             zoom_plot = interp[y_start:y_end, x_start:x_end]
+
+#             valid_vals = interp[np.isfinite(interp)]
+#             if valid_vals.size == 0:
+#                 return []
+
+#             min_val = np.nanmin(valid_vals)
+#             max_val = np.nanmax(valid_vals)
+#             log_cutoff = 1e-3
+#             log_ratio = max_val / (min_val + 1e-6)
+#             use_log = min_val > log_cutoff and log_ratio > 100
+
+#             if use_log:
+#                 data_for_plot = np.where(interp > log_cutoff, interp, np.nan)
+#                 levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20)
+#                 scale_label = "Hybrid Log"
+#             else:
+#                 data_for_plot = interp
+#                 levels = np.linspace(0, max_val, 20)
+#                 scale_label = "Linear"
+
+#             draw_etopo_basemap(ax1, mode='stock')
+#             draw_etopo_basemap(ax2, mode='stock')
+
+#             c1 = ax1.contourf(animator.lons, animator.lats, data_for_plot, levels=levels,
+#                             cmap="rainbow", alpha=0.6, transform=proj)
+#             ax1.contour(animator.lons, animator.lats, data_for_plot, levels=levels,
+#                         colors='black', linewidths=0.5, transform=proj)
+#             ax1.set_title(f"T{t+1} | Alt: {z_val} km (Full - {scale_label})")
+#             ax1.set_extent([animator.lons.min(), animator.lons.max(), animator.lats.min(), animator.lats.max()])
+#             ax1.coastlines()
+#             ax1.add_feature(cfeature.BORDERS, linestyle=':')
+#             ax1.add_feature(cfeature.LAND)
+#             ax1.add_feature(cfeature.OCEAN)
+
+#             c2 = ax2.contourf(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+#                             cmap="rainbow", alpha=0.4, transform=proj)
+#             ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+#                         colors='black', linewidths=0.5, transform=proj)
+#             ax2.set_title(f"T{t+1} | Alt: {z_val} km (Zoom - {scale_label})")
+#             ax2.set_extent([lon_zoom.min(), lon_zoom.max(), lat_zoom.min(), lat_zoom.max()])
+#             ax2.coastlines()
+#             ax2.add_feature(cfeature.BORDERS, linestyle=':')
+#             ax2.add_feature(cfeature.LAND)
+#             ax2.add_feature(cfeature.OCEAN)
+
+#             ax2.text(animator.lons[0], animator.lats[0], animator.country_label, fontsize=9, color='white',
+#                     transform=proj, bbox=dict(facecolor='black', alpha=0.5))
+
+#             texts_ax1, texts_ax2 = [], []
+#             for country in country_geoms:
+#                 name = country.attributes['NAME_LONG']
+#                 geom = country.geometry
+#                 try:
+#                     lon, lat = geom.centroid.x, geom.centroid.y
+#                     if (lon_zoom.min() <= lon <= lon_zoom.max()) and (lat_zoom.min() <= lat <= lat_zoom.max()):
+#                         text = ax2.text(lon, lat, name, fontsize=6, transform=proj,
+#                                         ha='center', va='center', color='white',
+#                                         bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+#                         texts_ax2.append(text)
+
+#                     if (animator.lons.min() <= lon <= animator.lons.max()) and (animator.lats.min() <= lat <= animator.lats.max()):
+#                         text = ax1.text(lon, lat, name, fontsize=6, transform=proj,
+#                                         ha='center', va='center', color='white',
+#                                         bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+#                         texts_ax1.append(text)
+#                 except:
+#                     continue
+
+#             adjust_text(texts_ax1, ax=ax1, only_move={'points': 'y', 'text': 'y'},
+#                         arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+#             adjust_text(texts_ax2, ax=ax2, only_move={'points': 'y', 'text': 'y'},
+#                         arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+
+#             if np.nanmax(valid_vals) > threshold:
+#                 alert_text = f"⚠ Exceeds {threshold} g/m³!"
+#                 for ax in [ax1, ax2]:
+#                     ax.text(0.99, 0.01, alert_text, transform=ax.transAxes,
+#                             ha='right', va='bottom', fontsize=10, color='red',
+#                             bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+#                 ax1.contour(animator.lons, animator.lats, interp, levels=[threshold], colors='red', linewidths=2, transform=proj)
+#                 ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=[threshold], colors='red', linewidths=2, transform=proj)
+
+#             if not hasattr(update, "colorbar"):
+#                 update.colorbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical',
+#                                             label="Ash concentration (g/m³)")
+#                 formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+#                 update.colorbar.ax.yaxis.set_major_formatter(formatter)
+#                 if use_log:
+#                     update.colorbar.ax.text(1.05, 1.02, "log scale", transform=update.colorbar.ax.transAxes,
+#                                             fontsize=9, color='gray', rotation=90, ha='left', va='bottom')
+
+#             return []
+
+#         ani = animation.FuncAnimation(fig, update, frames=valid_frames, blit=False)
+#         gif_path = os.path.join(output_folder, f"ash_T1-Tn_Z{z_index+1}.gif")
+#         ani.save(gif_path, writer='pillow', fps=fps)
+#         plt.close()
+#         print(f"✅ Saved animation for Z={z_val} km to {gif_path}")
+###################################################################################################################
+# import os
+# import numpy as np
+# import matplotlib.pyplot as plt
+# import matplotlib.animation as animation
+# import matplotlib.ticker as mticker
+# import cartopy.crs as ccrs
+# import cartopy.feature as cfeature
+# from adjustText import adjust_text
+# import cartopy.io.shapereader as shpreader
+# from .interpolation import interpolate_grid
+# from .basemaps import draw_etopo_basemap
+
+# def animate_all_z_levels(animator, output_folder: str, fps: int = 2, threshold: float = 0.1):
+#     os.makedirs(output_folder, exist_ok=True)
+
+#     countries_shp = shpreader.natural_earth(resolution='110m', category='cultural', name='admin_0_countries')
+#     reader = shpreader.Reader(countries_shp)
+#     country_geoms = list(reader.records())
+
+#     # Compute consistent zoom window across all z-levels and time frames
+#     valid_mask_all = np.zeros_like(animator.datasets[0]['ash_concentration'].values[0], dtype=bool)
+#     for ds in animator.datasets:
+#         for z in range(len(animator.levels)):
+#             valid_mask_all |= ds['ash_concentration'].values[z] > 0
+
+#     y_idx_all, x_idx_all = np.where(valid_mask_all)
+#     if y_idx_all.size == 0 or x_idx_all.size == 0:
+#         raise ValueError("No valid data found across any Z level or frame.")
+
+#     y_min, y_max = y_idx_all.min(), y_idx_all.max()
+#     x_min, x_max = x_idx_all.min(), x_idx_all.max()
+#     buffer_y = int((y_max - y_min) * 0.5)
+#     buffer_x = int((x_max - x_min) * 0.5)
+
+#     y_start = max(0, y_min - buffer_y)
+#     y_end = min(animator.lat_grid.shape[0], y_max + buffer_y + 1)
+#     x_start = max(0, x_min - buffer_x)
+#     x_end = min(animator.lon_grid.shape[1], x_max + buffer_x + 1)
+
+#     lat_zoom = animator.lats[y_start:y_end]
+#     lon_zoom = animator.lons[x_start:x_end]
+#     lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+
+#     for z_index, z_val in enumerate(animator.levels):
+#         fig = plt.figure(figsize=(16, 7))
+#         proj = ccrs.PlateCarree()
+#         ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+#         ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+#         valid_frames = []
+#         for t in range(len(animator.datasets)):
+#             data = animator.datasets[t]['ash_concentration'].values[z_index]
+#             interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+#             interp = np.where(interp < 0, np.nan, interp)
+#             if np.isfinite(interp).sum() > 0:
+#                 valid_frames.append(t)
+
+#         if not valid_frames:
+#             print(f"No valid frames for Z={z_val} km. Skipping animation.")
+#             plt.close()
+#             continue
+
+#         def update(t):
+#             ax1.clear()
+#             ax2.clear()
+
+#             data = animator.datasets[t]['ash_concentration'].values[z_index]
+#             interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+#             interp = np.where(interp < 0, np.nan, interp)
+#             zoom_plot = interp[y_start:y_end, x_start:x_end]
+
+#             valid_vals = interp[np.isfinite(interp)]
+#             if valid_vals.size == 0:
+#                 return []
+
+#             min_val = np.nanmin(valid_vals)
+#             max_val = np.nanmax(valid_vals)
+#             log_cutoff = 1e-3
+#             log_ratio = max_val / (min_val + 1e-6)
+#             use_log = min_val > log_cutoff and log_ratio > 100
+
+#             if use_log:
+#                 data_for_plot = np.where(interp > log_cutoff, interp, np.nan)
+#                 levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20)
+#                 scale_label = "Hybrid Log"
+#             else:
+#                 data_for_plot = interp
+#                 levels = np.linspace(0, max_val, 20)
+#                 scale_label = "Linear"
+
+#             draw_etopo_basemap(ax1, mode='stock')
+#             draw_etopo_basemap(ax2, mode='stock')
+
+#             c1 = ax1.contourf(animator.lons, animator.lats, data_for_plot, levels=levels,
+#                             cmap="rainbow", alpha=0.6, transform=proj)
+#             ax1.contour(animator.lons, animator.lats, data_for_plot, levels=levels,
+#                         colors='black', linewidths=0.5, transform=proj)
+#             ax1.set_title(f"T{t+1} | Alt: {z_val} km (Full - {scale_label})")
+#             ax1.set_extent([animator.lons.min(), animator.lons.max(), animator.lats.min(), animator.lats.max()])
+#             ax1.coastlines()
+#             ax1.add_feature(cfeature.BORDERS, linestyle=':')
+#             ax1.add_feature(cfeature.LAND)
+#             ax1.add_feature(cfeature.OCEAN)
+
+#             c2 = ax2.contourf(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+#                             cmap="rainbow", alpha=0.4, transform=proj)
+#             ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+#                         colors='black', linewidths=0.5, transform=proj)
+#             ax2.set_title(f"T{t+1} | Alt: {z_val} km (Zoom - {scale_label})")
+#             ax2.set_extent([lon_zoom.min(), lon_zoom.max(), lat_zoom.min(), lat_zoom.max()])
+#             ax2.coastlines()
+#             ax2.add_feature(cfeature.BORDERS, linestyle=':')
+#             ax2.add_feature(cfeature.LAND)
+#             ax2.add_feature(cfeature.OCEAN)
+
+#             ax2.text(animator.lons[0], animator.lats[0], animator.country_label, fontsize=9, color='white',
+#                      transform=proj, bbox=dict(facecolor='black', alpha=0.5))
+
+#             texts_ax1, texts_ax2 = [], []
+#             for country in country_geoms:
+#                 name = country.attributes['NAME_LONG']
+#                 geom = country.geometry
+#                 try:
+#                     lon, lat = geom.centroid.x, geom.centroid.y
+#                     if (lon_zoom.min() <= lon <= lon_zoom.max()) and (lat_zoom.min() <= lat <= lat_zoom.max()):
+#                         text = ax2.text(lon, lat, name, fontsize=6, transform=proj,
+#                                         ha='center', va='center', color='white',
+#                                         bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+#                         texts_ax2.append(text)
+
+#                     if (animator.lons.min() <= lon <= animator.lons.max()) and (animator.lats.min() <= lat <= animator.lats.max()):
+#                         text = ax1.text(lon, lat, name, fontsize=6, transform=proj,
+#                                         ha='center', va='center', color='white',
+#                                         bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+#                         texts_ax1.append(text)
+#                 except:
+#                     continue
+
+#             adjust_text(texts_ax1, ax=ax1, only_move={'points': 'y', 'text': 'y'},
+#                         arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+#             adjust_text(texts_ax2, ax=ax2, only_move={'points': 'y', 'text': 'y'},
+#                         arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+
+#             if np.nanmax(valid_vals) > threshold:
+#                 alert_text = f"⚠ Exceeds {threshold} g/m³!"
+#                 for ax in [ax1, ax2]:
+#                     ax.text(0.99, 0.01, alert_text, transform=ax.transAxes,
+#                             ha='right', va='bottom', fontsize=10, color='red',
+#                             bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+#                 ax1.contour(animator.lons, animator.lats, interp, levels=[threshold], colors='red', linewidths=2, transform=proj)
+#                 ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=[threshold], colors='red', linewidths=2, transform=proj)
+
+#             if not hasattr(update, "colorbar"):
+#                 update.colorbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical',
+#                                                label="Ash concentration (g/m³)")
+#                 formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+#                 update.colorbar.ax.yaxis.set_major_formatter(formatter)
+#                 if use_log:
+#                     update.colorbar.ax.text(1.05, 1.02, "log scale", transform=update.colorbar.ax.transAxes,
+#                                             fontsize=9, color='gray', rotation=90, ha='left', va='bottom')
+
+#             return []
+
+#         ani = animation.FuncAnimation(fig, update, frames=valid_frames, blit=False)
+#         gif_path = os.path.join(output_folder, f"ash_T1-Tn_Z{z_index+1}.gif")
+#         ani.save(gif_path, writer='pillow', fps=fps)
+#         plt.close()
+#         print(f"✅ Saved animation for Z={z_val} km to {gif_path}")
+
+
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import matplotlib.ticker as mticker
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+from adjustText import adjust_text
+import cartopy.io.shapereader as shpreader
+from .interpolation import interpolate_grid
+from .basemaps import draw_etopo_basemap
+
+def animate_all_z_levels(animator, output_folder: str, fps: int = 2, threshold: float = 0.1,
+                         zoom_width_deg: float = 6.0, zoom_height_deg: float = 6.0):
+    os.makedirs(output_folder, exist_ok=True)
+
+    countries_shp = shpreader.natural_earth(resolution='110m', category='cultural', name='admin_0_countries')
+    reader = shpreader.Reader(countries_shp)
+    country_geoms = list(reader.records())
+
+    # Find the most active region (max concentration point)
+    max_conc = -np.inf
+    center_lat = center_lon = None
+    for ds in animator.datasets:
+        for z in range(len(animator.levels)):
+            data = ds['ash_concentration'].values[z]
+            if np.max(data) > max_conc:
+                max_conc = np.max(data)
+                max_idx = np.unravel_index(np.argmax(data), data.shape)
+                center_lat = animator.lat_grid[max_idx]
+                center_lon = animator.lon_grid[max_idx]
+
+    if center_lat is None or center_lon is None:
+        raise ValueError("No valid concentration found to determine zoom center.")
+
+    # Compute fixed zoom extents in lat/lon degrees
+    lon_zoom_min = center_lon - zoom_width_deg / 2
+    lon_zoom_max = center_lon + zoom_width_deg / 2
+    lat_zoom_min = center_lat - zoom_height_deg / 2
+    lat_zoom_max = center_lat + zoom_height_deg / 2
+
+    # Create zoom grids for plotting
+    lat_zoom = animator.lats[(animator.lats >= lat_zoom_min) & (animator.lats <= lat_zoom_max)]
+    lon_zoom = animator.lons[(animator.lons >= lon_zoom_min) & (animator.lons <= lon_zoom_max)]
+    lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+
+    for z_index, z_val in enumerate(animator.levels):
+        fig = plt.figure(figsize=(16, 7))
+        proj = ccrs.PlateCarree()
+        ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+        ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+        valid_frames = []
+        for t in range(len(animator.datasets)):
+            data = animator.datasets[t]['ash_concentration'].values[z_index]
+            interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+            interp = np.where(interp < 0, np.nan, interp)
+            if np.isfinite(interp).sum() > 0:
+                valid_frames.append(t)
+
+        if not valid_frames:
+            print(f"No valid frames for Z={z_val} km. Skipping animation.")
+            plt.close()
+            continue
+
+        def update(t):
+            ax1.clear()
+            ax2.clear()
+
+            data = animator.datasets[t]['ash_concentration'].values[z_index]
+            interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+            interp = np.where(interp < 0, np.nan, interp)
+
+            # Extract zoom window from interpolated data
+            lat_idx = np.where((animator.lats >= lat_zoom_min) & (animator.lats <= lat_zoom_max))[0]
+            lon_idx = np.where((animator.lons >= lon_zoom_min) & (animator.lons <= lon_zoom_max))[0]
+            zoom_plot = interp[np.ix_(lat_idx, lon_idx)]
+
+            valid_vals = interp[np.isfinite(interp)]
+            if valid_vals.size == 0:
+                return []
+
+            min_val = np.nanmin(valid_vals)
+            max_val = np.nanmax(valid_vals)
+            log_cutoff = 1e-3
+            log_ratio = max_val / (min_val + 1e-6)
+            use_log = min_val > log_cutoff and log_ratio > 100
+
+            if use_log:
+                data_for_plot = np.where(interp > log_cutoff, interp, np.nan)
+                levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20)
+                scale_label = "Hybrid Log"
+            else:
+                data_for_plot = interp
+                levels = np.linspace(0, max_val, 20)
+                scale_label = "Linear"
+
+            draw_etopo_basemap(ax1, mode='stock')
+            draw_etopo_basemap(ax2, mode='stock')
+
+            c1 = ax1.contourf(animator.lons, animator.lats, data_for_plot, levels=levels,
+                            cmap="rainbow", alpha=0.6, transform=proj)
+            ax1.contour(animator.lons, animator.lats, data_for_plot, levels=levels,
+                        colors='black', linewidths=0.5, transform=proj)
+            ax1.set_title(f"T{t+1} | Alt: {z_val} km (Full - {scale_label})")
+            ax1.set_extent([animator.lons.min(), animator.lons.max(), animator.lats.min(), animator.lats.max()])
+            ax1.coastlines()
+            ax1.add_feature(cfeature.BORDERS, linestyle=':')
+            ax1.add_feature(cfeature.LAND)
+            ax1.add_feature(cfeature.OCEAN)
+
+            c2 = ax2.contourf(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+                            cmap="rainbow", alpha=0.4, transform=proj)
+            ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+                        colors='black', linewidths=0.5, transform=proj)
+            ax2.set_title(f"T{t+1} | Alt: {z_val} km (Zoom - {scale_label})")
+            ax2.set_extent([lon_zoom_min, lon_zoom_max, lat_zoom_min, lat_zoom_max])
+            ax2.coastlines()
+            ax2.add_feature(cfeature.BORDERS, linestyle=':')
+            ax2.add_feature(cfeature.LAND)
+            ax2.add_feature(cfeature.OCEAN)
+
+            ax2.text(animator.lons[0], animator.lats[0], animator.country_label, fontsize=9, color='white',
+                     transform=proj, bbox=dict(facecolor='black', alpha=0.5))
+
+            texts_ax1, texts_ax2 = [], []
+            for country in country_geoms:
+                name = country.attributes['NAME_LONG']
+                geom = country.geometry
+                try:
+                    lon, lat = geom.centroid.x, geom.centroid.y
+                    if (lon_zoom_min <= lon <= lon_zoom_max) and (lat_zoom_min <= lat <= lat_zoom_max):
+                        text = ax2.text(lon, lat, name, fontsize=6, transform=proj,
+                                        ha='center', va='center', color='white',
+                                        bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+                        texts_ax2.append(text)
+
+                    if (animator.lons.min() <= lon <= animator.lons.max()) and (animator.lats.min() <= lat <= animator.lats.max()):
+                        text = ax1.text(lon, lat, name, fontsize=6, transform=proj,
+                                        ha='center', va='center', color='white',
+                                        bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+                        texts_ax1.append(text)
+                except:
+                    continue
+
+            adjust_text(texts_ax1, ax=ax1, only_move={'points': 'y', 'text': 'y'},
+                        arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+            adjust_text(texts_ax2, ax=ax2, only_move={'points': 'y', 'text': 'y'},
+                        arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+
+            if np.nanmax(valid_vals) > threshold:
+                alert_text = f"⚠ Exceeds {threshold} g/m³!"
+                for ax in [ax1, ax2]:
+                    ax.text(0.99, 0.01, alert_text, transform=ax.transAxes,
+                            ha='right', va='bottom', fontsize=10, color='red',
+                            bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+                ax1.contour(animator.lons, animator.lats, interp, levels=[threshold], colors='red', linewidths=2, transform=proj)
+                ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=[threshold], colors='red', linewidths=2, transform=proj)
+
+            if not hasattr(update, "colorbar"):
+                update.colorbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical',
+                                               label="Ash concentration (g/m³)")
+                formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+                update.colorbar.ax.yaxis.set_major_formatter(formatter)
+                if use_log:
+                    update.colorbar.ax.text(1.05, 1.02, "log scale", transform=update.colorbar.ax.transAxes,
+                                            fontsize=9, color='gray', rotation=90, ha='left', va='bottom')
+
+            return []
+
+        ani = animation.FuncAnimation(fig, update, frames=valid_frames, blit=False)
+        gif_path = os.path.join(output_folder, f"ash_T1-Tn_Z{z_index+1}.gif")
+        ani.save(gif_path, writer='pillow', fps=fps)
+        plt.close()
+        print(f"✅ Saved animation for Z={z_val} km to {gif_path}")

ash_animator/animation_single.py

@@ -0,0 +1,147 @@
+
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import matplotlib.ticker as mticker
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+from .interpolation import interpolate_grid
+from .basemaps import draw_etopo_basemap
+
+def animate_single_z_level(animator, z_km: float, output_path: str, fps: int = 2, include_metadata: bool = True, threshold: float = 0.1):
+    if z_km not in animator.levels:
+        print(f"Z level {z_km} km not found in dataset.")
+        return
+
+    z_index = np.where(animator.levels == z_km)[0][0]
+    fig = plt.figure(figsize=(16, 7))
+    proj = ccrs.PlateCarree()
+    ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+    ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+    meta = animator.datasets[0].attrs
+    legend_text = (
+        f"Run name:         {meta.get('run_name', 'N/A')}\n"
+        f"Run time:         {meta.get('run_time', 'N/A')}\n"
+        f"Met data:         {meta.get('met_data', 'N/A')}\n"
+        f"Start release:    {meta.get('start_of_release', 'N/A')}\n"
+        f"End release:      {meta.get('end_of_release', 'N/A')}\n"
+        f"Source strength:  {meta.get('source_strength', 'N/A')} g/s\n"
+        f"Release loc:      {meta.get('release_location', 'N/A')}\n"
+        f"Release height:   {meta.get('release_height', 'N/A')} m asl\n"
+        f"Run duration:     {meta.get('run_duration', 'N/A')}"
+    )
+
+    valid_mask = np.stack([
+        ds['ash_concentration'].values[z_index] for ds in animator.datasets
+    ]).max(axis=0) > 0
+    y_idx, x_idx = np.where(valid_mask)
+
+    if y_idx.size == 0 or x_idx.size == 0:
+        print(f"Z level {z_km} km has no valid data. Skipping...")
+        plt.close()
+        return
+
+    y_min, y_max = y_idx.min(), y_idx.max()
+    x_min, x_max = x_idx.min(), x_idx.max()
+    buffer_y = int((y_max - y_min) * 0.5)
+    buffer_x = int((x_max - x_min) * 0.5)
+    y_start = max(0, y_min - buffer_y)
+    y_end = min(animator.lat_grid.shape[0], y_max + buffer_y + 1)
+    x_start = max(0, x_min - buffer_x)
+    x_end = min(animator.lon_grid.shape[1], x_max + buffer_x + 1)
+
+    lat_zoom = animator.lats[y_start:y_end]
+    lon_zoom = animator.lons[x_start:x_end]
+    lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+
+    valid_frames = []
+    for t in range(len(animator.datasets)):
+        interp = interpolate_grid(animator.datasets[t]['ash_concentration'].values[z_index],
+                                  animator.lon_grid, animator.lat_grid)
+        if np.isfinite(interp).sum() > 0:
+            valid_frames.append(t)
+
+    if not valid_frames:
+        print(f"No valid frames for Z={z_km} km. Skipping animation.")
+        plt.close()
+        return
+
+    def update(t):
+        ax1.clear()
+        ax2.clear()
+
+        data = animator.datasets[t]['ash_concentration'].values[z_index]
+        interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+        interp = np.where(interp < 0, np.nan, interp)
+        zoom_plot = interp[y_start:y_end, x_start:x_end]
+
+        valid_vals = interp[np.isfinite(interp)]
+        if valid_vals.size == 0:
+            return []
+
+        min_val = np.nanmin(valid_vals)
+        max_val = np.nanmax(valid_vals)
+        log_cutoff = 1e-3
+        use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+
+        levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+        data_for_plot = np.where(interp > log_cutoff, interp, 0) if use_log else interp
+        scale_label = "Log" if use_log else "Linear"
+
+        draw_etopo_basemap(ax1, mode='stock')
+        draw_etopo_basemap(ax2, mode='stock')
+
+        c1 = ax1.contourf(animator.lons, animator.lats, data_for_plot, levels=levels,
+                        cmap="rainbow", alpha=0.6, transform=proj)
+        ax1.set_title(f"T{t+1} | Alt: {z_km} km (Full - {scale_label})")
+        ax1.set_extent([animator.lons.min(), animator.lons.max(), animator.lats.min(), animator.lats.max()])
+        ax1.coastlines(); ax1.add_feature(cfeature.BORDERS); ax1.add_feature(cfeature.LAND); ax1.add_feature(cfeature.OCEAN)
+
+        c2 = ax2.contourf(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+                        cmap="rainbow", alpha=0.6, transform=proj)
+        ax2.set_title(f"T{t+1} | Alt: {z_km} km (Zoom - {scale_label})")
+        ax2.set_extent([lon_zoom.min(), lon_zoom.max(), lat_zoom.min(), lat_zoom.max()])
+        ax2.coastlines(); ax2.add_feature(cfeature.BORDERS); ax2.add_feature(cfeature.LAND); ax2.add_feature(cfeature.OCEAN)
+
+        if not hasattr(update, "colorbar"):
+            update.colorbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical',
+                                        label="Ash concentration (g/m³)")
+            formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+            update.colorbar.ax.yaxis.set_major_formatter(formatter)
+            if use_log:
+                update.colorbar.ax.text(1.05, 1.02, "log scale", transform=update.colorbar.ax.transAxes,
+                                        fontsize=9, color='gray', rotation=90, ha='left', va='bottom')
+
+        if include_metadata:
+            ax1.annotate(legend_text, xy=(0.75, 0.99), xycoords='axes fraction',
+                        fontsize=8, ha='left', va='top',
+                        bbox=dict(boxstyle="round", facecolor="white", edgecolor="gray"))
+            for ax in [ax1, ax2]:
+                ax.text(0.01, 0.01,
+                        f"Source: NAME\nRes: {animator.x_res:.2f}°\n{meta.get('run_name', 'N/A')}",
+                        transform=ax.transAxes, fontsize=8, color='white',
+                        bbox=dict(facecolor='black', alpha=0.5))
+
+        for ax in [ax1, ax2]:
+            ax.text(0.01, 0.98, f"Time step T{t+1}", transform=ax.transAxes,
+                    fontsize=9, color='white', va='top', ha='left',
+                    bbox=dict(facecolor='black', alpha=0.4, boxstyle='round'))
+
+        if np.nanmax(valid_vals) > threshold:
+            alert_text = f"⚠ Exceeds {threshold} g/m³!"
+            for ax in [ax1, ax2]:
+                ax.text(0.99, 0.01, alert_text, transform=ax.transAxes,
+                        ha='right', va='bottom', fontsize=10, color='red',
+                        bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+            ax1.contour(animator.lons, animator.lats, interp, levels=[threshold], colors='red', linewidths=2, transform=proj)
+            ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=[threshold], colors='red', linewidths=2, transform=proj)
+
+        return []
+
+    ani = animation.FuncAnimation(fig, update, frames=valid_frames, blit=False)
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+    ani.save(output_path, writer='pillow', fps=fps)
+    plt.close()
+    print(f"✅ Saved animation for Z={z_km} km to {output_path}")

ash_animator/animation_vertical.py

@@ -0,0 +1,360 @@
+
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import matplotlib.ticker as mticker
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+import cartopy.io.shapereader as shpreader
+from .interpolation import interpolate_grid
+from .basemaps import draw_etopo_basemap
+
+# def animate_vertical_profile(animator, t_index: int, output_path: str, fps: int = 2, include_metadata: bool = True, threshold: float = 0.1):
+#     if not (0 <= t_index < len(animator.datasets)):
+#         print(f"Invalid time index {t_index}. Must be between 0 and {len(animator.datasets) - 1}.")
+#         return
+
+#     ds = animator.datasets[t_index]
+#     fig = plt.figure(figsize=(16, 7))
+#     proj = ccrs.PlateCarree()
+#     ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+#     ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+#     meta = ds.attrs
+#     legend_text = (
+#         f"Run name:         {meta.get('run_name', 'N/A')}\n"
+#         f"Run time:         {meta.get('run_time', 'N/A')}\n"
+#         f"Met data:         {meta.get('met_data', 'N/A')}\n"
+#         f"Start release:    {meta.get('start_of_release', 'N/A')}\n"
+#         f"End release:      {meta.get('end_of_release', 'N/A')}\n"
+#         f"Source strength:  {meta.get('source_strength', 'N/A')} g/s\n"
+#         f"Release loc:      {meta.get('release_location', 'N/A')}\n"
+#         f"Release height:   {meta.get('release_height', 'N/A')} m asl\n"
+#         f"Run duration:     {meta.get('run_duration', 'N/A')}"
+#     )
+
+#     valid_mask = np.stack([ds['ash_concentration'].values[z] for z in range(len(animator.levels))]).max(axis=0) > 0
+#     y_idx, x_idx = np.where(valid_mask)
+
+#     if y_idx.size == 0 or x_idx.size == 0:
+#         print(f"No valid data found for time T{t_index+1}. Skipping...")
+#         plt.close()
+#         return
+
+#     y_min, y_max = y_idx.min(), y_idx.max()
+#     x_min, x_max = x_idx.min(), x_idx.max()
+#     buffer_y = int((y_max - y_min) * 0.1)
+#     buffer_x = int((x_max - x_min) * 0.1)
+#     y_start = max(0, y_min - buffer_y)
+#     y_end = min(animator.lat_grid.shape[0], y_max + buffer_y + 1)
+#     x_start = max(0, x_min - buffer_x)
+#     x_end = min(animator.lon_grid.shape[1], x_max + buffer_x + 1)
+
+#     lat_zoom = animator.lats[y_start:y_end]
+#     lon_zoom = animator.lons[x_start:x_end]
+#     lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+
+#     z_indices_with_data = []
+#     for z_index in range(len(animator.levels)):
+#         data = ds['ash_concentration'].values[z_index]
+#         interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+#         if np.isfinite(interp).sum() > 0:
+#             z_indices_with_data.append(z_index)
+
+#     if not z_indices_with_data:
+#         print(f"No valid Z-levels at time T{t_index+1}.")
+#         plt.close()
+#         return
+
+#     def update(z_index):
+#         ax1.clear()
+#         ax2.clear()
+
+#         data = ds['ash_concentration'].values[z_index]
+#         interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+#         interp = np.where(interp < 0, np.nan, interp)
+#         zoom_plot = interp[y_start:y_end, x_start:x_end]
+
+#         valid_vals = interp[np.isfinite(interp)]
+#         if valid_vals.size == 0:
+#             return []
+
+#         min_val = np.nanmin(valid_vals)
+#         max_val = np.nanmax(valid_vals)
+#         log_cutoff = 1e-3
+#         use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+
+#         levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+#         data_for_plot = np.where(interp > log_cutoff, interp, 0) if use_log else interp
+#         scale_label = "Log" if use_log else "Linear"
+
+#         draw_etopo_basemap(ax1, mode='stock')
+#         draw_etopo_basemap(ax2, mode='stock')
+
+#         c1 = ax1.contourf(animator.lons, animator.lats, data_for_plot, levels=levels,
+#                         cmap="rainbow", alpha=0.6, transform=proj)
+#         ax1.set_title(f"T{t_index+1} | Alt: {animator.levels[z_index]} km (Full - {scale_label})")
+#         ax1.set_extent([animator.lons.min(), animator.lons.max(), animator.lats.min(), animator.lats.max()])
+#         ax1.coastlines(); ax1.add_feature(cfeature.BORDERS, linestyle=':')
+#         ax1.add_feature(cfeature.LAND); ax1.add_feature(cfeature.OCEAN)
+
+#         c2 = ax2.contourf(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+#                         cmap="rainbow", alpha=0.6, transform=proj)
+#         ax2.set_title(f"T{t_index+1} | Alt: {animator.levels[z_index]} km (Zoom - {scale_label})")
+#         ax2.set_extent([lon_zoom.min(), lon_zoom.max(), lat_zoom.min(), lat_zoom.max()])
+#         ax2.coastlines(); ax2.add_feature(cfeature.BORDERS, linestyle=':')
+#         ax2.add_feature(cfeature.LAND); ax2.add_feature(cfeature.OCEAN)
+
+#         for ax in [ax1, ax2]:
+#             ax.text(0.01, 0.98, f"Altitude: {animator.levels[z_index]:.2f} km", transform=ax.transAxes,
+#                     fontsize=9, color='white', va='top', ha='left',
+#                     bbox=dict(facecolor='black', alpha=0.4, boxstyle='round'))
+
+#             if include_metadata:
+#                 ax.text(0.01, 0.01,
+#                         f"Source: NAME\nRes: {animator.x_res:.2f}°\n{meta.get('run_name', 'N/A')}",
+#                         transform=ax.transAxes, fontsize=8, color='white',
+#                         bbox=dict(facecolor='black', alpha=0.5))
+
+#         if np.nanmax(valid_vals) > threshold:
+#             for ax in [ax1, ax2]:
+#                 ax.text(0.99, 0.01, f"⚠ Exceeds {threshold} g/m³!", transform=ax.transAxes,
+#                         ha='right', va='bottom', fontsize=10, color='red',
+#                         bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+#             ax1.contour(animator.lons, animator.lats, interp, levels=[threshold], colors='red', linewidths=2, transform=proj)
+#             ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=[threshold], colors='red', linewidths=2, transform=proj)
+
+#         if include_metadata and not hasattr(update, "legend_text"):
+#             ax1.annotate(legend_text, xy=(0.75, 0.99), xycoords='axes fraction',
+#                         fontsize=8, ha='left', va='top',
+#                         bbox=dict(boxstyle="round", facecolor="white", edgecolor="gray"))
+
+#         if not hasattr(update, "colorbar"):
+#             update.colorbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical',
+#                                         label="Ash concentration (g/m³)")
+#             formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+#             update.colorbar.ax.yaxis.set_major_formatter(formatter)
+
+#             if use_log:
+#                 update.colorbar.ax.text(1.05, 1.02, "log scale", transform=update.colorbar.ax.transAxes,
+#                                         fontsize=9, color='gray', rotation=90, ha='left', va='bottom')
+
+#         return []
+
+#     os.makedirs(os.path.dirname(output_path), exist_ok=True)
+#     ani = animation.FuncAnimation(fig, update, frames=z_indices_with_data, blit=False)
+#     ani.save(output_path, writer='pillow', fps=fps)
+#     plt.close()
+#     print(f"✅ Saved vertical profile animation for T{t_index+1} to {output_path}")
+
+# def animate_all_vertical_profiles(animator, output_folder: str, fps: int = 2, include_metadata: bool = True, threshold: float = 0.1):
+#     os.makedirs(output_folder, exist_ok=True)
+#     for t_index in range(len(animator.datasets)):
+#         output_path = os.path.join(output_folder, f"vertical_T{t_index+1:02d}.gif")
+#         print(f"🔄 Generating vertical profile animation for T{t_index+1}...")
+#         animate_vertical_profile(animator, t_index, output_path, fps, include_metadata, threshold)
+
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import matplotlib.ticker as mticker
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+import cartopy.io.shapereader as shpreader
+from .interpolation import interpolate_grid
+from .basemaps import draw_etopo_basemap
+from adjustText import adjust_text
+
+def animate_vertical_profile(animator, t_index: int, output_path: str, fps: int = 2,
+                             include_metadata: bool = True, threshold: float = 0.1,
+                             zoom_width_deg: float = 6.0, zoom_height_deg: float = 6.0):
+    if not (0 <= t_index < len(animator.datasets)):
+        print(f"Invalid time index {t_index}. Must be between 0 and {len(animator.datasets) - 1}.")
+        return
+
+    countries_shp = shpreader.natural_earth(resolution='110m', category='cultural', name='admin_0_countries')
+    reader = shpreader.Reader(countries_shp)
+    country_geoms = list(reader.records())
+   
+    ds = animator.datasets[t_index]
+    fig = plt.figure(figsize=(18, 7))  # Wider for metadata outside
+    proj = ccrs.PlateCarree()
+    ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+    ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+    meta = ds.attrs
+    legend_text = (
+        f"Run name:         {meta.get('run_name', 'N/A')}\n"
+        f"Run time:         {meta.get('run_time', 'N/A')}\n"
+        f"Met data:         {meta.get('met_data', 'N/A')}\n"
+        f"Start release:    {meta.get('start_of_release', 'N/A')}\n"
+        f"End release:      {meta.get('end_of_release', 'N/A')}\n"
+        f"Source strength:  {meta.get('source_strength', 'N/A')} g/s\n"
+        f"Release loc:      {meta.get('release_location', 'N/A')}\n"
+        f"Release height:   {meta.get('release_height', 'N/A')} m asl\n"
+        f"Run duration:     {meta.get('run_duration', 'N/A')}"
+    )
+
+    # 🔍 Find most active point at this time step
+    max_conc = -np.inf
+    center_lat = center_lon = None
+    for z in range(len(animator.levels)):
+        data = ds['ash_concentration'].values[z]
+        if np.max(data) > max_conc:
+            max_conc = np.max(data)
+            max_idx = np.unravel_index(np.argmax(data), data.shape)
+            center_lat = animator.lat_grid[max_idx]
+            center_lon = animator.lon_grid[max_idx]
+
+    if center_lat is None or center_lon is None:
+        print(f"No valid data found for time T{t_index+1}. Skipping...")
+        plt.close()
+        return
+
+    # 🌍 Define fixed zoom extents
+    lon_zoom_min = center_lon - zoom_width_deg / 2
+    lon_zoom_max = center_lon + zoom_width_deg / 2
+    lat_zoom_min = center_lat - zoom_height_deg / 2
+    lat_zoom_max = center_lat + zoom_height_deg / 2
+
+    lat_zoom = animator.lats[(animator.lats >= lat_zoom_min) & (animator.lats <= lat_zoom_max)]
+    lon_zoom = animator.lons[(animator.lons >= lon_zoom_min) & (animator.lons <= lon_zoom_max)]
+    lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+
+    z_indices_with_data = []
+    for z_index in range(len(animator.levels)):
+        data = ds['ash_concentration'].values[z_index]
+        interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+        if np.isfinite(interp).sum() > 0:
+            z_indices_with_data.append(z_index)
+
+    if not z_indices_with_data:
+        print(f"No valid Z-levels at time T{t_index+1}.")
+        plt.close()
+        return
+
+    def update(z_index):
+        ax1.clear()
+        ax2.clear()
+
+        data = ds['ash_concentration'].values[z_index]
+        interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+        interp = np.where(interp < 0, np.nan, interp)
+
+        lat_idx = np.where((animator.lats >= lat_zoom_min) & (animator.lats <= lat_zoom_max))[0]
+        lon_idx = np.where((animator.lons >= lon_zoom_min) & (animator.lons <= lon_zoom_max))[0]
+        zoom_plot = interp[np.ix_(lat_idx, lon_idx)]
+
+        valid_vals = interp[np.isfinite(interp)]
+        if valid_vals.size == 0:
+            return []
+
+        min_val = np.nanmin(valid_vals)
+        max_val = np.nanmax(valid_vals)
+        log_cutoff = 1e-3
+        use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+
+        levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+        data_for_plot = np.where(interp > log_cutoff, interp, 0) if use_log else interp
+        scale_label = "Log" if use_log else "Linear"
+
+        draw_etopo_basemap(ax1, mode='stock')
+        draw_etopo_basemap(ax2, mode='stock')
+
+        c1 = ax1.contourf(animator.lons, animator.lats, data_for_plot, levels=levels,
+                          cmap="rainbow", alpha=0.6, transform=proj)
+        ax1.set_title(f"T{t_index+1} | Alt: {animator.levels[z_index]} km (Full - {scale_label})")
+        ax1.set_extent([animator.lons.min(), animator.lons.max(), animator.lats.min(), animator.lats.max()])
+        ax1.coastlines(); ax1.add_feature(cfeature.BORDERS, linestyle=':')
+        ax1.add_feature(cfeature.LAND); ax1.add_feature(cfeature.OCEAN)
+
+        c2 = ax2.contourf(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=levels,
+                          cmap="rainbow", alpha=0.6, transform=proj)
+        ax2.set_title(f"T{t_index+1} | Alt: {animator.levels[z_index]} km (Zoom - {scale_label})")
+        ax2.set_extent([lon_zoom_min, lon_zoom_max, lat_zoom_min, lat_zoom_max])
+        ax2.coastlines(); ax2.add_feature(cfeature.BORDERS, linestyle=':')
+        ax2.add_feature(cfeature.LAND); ax2.add_feature(cfeature.OCEAN)
+
+        for ax in [ax1, ax2]:
+            ax.text(0.01, 0.98, f"Altitude: {animator.levels[z_index]:.2f} km", transform=ax.transAxes,
+                    fontsize=9, color='white', va='top', ha='left',
+                    bbox=dict(facecolor='black', alpha=0.4, boxstyle='round'))
+
+        if include_metadata:
+            fig.text(0.50, 0.1, legend_text, va='center', ha='left', fontsize=8,
+                     bbox=dict(facecolor='white', alpha=0.8, edgecolor='gray'),
+                     transform=fig.transFigure)
+
+        if np.nanmax(valid_vals) > threshold:
+            for ax in [ax1, ax2]:
+                ax.text(0.99, 0.01, f"⚠ Exceeds {threshold} g/m³!", transform=ax.transAxes,
+                        ha='right', va='bottom', fontsize=10, color='red',
+                        bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+            ax1.contour(animator.lons, animator.lats, interp, levels=[threshold], colors='red', linewidths=2, transform=proj)
+            ax2.contour(lon_zoom_grid, lat_zoom_grid, zoom_plot, levels=[threshold], colors='red', linewidths=2, transform=proj)
+
+        if not hasattr(update, "colorbar"):
+            update.colorbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical',
+                                           label="Ash concentration (g/m³)", shrink=0.75)
+            formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+            update.colorbar.ax.yaxis.set_major_formatter(formatter)
+
+            if use_log:
+                update.colorbar.ax.text(1.05, 1.02, "log scale", transform=update.colorbar.ax.transAxes,
+                                        fontsize=9, color='gray', rotation=90, ha='left', va='bottom')
+
+        ######################3
+        
+            
+        texts_ax1, texts_ax2 = [], []
+        for country in country_geoms:
+            name = country.attributes['NAME_LONG']
+            geom = country.geometry
+            try:
+                lon, lat = geom.centroid.x, geom.centroid.y
+                if (lon_zoom_min <= lon <= lon_zoom_max) and (lat_zoom_min <= lat <= lat_zoom_max):
+                    text = ax2.text(lon, lat, name, fontsize=6, transform=proj,
+                                    ha='center', va='center', color='white',
+                                    bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+                    texts_ax2.append(text)
+
+                if (animator.lons.min() <= lon <= animator.lons.max()) and (animator.lats.min() <= lat <= animator.lats.max()):
+                    text = ax1.text(lon, lat, name, fontsize=6, transform=proj,
+                                    ha='center', va='center', color='white',
+                                    bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+                    texts_ax1.append(text)
+            except:
+                continue
+
+        adjust_text(texts_ax1, ax=ax1, only_move={'points': 'y', 'text': 'y'},
+                    arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+        adjust_text(texts_ax2, ax=ax2, only_move={'points': 'y', 'text': 'y'},
+                    arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+        
+            
+            ############################################
+        
+        
+        
+        
+        return []
+
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+    ani = animation.FuncAnimation(fig, update, frames=z_indices_with_data, blit=False)
+    ani.save(output_path, writer='pillow', fps=fps)
+    plt.close()
+    print(f"✅ Saved vertical profile animation for T{t_index+1} to {output_path}")
+
+
+def animate_all_vertical_profiles(animator, output_folder: str, fps: int = 2,
+                                  include_metadata: bool = True, threshold: float = 0.1,
+                                  zoom_width_deg: float = 10.0, zoom_height_deg: float = 6.0):
+    os.makedirs(output_folder, exist_ok=True)
+    for t_index in range(len(animator.datasets)):
+        output_path = os.path.join(output_folder, f"vertical_T{t_index+1:02d}.gif")
+        print(f"🔄 Generating vertical profile animation for T{t_index+1}...")
+        animate_vertical_profile(animator, t_index, output_path, fps,
+                                 include_metadata, threshold,
+                                 zoom_width_deg, zoom_height_deg)

ash_animator/basemaps.py

@@ -0,0 +1,103 @@
+import os
+import hashlib
+import tempfile
+import contextily as ctx
+from mpl_toolkits.basemap import Basemap
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+from PIL import Image
+import matplotlib.pyplot as plt
+
+# Determine platform and fallback cache path
+def get_cache_dir(app_name):
+    if os.name == 'nt':
+        return os.path.join(os.getenv('LOCALAPPDATA', tempfile.gettempdir()), f"{app_name}_cache")
+    elif os.name == 'posix':
+        home_dir = os.path.expanduser("~")
+        if os.path.isdir(home_dir) and os.access(home_dir, os.W_OK):
+            return os.path.join(home_dir, f".{app_name}_cache")
+        else:
+            return os.path.join(tempfile.gettempdir(), f"{app_name}_cache")
+    else:
+        return os.path.join(tempfile.gettempdir(), f"{app_name}_cache")
+
+# Define cache directories
+CTX_TILE_CACHE_DIR = get_cache_dir("contextily")
+BASEMAP_TILE_CACHE_DIR = get_cache_dir("basemap")
+
+os.environ["XDG_CACHE_HOME"] = CTX_TILE_CACHE_DIR
+os.makedirs(CTX_TILE_CACHE_DIR, exist_ok=True)
+os.makedirs(BASEMAP_TILE_CACHE_DIR, exist_ok=True)
+
+def draw_etopo_basemap(ax, mode="basemap", zoom=11):
+    """
+    Draws a high-resolution basemap background on the provided Cartopy GeoAxes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes._subplots.AxesSubplot
+        The matplotlib Axes object (with Cartopy projection) to draw the map background on.
+
+    mode : str, optional
+        The basemap mode to use:
+        - "stock": Default stock image from Cartopy.
+        - "contextily": Web tile background (CartoDB Voyager), with caching.
+        - "basemap": High-resolution shaded relief using Basemap, with caching.
+        Default is "basemap".
+
+    zoom : int, optional
+        Tile zoom level (only for "contextily"). Higher = more detail. Default is 7.
+
+    Notes
+    -----
+    - Uses high resolution for Basemap (resolution='h') and saves figure at 300 DPI.
+    - Cached images are reused using extent-based hashing to avoid re-rendering.
+    - Basemap is deprecated; Cartopy with web tiles is recommended for new projects.
+    """
+    try:
+        if mode == "stock":
+            ax.stock_img()
+
+        elif mode == "contextily":
+            extent = ax.get_extent(crs=ccrs.PlateCarree())
+            ax.set_extent(extent, crs=ccrs.PlateCarree())
+            ctx.add_basemap(
+                ax,
+                crs=ccrs.PlateCarree(),
+                source=ctx.providers.CartoDB.Voyager,
+                zoom=zoom
+            )
+
+        elif mode == "basemap":
+            extent = ax.get_extent(crs=ccrs.PlateCarree())
+            extent_str = f"{extent[0]:.4f}_{extent[1]:.4f}_{extent[2]:.4f}_{extent[3]:.4f}"
+            cache_key = hashlib.md5(extent_str.encode()).hexdigest()
+            cache_file = os.path.join(BASEMAP_TILE_CACHE_DIR, f"{cache_key}_highres.png")
+
+            if os.path.exists(cache_file):
+                img = Image.open(cache_file)
+                ax.imshow(img, extent=extent, transform=ccrs.PlateCarree())
+            else:
+                temp_fig, temp_ax = plt.subplots(figsize=(12, 9),
+                                                 subplot_kw={'projection': ccrs.PlateCarree()})
+                temp_ax.set_extent(extent, crs=ccrs.PlateCarree())
+
+                m = Basemap(projection='cyl',
+                            llcrnrlon=extent[0], urcrnrlon=extent[1],
+                            llcrnrlat=extent[2], urcrnrlat=extent[3],
+                            resolution='f', ax=temp_ax)
+                m.shadedrelief()
+
+                temp_fig.savefig(cache_file, dpi=300, bbox_inches='tight', pad_inches=0)
+                plt.close(temp_fig)
+
+                img = Image.open(cache_file)
+                ax.imshow(img, extent=extent, transform=ccrs.PlateCarree())
+
+        else:
+            raise ValueError(f"Unsupported basemap mode: {mode}")
+
+    except Exception as e:
+        print(f"[Relief Error - {mode} mode]:", e)
+        ax.add_feature(cfeature.LAND)
+        ax.add_feature(cfeature.OCEAN)

ash_animator/converter.py

@@ -0,0 +1,279 @@
+
+
+# Re-defining the integrated class first
+import os
+import re
+import zipfile
+import numpy as np
+import xarray as xr
+from typing import List, Tuple
+import shutil
+
+
+import tempfile  # Added for safe temp directory usage
+
+class NAMEDataProcessor:
+    def __init__(self, output_root: str = None):
+        if output_root is None:
+            output_root = os.path.join(tempfile.gettempdir(), "name_outputs")
+        self.output_root = output_root
+        self.output_3d = os.path.join(self.output_root, "3D")
+        self.output_horizontal = os.path.join(self.output_root, "horizontal")
+        os.makedirs(self.output_3d, exist_ok=True)
+        os.makedirs(self.output_horizontal, exist_ok=True)
+        self.output_root = output_root
+        self.output_3d = os.path.join(self.output_root, "3D")
+        self.output_horizontal = os.path.join(self.output_root, "horizontal")
+        os.makedirs(self.output_3d, exist_ok=True)
+        os.makedirs(self.output_horizontal, exist_ok=True)
+
+    def _sanitize_key(self, key: str) -> str:
+        key = re.sub(r'\W+', '_', key)
+        if not key[0].isalpha():
+            key = f"attr_{key}"
+        return key
+
+    def _parse_metadata(self, lines: List[str]) -> dict:
+        metadata = {}
+        for line in lines:
+            if ":" in line:
+                key, value = line.split(":", 1)
+                clean_key = self._sanitize_key(key.strip().lower())
+                metadata[clean_key] = value.strip()
+
+        try:
+            metadata.update({
+                "x_origin": float(metadata["x_grid_origin"]),
+                "y_origin": float(metadata["y_grid_origin"]),
+                "x_size": int(metadata["x_grid_size"]),
+                "y_size": int(metadata["y_grid_size"]),
+                "x_res": float(metadata["x_grid_resolution"]),
+                "y_res": float(metadata["y_grid_resolution"]),
+            })
+        except KeyError as e:
+            raise ValueError(f"Missing required metadata field: {e}")
+        except ValueError as e:
+            raise ValueError(f"Invalid value in metadata: {e}")
+
+        if metadata["x_res"] == 0 or metadata["y_res"] == 0:
+            raise ZeroDivisionError("Grid resolution cannot be zero.")
+
+        return metadata
+
+    def _get_data_lines(self, lines: List[str]) -> List[str]:
+        idx = next(i for i, l in enumerate(lines) if l.strip() == "Fields:")
+        return lines[idx + 1:]
+
+    def _is_horizontal_file(self, filename: str) -> bool:
+        return "HorizontalField" in filename
+
+    def _convert_horizontal(self, filepath: str, output_filename: str) -> str:
+        with open(filepath, 'r') as f:
+            lines = f.readlines()
+
+        meta = self._parse_metadata(lines)
+        data_lines = self._get_data_lines(lines)
+
+        lons = np.round(np.arange(meta["x_origin"], meta["x_origin"] + meta["x_size"] * meta["x_res"], meta["x_res"]), 6)
+        lats = np.round(np.arange(meta["y_origin"], meta["y_origin"] + meta["y_size"] * meta["y_res"], meta["y_res"]), 6)
+
+        air_conc = np.zeros((meta["y_size"], meta["x_size"]), dtype=np.float32)
+        dry_depo = np.zeros((meta["y_size"], meta["x_size"]), dtype=np.float32)
+        wet_depo = np.zeros((meta["y_size"], meta["x_size"]), dtype=np.float32)
+
+        for line in data_lines:
+            parts = [p.strip().strip(',') for p in line.strip().split(',') if p.strip()]
+            if len(parts) >= 7 and parts[0].isdigit() and parts[1].isdigit():
+                try:
+                    x = int(parts[0]) - 1
+                    y = int(parts[1]) - 1
+                    air_val = float(parts[4])
+                    dry_val = float(parts[5])
+                    wet_val = float(parts[6])
+                    if 0 <= x < meta["x_size"] and 0 <= y < meta["y_size"]:
+                        air_conc[y, x] = air_val
+                        dry_depo[y, x] = dry_val
+                        wet_depo[y, x] = wet_val
+                except Exception:
+                    continue
+
+        ds = xr.Dataset(
+            {
+                "air_concentration": (['latitude', 'longitude'], air_conc),
+                "dry_deposition_rate": (['latitude', 'longitude'], dry_depo),
+                "wet_deposition_rate": (['latitude', 'longitude'], wet_depo)
+            },
+            coords={
+                "latitude": lats,
+                "longitude": lons
+            },
+            attrs={
+                "title": "Volcanic Ash Horizontal Output (Multiple Fields)",
+                "source": "NAME model output processed to NetCDF (horizontal multi-field)",
+                **{k: str(v) for k, v in meta.items()}
+            }
+        )
+
+        ds["air_concentration"].attrs.update({
+            "units": "g/m^3",
+            "long_name": "Boundary Layer Average Air Concentration"
+        })
+        ds["dry_deposition_rate"].attrs.update({
+            "units": "g/m^2/s",
+            "long_name": "Dry Deposition Rate"
+        })
+        ds["wet_deposition_rate"].attrs.update({
+            "units": "g/m^2/s",
+            "long_name": "Wet Deposition Rate"
+        })
+        ds["latitude"].attrs["units"] = "degrees_north"
+        ds["longitude"].attrs["units"] = "degrees_east"
+
+        out_path = os.path.join(self.output_horizontal, output_filename)
+        ds.to_netcdf(out_path, engine="netcdf4")
+
+        return out_path
+
+  
+    def _convert_3d_group(self, group: List[Tuple[int, str]], output_filename: str) -> str:
+        first_file_path = group[0][1]
+        with open(first_file_path, 'r') as f:
+            lines = f.readlines()
+        meta = self._parse_metadata(lines)
+
+        lons = np.round(np.arange(meta["x_origin"], meta["x_origin"] + meta["x_size"] * meta["x_res"], meta["x_res"]), 6)
+        lats = np.round(np.arange(meta["y_origin"], meta["y_origin"] + meta["y_size"] * meta["y_res"], meta["y_res"]), 6)
+
+        z_levels = []
+        z_coords = []
+
+        for z_idx, filepath in group:
+            with open(filepath, 'r') as f:
+                lines = f.readlines()
+            data_lines = self._get_data_lines(lines)
+            grid = np.zeros((meta["y_size"], meta["x_size"]), dtype=np.float32)
+
+            for line in data_lines:
+                parts = [p.strip().strip(',') for p in line.strip().split(',') if p.strip()]
+                if len(parts) >= 5 and parts[0].isdigit() and parts[1].isdigit():
+                    try:
+                        x = int(parts[0]) - 1
+                        y = int(parts[1]) - 1
+                        val = float(parts[4])
+                        if 0 <= x < meta["x_size"] and 0 <= y < meta["y_size"]:
+                            grid[y, x] = val
+                    except Exception:
+                        continue
+            z_levels.append(grid)
+            z_coords.append(z_idx)
+
+        z_cube = np.stack(z_levels, axis=0)
+        ds = xr.Dataset(
+            {
+                "ash_concentration": (['altitude', 'latitude', 'longitude'], z_cube)
+            },
+            coords={
+                "altitude": np.array(z_coords, dtype=np.float32),
+                "latitude": lats,
+                "longitude": lons
+            },
+            attrs={
+                "title": "Volcanic Ash Concentration (3D)",
+                "source": "NAME model output processed to NetCDF (3D fields)",
+                **{k: str(v) for k, v in meta.items()}
+            }
+        )
+
+        out_path = os.path.join(self.output_3d, output_filename)
+
+        # 🔥 Check if file exists, delete it first
+        # if os.path.exists(out_path):
+        #     os.remove(out_path)
+
+        # 🔥 Save NetCDF safely using netCDF4
+        ds.to_netcdf(out_path, engine="netcdf4")
+
+        return out_path
+
+
+    def batch_process_zip(self, zip_path: str) -> List[str]:
+        extract_dir = os.path.join(tempfile.gettempdir(), "unzipped_name_extract")
+
+        os.makedirs(extract_dir, exist_ok=True)
+        
+        ###
+        
+
+            # Function to empty folder contents
+        def empty_folder(folder_path):
+            import os
+            import glob
+            files = glob.glob(os.path.join(folder_path, '*'))
+            for f in files:
+                try:
+                    os.remove(f)
+                except IsADirectoryError:
+                    shutil.rmtree(f)
+
+        # 🛠 Clear cached open files and garbage collect before deleting
+        
+        # 🔥 Empty previous outputs, do not delete folders
+        if os.path.exists(self.output_3d):
+            empty_folder(self.output_3d)
+        else:
+            os.makedirs(self.output_3d, exist_ok=True)
+
+        # if os.path.exists(self.output_horizontal):
+        #     empty_folder(self.output_horizontal)
+        # else:
+        #     os.makedirs(self.output_horizontal, exist_ok=True)
+
+        # if os.path.exists(extract_dir):
+        #     shutil.rmtree(extract_dir)
+        # os.makedirs(extract_dir, exist_ok=True)
+
+        
+
+        
+        
+        #####
+
+        with zipfile.ZipFile(zip_path, 'r') as zip_ref:
+            zip_ref.extractall(extract_dir)
+
+        txt_files = []
+        for root, _, files in os.walk(extract_dir):
+            for file in files:
+                if file.endswith(".txt"):
+                    txt_files.append(os.path.join(root, file))
+
+        horizontal_files = []
+        grouped_3d = {}
+
+        pattern = re.compile(r"_T(\d+)_.*_Z(\d+)\.txt$")
+
+        for f in txt_files:
+            if self._is_horizontal_file(f):
+                horizontal_files.append(f)
+            else:
+                match = pattern.search(f)
+                if match:
+                    t = int(match.group(1))
+                    z = int(match.group(2))
+                    grouped_3d.setdefault(t, []).append((z, f))
+
+        nc_files = []
+
+        # Process horizontal
+        for f in sorted(horizontal_files):
+            base_name = os.path.splitext(os.path.basename(f))[0]
+            out_nc = self._convert_horizontal(f, f"{base_name}.nc")
+            nc_files.append(out_nc)
+
+        # Process 3D
+        for t_key in sorted(grouped_3d):
+            group = sorted(grouped_3d[t_key])
+            out_nc = self._convert_3d_group(group, f"T{t_key}.nc")
+            nc_files.append(out_nc)
+
+        return nc_files

ash_animator/export.py

@@ -0,0 +1,119 @@
+
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.ticker as mticker
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+from .interpolation import interpolate_grid
+from .basemaps import draw_etopo_basemap
+
+def export_frames_as_jpgs(animator, output_folder: str, include_metadata: bool = True):
+    os.makedirs(output_folder, exist_ok=True)
+
+    meta = animator.datasets[0].attrs
+    legend_text = (
+        f"Run name:           {meta.get('run_name', 'N/A')}\n"
+        f"Run time:           {meta.get('run_time', 'N/A')}\n"
+        f"Met data:           {meta.get('met_data', 'N/A')}\n"
+        f"Start of release:   {meta.get('start_of_release', 'N/A')}\n"
+        f"End of release:     {meta.get('end_of_release', 'N/A')}\n"
+        f"Source strength:    {meta.get('source_strength', 'N/A')} g / s\n"
+        f"Release location:   {meta.get('release_location', 'N/A')}\n"
+        f"Release height:     {meta.get('release_height', 'N/A')} m asl\n"
+        f"Run duration:       {meta.get('run_duration', 'N/A')}"
+    )
+
+    for z_index, z_val in enumerate(animator.levels):
+        z_dir = os.path.join(output_folder, f"ash_T1-Tn_Z{z_index+1}")
+        os.makedirs(z_dir, exist_ok=True)
+
+        valid_mask = np.stack([
+            ds['ash_concentration'].values[z_index] for ds in animator.datasets
+        ]).max(axis=0) > 0
+        y_idx, x_idx = np.where(valid_mask)
+
+        if y_idx.size == 0 or x_idx.size == 0:
+            print(f"Z level {z_val} km has no valid data. Skipping...")
+            continue
+
+        y_min, y_max = y_idx.min(), y_idx.max()
+        x_min, x_max = x_idx.min(), x_idx.max()
+
+        for t in range(len(animator.datasets)):
+            data = animator.datasets[t]['ash_concentration'].values[z_index]
+            interp = interpolate_grid(data, animator.lon_grid, animator.lat_grid)
+            if np.isfinite(interp).sum() == 0:
+                continue
+
+            fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(18, 8), subplot_kw={'projection': ccrs.PlateCarree()})
+            valid_vals = interp[np.isfinite(interp)]
+            min_val = np.nanmin(valid_vals)
+            max_val = np.nanmax(valid_vals)
+            log_cutoff = 1e-3
+            log_ratio = max_val / (min_val + 1e-6)
+            use_log = min_val > log_cutoff and log_ratio > 100
+
+            levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+            data_for_plot = np.where(interp > log_cutoff, interp, np.nan) if use_log else interp
+            scale_label = "Hybrid Log" if use_log else "Linear"
+
+            # Plot full
+            c1 = ax1.contourf(animator.lons, animator.lats, data_for_plot, levels=levels,
+                            cmap="rainbow", alpha=0.6, transform=ccrs.PlateCarree())
+            draw_etopo_basemap(ax1, mode='stock')
+            ax1.set_extent([animator.lons.min(), animator.lons.max(), animator.lats.min(), animator.lats.max()])
+            ax1.set_title(f"T{t+1} | Alt: {z_val} km (Full - {scale_label})")
+            ax1.coastlines(); ax1.add_feature(cfeature.BORDERS)
+            ax1.add_feature(cfeature.LAND); ax1.add_feature(cfeature.OCEAN)
+
+            # Zoom region
+            buffer_y = int((y_max - y_min) * 0.5)
+            buffer_x = int((x_max - x_min) * 0.5)
+
+            y_start = max(0, y_min - buffer_y)
+            y_end = min(data_for_plot.shape[0], y_max + buffer_y + 1)
+            x_start = max(0, x_min - buffer_x)
+            x_end = min(data_for_plot.shape[1], x_max + buffer_x + 1)
+
+            zoom = data_for_plot[y_start:y_end, x_start:x_end]
+            lon_zoom = animator.lons[x_start:x_end]
+            lat_zoom = animator.lats[y_start:y_end]
+
+            c2 = ax2.contourf(lon_zoom, lat_zoom, zoom, levels=levels,
+                            cmap="rainbow", alpha=0.6, transform=ccrs.PlateCarree())
+            draw_etopo_basemap(ax2, mode='stock')
+            ax2.set_extent([lon_zoom.min(), lon_zoom.max(), lat_zoom.min(), lat_zoom.max()])
+            ax2.set_title(f"T{t+1} | Alt: {z_val} km (Zoom - {scale_label})")
+            ax2.coastlines(); ax2.add_feature(cfeature.BORDERS)
+            ax2.add_feature(cfeature.LAND); ax2.add_feature(cfeature.OCEAN)
+
+            for ax in [ax1, ax2]:
+                ax.text(0.01, 0.98, f"Time step T{t+1}", transform=ax.transAxes,
+                        fontsize=9, color='white', va='top', ha='left',
+                        bbox=dict(facecolor='black', alpha=0.4, boxstyle='round'))
+
+            if include_metadata:
+                for ax in [ax1, ax2]:
+                    ax.text(0.01, 0.01,
+                            f"Source: NAME model\nRes: {animator.x_res:.2f}°\n{meta.get('run_name', 'N/A')}",
+                            transform=ax.transAxes, fontsize=8, color='white',
+                            bbox=dict(facecolor='black', alpha=0.5))
+                ax1.annotate(legend_text, xy=(0.75, 0.99), xycoords='axes fraction',
+                            fontsize=8, ha='left', va='top',
+                            bbox=dict(boxstyle="round", facecolor="white", edgecolor="gray"),
+                            annotation_clip=False)
+
+            cbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical', shrink=0.75, pad=0.03)
+            cbar.set_label("Ash concentration (g/m³)")
+            formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+            cbar.ax.yaxis.set_major_formatter(formatter)
+
+            if use_log:
+                cbar.ax.text(1.1, 1.02, "log scale", transform=cbar.ax.transAxes,
+                            fontsize=9, color='gray', rotation=90, ha='left', va='bottom')
+
+            frame_path = os.path.join(z_dir, f"frame_{t+1:04d}.jpg")
+            plt.savefig(frame_path, dpi=150, bbox_inches='tight')
+            plt.close(fig)
+            print(f"Saved {frame_path}")

ash_animator/interpolation.py

@@ -0,0 +1,14 @@
+
+import numpy as np
+from scipy.interpolate import griddata
+
+def interpolate_grid(data, lon_grid, lat_grid):
+    data = np.where(data < 0, np.nan, data)
+    mask = data > 0
+    if np.count_nonzero(mask) < 10:
+        return np.full_like(data, np.nan)
+    
+    points = np.column_stack((lon_grid[mask], lat_grid[mask]))
+    values = data[mask]
+    grid_z = griddata(points, values, (lon_grid, lat_grid), method='cubic')
+    return np.where(grid_z < 0, 0, grid_z)

ash_animator/plot_3dfield_data.py

@@ -0,0 +1,472 @@
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import matplotlib.ticker as mticker
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+import cartopy.io.shapereader as shpreader
+from adjustText import adjust_text
+from .interpolation import interpolate_grid
+from .basemaps import draw_etopo_basemap
+import imageio.v2 as imageio
+import shutil
+import tempfile
+
+class Plot_3DField_Data:
+    
+    """
+    A class for visualizing 3D spatiotemporal field data (e.g., ash concentration) across time and altitude levels.
+
+    This class uses matplotlib and cartopy to create:
+      - Animated GIFs of spatial fields at given altitudes
+      - Vertical profile animations over time
+      - Exported static frames with metadata annotations and zoomed views
+
+    Parameters
+    ----------
+    animator : object
+        A container holding the dataset, including:
+        - datasets: list of xarray-like DataArrays with 'ash_concentration'
+        - lons, lats: 1D longitude and latitude arrays
+        - lat_grid, lon_grid: 2D grid arrays for spatial mapping
+        - levels: 1D array of vertical altitude levels (e.g., in km)
+    output_dir : str
+        Base directory for saving all outputs. Defaults to "plots".
+    cmap : str
+        Matplotlib colormap name. Defaults to "rainbow".
+    fps : int
+        Frames per second for GIFs. Defaults to 2.
+    include_metadata : bool
+        Whether to annotate each figure with simulation metadata. Defaults to True.
+    threshold : float
+        Value threshold (e.g., in g/m³) to highlight exceedances. Defaults to 0.1.
+    zoom_width_deg : float
+        Width of the zoomed-in region in degrees. Defaults to 6.0.
+    zoom_height_deg : float
+        Height of the zoomed-in region in degrees. Defaults to 6.0.
+    zoom_level : int
+        Zoom level passed to basemap drawing. Defaults to 7.
+    basemap_type : str
+        Type of basemap to draw (passed to draw_etopo_basemap). Defaults to "basemap".
+
+    Methods
+    -------
+    plot_single_z_level(z_km, filename)
+        Generate animation over time at a specific altitude level.
+    
+    plot_vertical_profile_at_time(t_index, filename=None)
+        Generate vertical profile GIF for a single timestep.
+
+    animate_altitude(t_index, output_path)
+        Animate altitude slices for one timestep.
+
+    animate_all_altitude_profiles(output_folder='altitude_profiles')
+        Generate vertical animations for all time steps.
+
+    export_frames_as_jpgs(include_metadata=True)
+        Export individual frames as static `.jpg` images with annotations.
+    """
+    def __init__(self, animator, output_dir="plots", cmap="rainbow", fps=2,
+                 include_metadata=True, threshold=0.1,
+                 zoom_width_deg=6.0, zoom_height_deg=6.0, zoom_level=7, basemap_type="basemap"):
+        self.animator = animator
+        
+        self.output_dir = os.path.abspath(
+            os.path.join(
+                os.environ.get("NAME_OUTPUT_DIR", tempfile.gettempdir()),
+                output_dir
+            )
+        )
+        os.makedirs(self.output_dir, exist_ok=True)
+        self.cmap = cmap
+        self.fps = fps
+        self.include_metadata = include_metadata
+        self.threshold = threshold
+        self.zoom_width = zoom_width_deg
+        self.zoom_height = zoom_height_deg
+        shp = shpreader.natural_earth(resolution='110m', category='cultural', name='admin_0_countries')
+        self.country_geoms = list(shpreader.Reader(shp).records())
+        self.zoom_level=zoom_level
+        self.basemap_type=basemap_type
+        
+        #############3
+        
+            
+        # Load shapefile once
+        countries_shp = shpreader.natural_earth(
+            resolution='110m',
+            category='cultural',
+            name='admin_0_countries'
+        )
+        self.country_geoms = list(shpreader.Reader(countries_shp).records())
+
+        # Cache extent bounds
+        self.lon_min = np.min(self.animator.lons)
+        self.lon_max = np.max(self.animator.lons)
+        self.lat_min = np.min(self.animator.lats)
+        self.lat_max = np.max(self.animator.lats)
+        
+        #####################3
+        
+    def _make_dirs(self, path):
+        path = os.path.abspath(os.path.join(os.getcwd(), os.path.dirname(path)))
+        os.makedirs(path, exist_ok=True)
+
+    def _get_zoom_indices(self, center_lat, center_lon):
+        lon_min = center_lon - self.zoom_width / 2
+        lon_max = center_lon + self.zoom_width / 2
+        lat_min = center_lat - self.zoom_height / 2
+        lat_max = center_lat + self.zoom_height / 2
+        lat_idx = np.where((self.animator.lats >= lat_min) & (self.animator.lats <= lat_max))[0]
+        lon_idx = np.where((self.animator.lons >= lon_min) & (self.animator.lons <= lon_max))[0]
+        return lat_idx, lon_idx, lon_min, lon_max, lat_min, lat_max
+
+    def _get_max_concentration_location(self):
+        max_conc = -np.inf
+        center_lat = center_lon = None
+        for ds in self.animator.datasets:
+            for z in range(len(self.animator.levels)):
+                data = ds['ash_concentration'].values[z]
+                if np.max(data) > max_conc:
+                    max_conc = np.max(data)
+                    max_idx = np.unravel_index(np.argmax(data), data.shape)
+                    center_lat = self.animator.lat_grid[max_idx]
+                    center_lon = self.animator.lon_grid[max_idx]
+        return center_lat, center_lon
+
+    def _add_country_labels(self, ax, extent):
+        proj = ccrs.PlateCarree()
+        texts = []
+        for country in self.country_geoms:
+            name = country.attributes['NAME_LONG']
+            geom = country.geometry
+            try:
+                lon, lat = geom.centroid.x, geom.centroid.y
+                if extent[0] <= lon <= extent[1] and extent[2] <= lat <= extent[3]:
+                    text = ax.text(lon, lat, name, fontsize=6, transform=proj,
+                                   ha='center', va='center', color='white',
+                                   bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+                    texts.append(text)
+            except:
+                continue
+        adjust_text(texts, ax=ax, only_move={'points': 'y', 'text': 'y'},
+                    arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+
+    def _plot_frame(self, ax, data, lons, lats, title, levels, scale_label, proj):
+        draw_etopo_basemap(ax, mode=self.basemap_type, zoom=self.zoom_level)
+        c = ax.contourf(lons, lats, data, levels=levels, cmap=self.cmap, alpha=0.6, transform=proj)
+        ax.contour(lons, lats, data, levels=levels, colors='black', linewidths=0.5, transform=proj)
+        ax.set_title(title)
+        ax.set_extent([lons.min(), lons.max(), lats.min(), lats.max()])
+        ax.coastlines()
+        ax.add_feature(cfeature.BORDERS, linestyle=':')
+        ax.add_feature(cfeature.LAND)
+        ax.add_feature(cfeature.OCEAN)
+        return c
+
+ 
+
+#  metadata placement function and usage
+
+    def _draw_metadata_sidebar(self, fig, meta_dict):
+        lines = [
+        f"Run name:        {meta_dict.get('run_name', 'N/A')}",
+        f"Run time:        {meta_dict.get('run_time', 'N/A')}",
+        f"Met data:        {meta_dict.get('met_data', 'N/A')}",
+        f"Start release:   {meta_dict.get('start_of_release', 'N/A')}",
+        f"End release:     {meta_dict.get('end_of_release', 'N/A')}",
+        f"Source strength: {meta_dict.get('source_strength', 'N/A')} g/s",
+        f"Release loc:     {meta_dict.get('release_location', 'N/A')}",
+        f"Release height:  {meta_dict.get('release_height', 'N/A')} m asl",
+        f"Run duration:    {meta_dict.get('run_duration', 'N/A')}"
+    ]
+        full_text = "\n".join(lines)  # ✅ actual newlines
+        fig.text(0.1, 0.095, full_text, va='center', ha='left',
+                fontsize=9, family='monospace', color='black',
+                bbox=dict(facecolor='white', alpha=0.8, edgecolor='gray'))
+
+
+
+    def plot_single_z_level(self, z_km, filename="z_level.gif"):
+       
+        if z_km not in self.animator.levels:
+            print(f"Z level {z_km} km not found.")
+            return
+        z_index = np.where(self.animator.levels == z_km)[0][0]
+        output_path = os.path.join(self.output_dir, "z_levels", filename)
+        fig = plt.figure(figsize=(16, 8))
+        proj = ccrs.PlateCarree()
+        ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+        ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+        center_lat, center_lon = self._get_max_concentration_location()
+        lat_idx, lon_idx, lon_min, lon_max, lat_min, lat_max = self._get_zoom_indices(center_lat, center_lon)
+        lat_zoom = self.animator.lats[lat_idx]
+        lon_zoom = self.animator.lons[lon_idx]
+        lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+        
+       
+
+        meta = self.animator.datasets[0].attrs
+        valid_frames = []
+        for t in range(len(self.animator.datasets)):
+            interp = interpolate_grid(self.animator.datasets[t]['ash_concentration'].values[z_index],
+                                      self.animator.lon_grid, self.animator.lat_grid)
+            if np.isfinite(interp).sum() > 0:
+                valid_frames.append(t)
+        if not valid_frames:
+            print(f"No valid frames for Z={z_km} km.")
+            plt.close()
+            return
+
+        def update(t):
+            ax1.clear()
+            ax2.clear()
+
+            data = self.animator.datasets[t]['ash_concentration'].values[z_index]
+            interp = interpolate_grid(data, self.animator.lon_grid, self.animator.lat_grid)
+            interp = np.where(interp < 0, np.nan, interp)
+            zoom_plot = interp[np.ix_(lat_idx, lon_idx)]
+
+            valid_vals = interp[np.isfinite(interp)]
+            if valid_vals.size == 0:
+                return []
+
+            min_val, max_val = np.nanmin(valid_vals), np.nanmax(valid_vals)
+            log_cutoff = 1e-3
+            use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+
+            levels = (
+                np.logspace(np.log10(log_cutoff), np.log10(max_val), 20)
+                if use_log else
+                np.linspace(0, max_val, 20)
+            )
+            data_for_plot = np.where(interp > log_cutoff, interp, np.nan) if use_log else interp
+            scale_label = "Log" if use_log else "Linear"
+
+            c = self._plot_frame(ax1, data_for_plot, self.animator.lons, self.animator.lats,
+                                f"T{t+1} | Alt: {z_km} km (Full - {scale_label})", levels, scale_label, proj)
+            self._plot_frame(ax2, zoom_plot, lon_zoom, lat_zoom,
+                            f"T{t} | Alt: {z_km} km (Zoom - {scale_label})", levels, scale_label, proj)
+
+            self._add_country_labels(ax1, [self.animator.lons.min(), self.animator.lons.max(),
+                                        self.animator.lats.min(), self.animator.lats.max()])
+            self._add_country_labels(ax2, [lon_min, lon_max, lat_min, lat_max])
+
+            if not hasattr(update, "colorbar"):
+                update.colorbar = fig.colorbar(c, ax=[ax1, ax2], orientation='vertical',
+                                            label="Ash concentration (g/m³)")
+                formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+                update.colorbar.ax.yaxis.set_major_formatter(formatter)
+
+            # ✅ Draw threshold outline and label only if exceeded
+            if np.nanmax(valid_vals) > self.threshold:
+                ax1.contour(self.animator.lons, self.animator.lats, interp, levels=[self.threshold],
+                            colors='red', linewidths=2, transform=proj)
+                ax2.contour(lon_zoom, lat_zoom, zoom_plot, levels=[self.threshold],
+                            colors='red', linewidths=2, transform=proj)
+                ax2.text(0.99, 0.01, f"⚠ Max Thresold Exceed: {np.nanmax(valid_vals):.2f} > {self.threshold} g/m³",
+                        transform=ax2.transAxes, ha='right', va='bottom',
+                        fontsize=9, color='red',
+                        bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+
+            return []
+
+  
+
+
+        self._draw_metadata_sidebar(fig, meta)
+        self._make_dirs(output_path)
+        fig.tight_layout()
+        ani = animation.FuncAnimation(fig, update, frames=valid_frames, blit=False, cache_frame_data =False)
+        ani.save(output_path, writer='pillow', fps=self.fps, dpi=300)
+        plt.close()
+        print(f"✅ Saved Z-level animation to {output_path}")
+
+    def plot_vertical_profile_at_time(self, t_index, filename=None):
+        time_label = f"T{t_index+1}"
+        for z_index, z_val in enumerate(self.animator.levels):
+            filename = f"TimeSlices_Z{z_val:.1f}km.gif"
+            self.plot_single_z_level(z_val, filename=os.path.join("vertical_profiles_timeSlice", filename))
+
+    
+    ################################################
+    
+    
+    
+    def animate_altitude(self, t_index: int, output_path: str):
+        if not (0 <= t_index < len(self.animator.datasets)):
+            print(f"Invalid time index {t_index}. Must be between 0 and {len(self.animator.datasets) - 1}.")
+        
+
+        ds = self.animator.datasets[t_index]
+        fig = plt.figure(figsize=(18, 7))
+        proj = ccrs.PlateCarree()
+        ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+        ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+        meta = ds.attrs
+        center_lat, center_lon = self._get_max_concentration_location()
+        if center_lat is None or center_lon is None:
+            print(f"No valid data found for time T{t_index + 1}. Skipping...")
+            plt.close()
+            return
+
+        lat_idx, lon_idx, lon_min, lon_max, lat_min, lat_max = self._get_zoom_indices(center_lat, center_lon)
+        lat_zoom = self.animator.lats[lat_idx]
+        lon_zoom = self.animator.lons[lon_idx]
+        lon_zoom_grid, lat_zoom_grid = np.meshgrid(lon_zoom, lat_zoom)
+
+        z_indices_with_data = []
+        for z_index in range(len(self.animator.levels)):
+            data = ds['ash_concentration'].values[z_index]
+            interp = interpolate_grid(data, self.animator.lon_grid, self.animator.lat_grid)
+            if np.isfinite(interp).sum() > 0:
+                z_indices_with_data.append(z_index)
+
+        if not z_indices_with_data:
+            print(f"No valid Z-levels at time T{t_index + 1}.")
+            plt.close()
+            return
+
+        def update(z_index):
+            ax1.clear()
+            ax2.clear()
+
+            data = ds['ash_concentration'].values[z_index]
+            interp = interpolate_grid(data, self.animator.lon_grid, self.animator.lat_grid)
+            interp = np.where(interp < 0, np.nan, interp)
+            zoom_plot = interp[np.ix_(lat_idx, lon_idx)]
+
+            valid_vals = interp[np.isfinite(interp)]
+            if valid_vals.size == 0:
+                return []
+
+            min_val, max_val = np.nanmin(valid_vals), np.nanmax(valid_vals)
+            log_cutoff = 1e-3
+            use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+
+            levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+            data_for_plot = np.where(interp > log_cutoff, interp, np.nan) if use_log else interp
+            scale_label = "Log" if use_log else "Linear"
+
+            title1 = f"T{t_index + 1} | Alt: {self.animator.levels[z_index]} km (Full - {scale_label})"
+            title2 = f"T{t_index + 1} | Alt: {self.animator.levels[z_index]} km (Zoom - {scale_label})"
+
+            c1 = self._plot_frame(ax1, data_for_plot, self.animator.lons, self.animator.lats, title1, levels, scale_label, proj)
+            self._plot_frame(ax2, zoom_plot, lon_zoom, lat_zoom, title2, levels, scale_label, proj)
+
+            self._add_country_labels(ax1, [self.lon_min, self.lon_max, self.lat_min, self.lat_max])
+            self._add_country_labels(ax2, [lon_min, lon_max, lat_min, lat_max])
+
+            if self.include_metadata:
+                self._draw_metadata_sidebar(fig, meta)
+
+            if not hasattr(update, "colorbar"):
+                update.colorbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical',
+                                                label="Ash concentration (g/m³)", shrink=0.75)
+                formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+                update.colorbar.ax.yaxis.set_major_formatter(formatter)
+
+            if np.nanmax(valid_vals) > self.threshold:
+                ax1.contour(self.animator.lons, self.animator.lats, interp, levels=[self.threshold],
+                            colors='red', linewidths=2, transform=proj)
+                ax2.contour(lon_zoom, lat_zoom, zoom_plot, levels=[self.threshold],
+                            colors='red', linewidths=2, transform=proj)
+
+            
+                ax2.text(0.99, 0.01, f"⚠ Max Thresold Exceed: {np.nanmax(valid_vals):.2f} > {self.threshold} g/m³",
+                            transform=ax2.transAxes, ha='right', va='bottom',
+                            fontsize=9, color='red',
+                            bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+            return []
+
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        #fig.set_size_inches(18, 7)
+        fig.tight_layout(rect=[0.02, 0.02, 0.98, 0.98])
+        ani = animation.FuncAnimation(fig, update, frames=z_indices_with_data, blit=False, cache_frame_data =False)
+        ani.save(output_path, writer='pillow', fps=self.fps, dpi=300)
+        plt.close()
+        print(f"✅ Saved vertical profile animation for T{t_index + 1} to {output_path}")
+
+
+
+    def animate_all_altitude_profiles(self, output_folder='altitude_profiles'):
+        output_folder = os.path.join(self.output_dir, "altitude_profiles")
+        os.makedirs(output_folder, exist_ok=True)
+        for t_index in range(len(self.animator.datasets)):
+            output_path = os.path.join(output_folder, f"vertical_T{t_index + 1:02d}.gif")
+            print(f"🔄 Generating vertical profile animation for T{t_index + 1}...")
+            self.animate_altitude(t_index, output_path)
+
+            
+    
+
+
+    
+    def export_frames_as_jpgs(self, include_metadata: bool = True):
+        output_folder = os.path.join(self.output_dir, "frames")
+        os.makedirs(output_folder, exist_ok=True)
+        meta = self.animator.datasets[0].attrs
+        legend_text = "\\n".join([
+            f"Run name:        {meta.get('run_name', 'N/A')}",
+            f"Run time:        {meta.get('run_time', 'N/A')}",
+            f"Met data:        {meta.get('met_data', 'N/A')}",
+            f"Start release:   {meta.get('start_of_release', 'N/A')}",
+            f"End release:     {meta.get('end_of_release', 'N/A')}",
+            f"Strength:        {meta.get('source_strength', 'N/A')} g/s",
+            f"Location:        {meta.get('release_location', 'N/A')}",
+            f"Height:          {meta.get('release_height', 'N/A')} m asl",
+            f"Duration:        {meta.get('run_duration', 'N/A')}"
+        ])
+        for z_index, z_val in enumerate(self.animator.levels):
+            z_dir = os.path.join(output_folder, f"Z{z_val:.1f}km")
+            os.makedirs(z_dir, exist_ok=True)
+            for t in range(len(self.animator.datasets)):
+                data = self.animator.datasets[t]['ash_concentration'].values[z_index]
+                interp = interpolate_grid(data, self.animator.lon_grid, self.animator.lat_grid)
+                if not np.isfinite(interp).any():
+                    continue
+                fig = plt.figure(figsize=(16, 8))
+                proj = ccrs.PlateCarree()
+                ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+                ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+                valid_vals = interp[np.isfinite(interp)]
+                min_val, max_val = np.nanmin(valid_vals), np.nanmax(valid_vals)
+                log_cutoff = 1e-3
+                use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+                levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+                data_for_plot = np.where(interp > log_cutoff, interp, np.nan) if use_log else interp
+                scale_label = "Log" if use_log else "Linear"
+                center_lat, center_lon = self._get_max_concentration_location()
+                lat_idx, lon_idx, lon_min, lon_max, lat_min, lat_max = self._get_zoom_indices(center_lat, center_lon)
+                zoom_plot = interp[np.ix_(lat_idx, lon_idx)]
+                lon_zoom = self.animator.lons[lon_idx]
+                lat_zoom = self.animator.lats[lat_idx]
+                c1 = self._plot_frame(ax1, data_for_plot, self.animator.lons, self.animator.lats,
+                                      f"T{t+1} | Alt: {z_val} km (Full - {scale_label})", levels, scale_label, proj)
+                self._plot_frame(ax2, zoom_plot, lon_zoom, lat_zoom,
+                                 f"T{t+1} | Alt: {z_val} km (Zoom - {scale_label})", levels, scale_label, proj)
+                self._add_country_labels(ax1, [self.animator.lons.min(), self.animator.lons.max(),
+                                               self.animator.lats.min(), self.animator.lats.max()])
+                self._add_country_labels(ax2, [lon_min, lon_max, lat_min, lat_max])
+                if np.nanmax(valid_vals) > self.threshold:
+                    ax1.contour(self.animator.lons, self.animator.lats, interp, levels=[self.threshold],
+                                colors='red', linewidths=2, transform=proj)
+                    ax2.contour(lon_zoom, lat_zoom, zoom_plot, levels=[self.threshold],
+                                colors='red', linewidths=2, transform=proj)
+                    ax2.text(0.99, 0.01, f"⚠ Max: {np.nanmax(valid_vals):.2f} > {self.threshold} g/m³",
+                             transform=ax2.transAxes, ha='right', va='bottom',
+                             fontsize=9, color='red',
+                             bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+                if include_metadata:
+                    self._draw_metadata_sidebar(fig, meta)
+                cbar = fig.colorbar(c1, ax=[ax1, ax2], orientation='vertical', shrink=0.75, pad=0.03)
+                cbar.set_label("Ash concentration (g/m³)")
+                formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+                cbar.ax.yaxis.set_major_formatter(formatter)
+                frame_path = os.path.join(z_dir, f"frame_{t+1:04d}.jpg")
+                plt.savefig(frame_path, bbox_inches='tight')
+                plt.close(fig)
+                print(f"📸 Saved {frame_path}")

ash_animator/plot_horizontal_data.py

@@ -0,0 +1,288 @@
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import matplotlib.ticker as mticker
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+import cartopy.io.shapereader as shpreader
+from adjustText import adjust_text
+from ash_animator.interpolation import interpolate_grid
+from ash_animator.basemaps import draw_etopo_basemap
+import tempfile
+
+class Plot_Horizontal_Data:
+    def __init__(self, animator, output_dir="plots", cmap="rainbow", fps=2,
+                 include_metadata=True, threshold=0.1,
+                 zoom_width_deg=6.0, zoom_height_deg=6.0, zoom_level=7, static_frame_export=False):
+        self.animator = animator
+                
+        self.output_dir = os.path.abspath(
+            os.path.join(
+                os.environ.get("NAME_OUTPUT_DIR", tempfile.gettempdir()),
+                output_dir
+            )
+        )
+        os.makedirs(self.output_dir, exist_ok=True)
+        self.cmap = cmap
+        self.fps = fps
+        self.include_metadata = include_metadata
+        self.threshold = threshold
+        self.zoom_width = zoom_width_deg
+        self.zoom_height = zoom_height_deg
+        shp = shpreader.natural_earth(resolution='110m', category='cultural', name='admin_0_countries')
+        self.country_geoms = list(shpreader.Reader(shp).records())
+        self.interpolate_grid= interpolate_grid
+        self._draw_etopo_basemap=draw_etopo_basemap
+        self.zoom_level=zoom_level
+        self.static_frame_export=static_frame_export
+
+    def _make_dirs(self, path):
+        os.makedirs(os.path.abspath(os.path.join(os.getcwd(), os.path.dirname(path))), exist_ok=True)
+
+    def _get_max_concentration_location(self, field):
+        max_val = -np.inf
+        lat = lon = None
+        for ds in self.animator.datasets:
+            data = ds[field].values
+            if np.max(data) > max_val:
+                max_val = np.max(data)
+                idx = np.unravel_index(np.argmax(data), data.shape)
+                lat = self.animator.lat_grid[idx]
+                lon = self.animator.lon_grid[idx]
+        return lat, lon
+
+    def _get_zoom_indices(self, center_lat, center_lon):
+        lon_min = center_lon - self.zoom_width / 2
+        lon_max = center_lon + self.zoom_width / 2
+        lat_min = center_lat - self.zoom_height / 2
+        lat_max = center_lat + self.zoom_height / 2
+        lat_idx = np.where((self.animator.lats >= lat_min) & (self.animator.lats <= lat_max))[0]
+        lon_idx = np.where((self.animator.lons >= lon_min) & (self.animator.lons <= lon_max))[0]
+        return lat_idx, lon_idx, lon_min, lon_max, lat_min, lat_max
+
+    def _add_country_labels(self, ax, extent):
+        proj = ccrs.PlateCarree()
+        texts = []
+        for country in self.country_geoms:
+            name = country.attributes['NAME_LONG']
+            geom = country.geometry
+            try:
+                lon, lat = geom.centroid.x, geom.centroid.y
+                if extent[0] <= lon <= extent[1] and extent[2] <= lat <= extent[3]:
+                    text = ax.text(lon, lat, name, fontsize=6, transform=proj,
+                                   ha='center', va='center', color='white',
+                                   bbox=dict(facecolor='black', alpha=0.5, linewidth=0))
+                    texts.append(text)
+            except:
+                continue
+        adjust_text(texts, ax=ax, only_move={'points': 'y', 'text': 'y'},
+                    arrowprops=dict(arrowstyle="->", color='white', lw=0.5))
+
+    def _draw_metadata_sidebar(self, fig, meta_dict):
+        lines = [
+        f"Run name:        {meta_dict.get('run_name', 'N/A')}",
+        f"Run time:        {meta_dict.get('run_time', 'N/A')}",
+        f"Met data:        {meta_dict.get('met_data', 'N/A')}",
+        f"Start release:   {meta_dict.get('start_of_release', 'N/A')}",
+        f"End release:     {meta_dict.get('end_of_release', 'N/A')}",
+        f"Source strength: {meta_dict.get('source_strength', 'N/A')} g/s",
+        f"Release loc:     {meta_dict.get('release_location', 'N/A')}",
+        f"Release height:  {meta_dict.get('release_height', 'N/A')} m asl",
+        f"Run duration:    {meta_dict.get('run_duration', 'N/A')}"
+        ]
+
+        # Split into two columns
+        mid = len(lines) // 2 + len(lines) % 2
+        left_lines = lines[:mid]
+        right_lines = lines[mid:]
+
+        left_text = "\n".join(left_lines)
+        right_text = "\n".join(right_lines)
+
+        # right column
+        fig.text(0.05, 0.05, left_text, va='bottom', ha='left',
+                fontsize=9, family='monospace', color='black',
+                bbox=dict(facecolor='white', alpha=0.8, edgecolor='gray'))
+
+        # left column
+        fig.text(0.3, 0.05, right_text, va='bottom', ha='left',
+                fontsize=9, family='monospace', color='black',
+                bbox=dict(facecolor='white', alpha=0.8, edgecolor='gray'))
+
+    
+    
+
+
+    def _plot_frame(self, ax, data, lons, lats, title, levels, scale_label, proj):
+        self._draw_etopo_basemap(ax, mode='basemap', zoom=self.zoom_level)
+        c = ax.contourf(lons, lats, data, levels=levels, cmap=self.cmap, alpha=0.6, transform=proj)
+        ax.set_title(title)
+        ax.set_extent([lons.min(), lons.max(), lats.min(), lats.max()])
+        ax.coastlines()
+        ax.add_feature(cfeature.BORDERS, linestyle=':')
+        ax.add_feature(cfeature.LAND)
+        ax.add_feature(cfeature.OCEAN)
+        return c
+
+    def get_available_2d_fields(self):
+        ds = self.animator.datasets[0]
+        return [v for v in ds.data_vars if ds[v].ndim == 2]
+
+    def plot_single_field_over_time(self, field, filename="field.gif"):
+        output_path = os.path.join(self.output_dir, "2d_fields", field, filename)
+        meta = self.animator.datasets[0].attrs
+        center_lat, center_lon = self._get_max_concentration_location(field)
+        lat_idx, lon_idx, lon_min, lon_max, lat_min, lat_max = self._get_zoom_indices(center_lat, center_lon)
+        lat_zoom = self.animator.lats[lat_idx]
+        lon_zoom = self.animator.lons[lon_idx]
+
+        valid_frames = []
+        for t in range(len(self.animator.datasets)):
+            data = self.animator.datasets[t][field].values
+            interp = self.interpolate_grid(data, self.animator.lon_grid, self.animator.lat_grid)
+            if np.isfinite(interp).sum() > 0:
+                valid_frames.append(t)
+
+        if not valid_frames:
+            print(f"No valid frames to plot for field '{field}'.")
+            return
+
+        fig = plt.figure(figsize=(16, 8))
+        proj = ccrs.PlateCarree()
+        ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+        ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+
+        def update(t):
+            ax1.clear()
+            ax2.clear()
+            data = self.animator.datasets[t][field].values
+            interp = self.interpolate_grid(data, self.animator.lon_grid, self.animator.lat_grid)
+            zoom = interp[np.ix_(lat_idx, lon_idx)]
+            valid = interp[np.isfinite(interp)]
+            if valid.size == 0:
+                return []
+
+            min_val, max_val = np.nanmin(valid), np.nanmax(valid)
+            log_cutoff = 1e-3
+            use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+            levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+            plot_data = np.where(interp > log_cutoff, interp, np.nan) if use_log else interp
+            scale_label = "Log" if use_log else "Linear"
+
+            c = self._plot_frame(ax1, plot_data, self.animator.lons, self.animator.lats,
+                                 f"T{t+1} | {field} (Full - {scale_label})", levels, scale_label, proj)
+            self._plot_frame(ax2, zoom, lon_zoom, lat_zoom,
+                             f"T{t+1} | {field} (Zoom - {scale_label})", levels, scale_label, proj)
+
+            self._add_country_labels(ax1, [self.animator.lons.min(), self.animator.lons.max(),
+                                           self.animator.lats.min(), self.animator.lats.max()])
+            self._add_country_labels(ax2, [lon_min, lon_max, lat_min, lat_max])
+
+           # Inside update() function:
+            if not hasattr(update, "colorbar"):
+                unit_label =  f"{field}:({self.animator.datasets[0][field].attrs.get('units', field)})" #self.animator.datasets[0][field].attrs.get('units', field)
+                update.colorbar = fig.colorbar(c, ax=[ax1, ax2], orientation='vertical', label=unit_label)
+                formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+                update.colorbar.ax.yaxis.set_major_formatter(formatter)
+
+            
+            if np.nanmax(valid) > self.threshold:
+                ax1.contour(self.animator.lons, self.animator.lats, interp, levels=[self.threshold],
+                        colors='red', linewidths=2, transform=proj)
+                ax2.contour(lon_zoom, lat_zoom, zoom, levels=[self.threshold],
+                            colors='red', linewidths=2, transform=proj)
+                ax2.text(0.99, 0.01, f"⚠ Max Thresold Exceed: {np.nanmax(valid):.2f} > {self.threshold}",
+                        transform=ax2.transAxes, ha='right', va='bottom',
+                        fontsize=9, color='red',
+                        bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+
+            if self.static_frame_export:
+                frame_folder = os.path.join(self.output_dir, "frames", field)
+            os.makedirs(frame_folder, exist_ok=True)
+            frame_path = os.path.join(frame_folder, f"frame_{t+1:04d}.jpg")
+            plt.savefig(frame_path, bbox_inches='tight')
+            print(f"🖼️ Saved static frame: {frame_path}")
+                    
+            return []
+
+        if self.include_metadata:
+            self._draw_metadata_sidebar(fig, meta)
+
+        self._make_dirs(output_path)
+        fig.tight_layout()
+        ani = animation.FuncAnimation(fig, update, frames=valid_frames, blit=False, cache_frame_data =False)
+        ani.save(output_path, writer='pillow', fps=self.fps)
+        plt.close()
+        print(f"✅ Saved enhanced 2D animation for {field} to {output_path}")
+
+    # def export_frames_as_jpgs(self, fields=None, include_metadata=True):
+    #     all_fields = self.get_available_2d_fields()
+    #     if fields:
+    #         fields = [f for f in fields if f in all_fields]
+    #     else:
+    #         fields = all_fields
+
+    #     meta = self.animator.datasets[0].attrs
+
+    #     for field in fields:
+    #         print(f"📤 Exporting frames for field: {field}")
+    #         output_folder = os.path.join(self.output_dir, "frames", field)
+    #         os.makedirs(output_folder, exist_ok=True)
+
+    #         center_lat, center_lon = self._get_max_concentration_location(field)
+    #         lat_idx, lon_idx, lon_min, lon_max, lat_min, lat_max = self._get_zoom_indices(center_lat, center_lon)
+    #         lat_zoom = self.animator.lats[lat_idx]
+    #         lon_zoom = self.animator.lons[lon_idx]
+
+    #         for t, ds in enumerate(self.animator.datasets):
+    #             data = ds[field].values
+    #             interp = self.interpolate_grid(data, self.animator.lon_grid, self.animator.lat_grid)
+    #             if not np.isfinite(interp).any():
+    #                 continue
+
+    #             fig = plt.figure(figsize=(16, 8))
+    #             proj = ccrs.PlateCarree()
+    #             ax1 = fig.add_subplot(1, 2, 1, projection=proj)
+    #             ax2 = fig.add_subplot(1, 2, 2, projection=proj)
+    #             zoom = interp[np.ix_(lat_idx, lon_idx)]
+    #             valid = interp[np.isfinite(interp)]
+    #             min_val, max_val = np.nanmin(valid), np.nanmax(valid)
+    #             log_cutoff = 1e-3
+    #             use_log = min_val > log_cutoff and (max_val / (min_val + 1e-6)) > 100
+    #             levels = np.logspace(np.log10(log_cutoff), np.log10(max_val), 20) if use_log else np.linspace(0, max_val, 20)
+    #             plot_data = np.where(interp > log_cutoff, interp, np.nan) if use_log else interp
+    #             scale_label = "Log" if use_log else "Linear"
+
+    #             c = self._plot_frame(ax1, plot_data, self.animator.lons, self.animator.lats,
+    #                                 f"T{t+1} | {field} (Full - {scale_label})", levels, scale_label, proj)
+    #             self._plot_frame(ax2, zoom, lon_zoom, lat_zoom,
+    #                             f"T{t+1} | {field} (Zoom - {scale_label})", levels, scale_label, proj)
+
+    #             self._add_country_labels(ax1, [self.animator.lons.min(), self.animator.lons.max(),
+    #                                         self.animator.lats.min(), self.animator.lats.max()])
+    #             self._add_country_labels(ax2, [lon_min, lon_max, lat_min, lat_max])
+
+    #             if include_metadata:
+    #                 self._draw_metadata_sidebar(fig, meta)
+
+    #             cbar = fig.colorbar(c, ax=[ax1, ax2], orientation='vertical', shrink=0.75, pad=0.03)
+    #             unit_label = f"{field}:({self.animator.datasets[0][field].attrs.get('units', field)})"
+    #             cbar.set_label(unit_label)
+    #             formatter = mticker.FuncFormatter(lambda x, _: f'{x:.2g}')
+    #             cbar.ax.yaxis.set_major_formatter(formatter)
+
+    #             if np.nanmax(valid) > self.threshold:
+    #                 ax1.contour(self.animator.lons, self.animator.lats, interp, levels=[self.threshold],
+    #                             colors='red', linewidths=2, transform=proj)
+    #                 ax2.contour(lon_zoom, lat_zoom, zoom, levels=[self.threshold],
+    #                             colors='red', linewidths=2, transform=proj)
+    #                 ax2.text(0.99, 0.01, f"⚠ Max: {np.nanmax(valid):.2f} > {self.threshold}",
+    #                         transform=ax2.transAxes, ha='right', va='bottom',
+    #                         fontsize=9, color='red',
+    #                         bbox=dict(facecolor='white', alpha=0.8, edgecolor='red'))
+
+    #             frame_path = os.path.join(output_folder, f"frame_{t+1:04d}.jpg")
+    #             plt.savefig(frame_path, dpi=150, bbox_inches='tight')
+    #             plt.close(fig)
+    #             print(f"📸 Saved {frame_path}")

ash_animator/utils.py

@@ -0,0 +1,23 @@
+
+from geopy.geocoders import Nominatim
+import numpy as np
+
+def create_grid(attrs):
+    x_origin = float(attrs["x_origin"])
+    y_origin = float(attrs["y_origin"])
+    x_res = float(attrs["x_res"])
+    y_res = float(attrs["y_res"])
+    x_grid_size = int(attrs["x_grid_size"])
+    y_grid_size = int(attrs["y_grid_size"])
+
+    lons = np.round(np.linspace(x_origin, x_origin + (x_grid_size - 1) * x_res, x_grid_size), 6)
+    lats = np.round(np.linspace(y_origin, y_origin + (y_grid_size - 1) * y_res, y_grid_size), 6)
+    return lons, lats, np.meshgrid(lons, lats)
+
+def get_country_label(lat, lon):
+    geolocator = Nominatim(user_agent="ash_animator")
+    try:
+        location = geolocator.reverse((lat, lon), language='en')
+        return location.raw['address'].get('country', 'Unknown')
+    except:
+        return "Unknown"

default_model.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9bb340a75132c3008a149557ff85f8bc05b4a46e70eee027503e30b9573fdd39
+size 181349