Upload 183 files

.gitattributes

@@ -32,3 +32,28 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T1.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T10.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T2.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T3.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T4.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T5.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T6.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T7.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T8.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/3D/T9.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T1_202001120500.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T10_202001121400.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T2_202001120600.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T3_202001120700.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T4_202001120800.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T5_202001120900.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T6_202001121000.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T7_202001121100.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T8_202001121200.nc filter=lfs diff=lfs merge=lfs -text
+ash_output/horizontal/AQOutput_HorizontalField_C1_T9_202001121300.nc filter=lfs diff=lfs merge=lfs -text
+media/2D/2d_fields/air_concentration/air_concentration.gif filter=lfs diff=lfs merge=lfs -text
+media/2D/frames/air_concentration/frame_0001.jpg filter=lfs diff=lfs merge=lfs -text
+media/2D/frames/air_concentration/frame_0008.jpg filter=lfs diff=lfs merge=lfs -text
+media/2D/frames/air_concentration/frame_0009.jpg filter=lfs diff=lfs merge=lfs -text
+media/2D/frames/air_concentration/frame_0010.jpg filter=lfs diff=lfs merge=lfs -text

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,131 @@
+
+# import contextily as ctx
+# from mpl_toolkits.basemap import Basemap
+# import cartopy.crs as ccrs
+# import cartopy.feature as cfeature
+
+# def draw_etopo_basemap(ax, mode="basemap", zoom=7):
+#     try:
+#         if mode == "stock":
+#             ax.stock_img()
+#         elif mode == "contextily":
+#             extent = ax.get_extent(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(ccrs.PlateCarree())
+#             m = Basemap(projection='cyl',
+#                         llcrnrlon=extent[0], urcrnrlon=extent[1],
+#                         llcrnrlat=extent[2], urcrnrlat=extent[3],
+#                         resolution='h', ax=ax)
+#             m.shadedrelief()
+#             m.drawcoastlines(linewidth=0.5)
+#             m.drawcountries(linewidth=0.7)
+#             m.drawmapboundary()
+#         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)
+
+import os
+import hashlib
+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
+
+# Define cache directories
+# Optional: Set tile cache directory (must be done before contextily downloads tiles)
+os.environ["XDG_CACHE_HOME"] = os.path.expanduser("~/.contextily_cache")
+
+CTX_TILE_CACHE_DIR = os.path.expanduser("~/.contextily_cache")
+BASEMAP_TILE_CACHE_DIR = os.path.expanduser("~/.basemap_cache")
+
+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())
+
+            # Create a hash key for this extent
+            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:
+                # Create a high-resolution temporary figure
+                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)  # 'h' = high resolution
+
+                m.shadedrelief()
+                # m.drawcoastlines(linewidth=0.1)
+                # m.drawcountries(linewidth=0.1)
+                # m.drawmapboundary()
+
+                # Save high-DPI figure for clarity
+                temp_fig.savefig(cache_file, dpi=300, bbox_inches='tight', pad_inches=0)
+                plt.close(temp_fig)
+
+                # Load and display the cached image
+                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,414 @@
+# # Full updated and corrected version of NAMEDataConverter with sanitized metadata keys
+
+# import os
+# import re
+# import zipfile
+# import shutil
+# import numpy as np
+# import xarray as xr
+# import matplotlib.pyplot as plt
+# import matplotlib.animation as animation
+# from typing import List, Tuple
+
+# class NAMEDataConverter:
+#     def __init__(self, output_dir: str):
+#         self.output_dir = output_dir
+#         os.makedirs(self.output_dir, exist_ok=True)
+
+#     def _sanitize_key(self, key: str) -> str:
+#         # Replace non-alphanumeric characters with underscores, and ensure it starts with a letter
+#         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"]),
+#                 "prelim_cols": int(metadata["number_of_preliminary_cols"]),
+#                 "n_fields": int(metadata["number_of_field_cols"]),
+#             })
+#         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 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",
+#                 "source": "NAME model output processed to NetCDF",
+#                 **{k: str(v) for k, v in meta.items()}  # Ensure all attrs are strings
+#             }
+#         )
+#         ds["ash_concentration"].attrs.update({
+#             "units": "g/m^3",
+#             "long_name": "Volcanic ash concentration"
+#         })
+#         ds["altitude"].attrs["units"] = "kilometers above sea level"
+#         ds["latitude"].attrs["units"] = "degrees_north"
+#         ds["longitude"].attrs["units"] = "degrees_east"
+
+#         out_path = os.path.join(self.output_dir, output_filename)
+#         ds.to_netcdf(out_path)
+#         return out_path
+
+#     def batch_process_zip(self, zip_path: str) -> List[str]:
+#         extract_dir = os.path.join(self.output_dir, "unzipped")
+#         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))
+
+#         pattern = re.compile(r"_T(\d+)_.*_Z(\d+)\.txt$")
+#         grouped = {}
+#         for f in txt_files:
+#             match = pattern.search(f)
+#             if match:
+#                 t = int(match.group(1))
+#                 z = int(match.group(2))
+#                 grouped.setdefault(t, []).append((z, f))
+
+#         nc_files = []
+#         for t_key in sorted(grouped):
+#             group = sorted(grouped[t_key])
+#             out_nc = self.convert_3d_group(group, f"T{t_key}.nc")
+#             nc_files.append(out_nc)
+#         return nc_files
+
+# 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
+
+
+class NAMEDataProcessor:
+    def __init__(self, output_root: str):
+        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.abspath("unzipped")
+
+        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,465 @@
+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
+
+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.getcwd(), 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, dpi=150, bbox_inches='tight')
+                plt.close(fig)
+                print(f"📸 Saved {frame_path}")

ash_animator/plot_horizontal_data.py

@@ -0,0 +1,564 @@
+''' 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
+
+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.getcwd(), 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, dpi=300, 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}")
+ '''
+ 
+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
+
+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.getcwd(), 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, dpi=300, 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"

ash_output/3D/T1.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7f04bb4ebcd78d22d304f989a1db3798ba8973c3605d409cf5d8c214e10640ae
+size 2995772

ash_output/3D/T10.nc

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

ash_output/3D/T2.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:417fd7f9876bc5cd90aa9b337d4643a2f60c4c16bcb02d387cac0d4e14865bdb
+size 2995772

ash_output/3D/T3.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ec9f03b1d56ef60f53c7d896b314391ef43aad5d8a483429f1225019a3cd9ba
+size 2995772

ash_output/3D/T4.nc

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

ash_output/3D/T5.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6ab72f23b1002e1282a249ca69a1b86edb931434d4061da53623a35259099e70
+size 2995772

ash_output/3D/T6.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:59e5b28106a70437df8acbe5f3a09bae1cb02452c64c81829ca024e45748ae01
+size 2995772

ash_output/3D/T7.nc

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

ash_output/3D/T8.nc

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

ash_output/3D/T9.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:779e66b51cced7ff2fcdb898497bd9239cc63dd1f98c3ea1e47ea227e033a469
+size 2995772

ash_output/horizontal/AQOutput_HorizontalField_C1_T10_202001121400.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:30423a57456aac09b692d4626113cfad7354c10ebfe2a6b8dc2bfc67660a087f
+size 760991

ash_output/horizontal/AQOutput_HorizontalField_C1_T1_202001120500.nc

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

ash_output/horizontal/AQOutput_HorizontalField_C1_T2_202001120600.nc

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

ash_output/horizontal/AQOutput_HorizontalField_C1_T3_202001120700.nc

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

ash_output/horizontal/AQOutput_HorizontalField_C1_T4_202001120800.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4486fd0527002f561c922a5a6281f3398a3813d857a5095cb20bb6ffd8646c97
+size 760991

ash_output/horizontal/AQOutput_HorizontalField_C1_T5_202001120900.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7677dd47e53ff9d1f6529c64c3447b3a17dc49edc740bedbc275798169eabf8f
+size 760991

ash_output/horizontal/AQOutput_HorizontalField_C1_T6_202001121000.nc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2c098cbd98dc31e6401fe90491324c068c9b9eb35e2d6893f74d18ca9c4161c4
+size 760991

ash_output/horizontal/AQOutput_HorizontalField_C1_T7_202001121100.nc

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

ash_output/horizontal/AQOutput_HorizontalField_C1_T8_202001121200.nc

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

ash_output/horizontal/AQOutput_HorizontalField_C1_T9_202001121300.nc

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

media/Taal_273070_20200112_scenario_yizhou.zip

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

media/default_model.zip

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