oafuncs 0.0.97.15__py3-none-any.whl → 0.0.97.17__py3-none-any.whl

oafuncs/oa_down/idm.py

@@ -4,7 +4,7 @@
 Author: Liu Kun && 16031215@qq.com
 Date: 2025-03-27 16:51:26
 LastEditors: Liu Kun && 16031215@qq.com
-LastEditTime: 2025-04-01 22:31:39
+LastEditTime: 2025-04-07 13:38:27
 FilePath: \\Python\\My_Funcs\\OAFuncs\\oafuncs\\oa_down\\idm.py
 Description:
 EditPlatform: vscode
@@ -14,6 +14,7 @@ Python Version: 3.12
 """
 
 
+
 import datetime
 import os
 from subprocess import call
@@ -46,12 +47,11 @@ def downloader(task_url, folder_path, file_name, idm_engine=r"D:\Programs\Intern
     call([idm_engine, "/d", task_url, "/p", folder_path, "/f", file_name, "/a"])
     # 开始任务队列
     call([idm_engine, "/s"])
-    # print(f"IDM下载器：{file_name}下载任务已添加至队列...")
     # print("[purple]-" * 150 + f"\n{datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n" + "[purple]-" * 150)
     print("[purple]*" * 100)
     time_str = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     time_str = time_str.center(100, " ")
     print(f"[bold purple]{time_str}")
-    print(f"[green]IDM Downloader: {file_name} download task has been added to the queue ...[/green]")
+    print(f"[green]IDM Downloader: {file_name}[/green]".center(100, " "))
     print("[purple]*" * 100)
-    print("\n")
+    # print("\n")

oafuncs/oa_draw.py

@@ -28,65 +28,75 @@ __all__ = ["fig_minus", "gif", "add_cartopy", "add_gridlines", "MidpointNormaliz
 warnings.filterwarnings("ignore")
 
 
-def fig_minus(ax_x: plt.Axes = None, ax_y: plt.Axes = None, cbar: mpl.colorbar.Colorbar = None, decimal: int = None, add_space: bool = False) -> plt.Axes | mpl.colorbar.Colorbar | None:
-    """
-    Description: 将坐标轴刻度中的负号替换为减号
+def fig_minus(x_axis: plt.Axes = None, y_axis: plt.Axes = None, colorbar: mpl.colorbar.Colorbar = None, decimal_places: int = None, add_spacing: bool = False) -> plt.Axes | mpl.colorbar.Colorbar | None:
+    """Replace negative signs with minus signs in axis tick labels.
+
+    Args:
+        x_axis (plt.Axes, optional): Matplotlib x-axis object to modify.
+        y_axis (plt.Axes, optional): Matplotlib y-axis object to modify.
+        colorbar (mpl.colorbar.Colorbar, optional): Matplotlib colorbar object to modify.
+        decimal_places (int, optional): Number of decimal places to display.
+        add_spacing (bool, optional): Whether to add spaces before non-negative numbers.
 
-    param {*} ax_x : x轴
-    param {*} ax_y : y轴
-    param {*} cbar : colorbar
-    param {*} decimal : 小数位数
-    param {*} add_space : 是否在非负数前面加空格
+    Returns:
+        plt.Axes | mpl.colorbar.Colorbar | None: The modified axis or colorbar object.
 
-    return {*} ax_x or ax_y or cbar
+    Example:
+        >>> fig_minus(x_axis=ax, y_axis=None, colorbar=colorbar, decimal_places=2, add_spacing=True)
     """
-    if ax_x is not None:
-        current_ticks = ax_x.get_xticks()
-    if ax_y is not None:
-        current_ticks = ax_y.get_yticks()
-    if cbar is not None:
-        current_ticks = cbar.get_ticks()
-    # 先判断是否需要加空格，如果要，先获取需要加的索引
-    if add_space:
+    # Determine which object to use and get its ticks
+    if x_axis is not None:
+        current_ticks = x_axis.get_xticks()
+    if y_axis is not None:
+        current_ticks = y_axis.get_yticks()
+    if colorbar is not None:
+        current_ticks = colorbar.get_ticks()
+
+    # Find index for adding space to non-negative values if needed
+    if add_spacing:
         index = 0
-        for _, tick in enumerate(current_ticks):
+        for i, tick in enumerate(current_ticks):
             if tick >= 0:
-                index = _
+                index = i
                 break
-    if decimal is not None:
-        # my_ticks = [(round(float(iii), decimal)) for iii in my_ticks]
-        current_ticks = [f"{val:.{decimal}f}" if val != 0 else "0" for val in current_ticks]
 
+    # Format according to decimal places if specified
+    if decimal_places is not None:
+        current_ticks = [f"{val:.{decimal_places}f}" if val != 0 else "0" for val in current_ticks]
+
+    # Replace negative signs with minus signs
     out_ticks = [f"{val}".replace("-", "\u2212") for val in current_ticks]
-    if add_space:
-        # 在非负数前面加两个空格
+
+    # Add spaces before non-negative values if specified
+    if add_spacing:
         out_ticks[index:] = ["  " + m for m in out_ticks[index:]]
 
-    if ax_x is not None:
-        ax_x.set_xticklabels(out_ticks)
-        return ax_x
-    if ax_y is not None:
-        ax_y.set_yticklabels(out_ticks)
-        return ax_y
-    if cbar is not None:
-        cbar.set_ticklabels(out_ticks)
-        return cbar
+    # Apply formatted ticks to the appropriate object
+    if x_axis is not None:
+        x_axis.set_xticklabels(out_ticks)
+    if y_axis is not None:
+        y_axis.set_yticklabels(out_ticks)
+    if colorbar is not None:
+        colorbar.set_ticklabels(out_ticks)
 
+    print("[green]Axis tick labels updated successfully.[/green]")
+    return x_axis or y_axis or colorbar
 
-# ** 将生成图片/已有图片制作成动图
-def gif(image_list: list[str], gif_name: str, duration: float = 200, resize: tuple[int, int] = None) -> None:  # 制作动图，默认间隔0.2
-    """
-    Description
-        Make gif from images
-    Parameters
-        image_list : list, list of images
-        gif_name : str, name of gif
-        duration : float, duration of each frame, units: ms
-        resize : tuple, (width, height) to resize images, if None, use first image size
-    Returns
+
+def gif(image_paths: list[str], output_gif_name: str, frame_duration: float = 200, resize_dimensions: tuple[int, int] = None) -> None:
+    """Create a GIF from a list of images.
+
+    Args:
+        image_paths (list[str]): List of image file paths.
+        output_gif_name (str): Name of the output GIF file.
+        frame_duration (float): Duration of each frame in milliseconds.
+        resize_dimensions (tuple[int, int], optional): Resize dimensions (width, height). Defaults to None.
+
+    Returns:
         None
-    Example
-        gif(["1.png", "2.png"], "test.gif", duration=0.2)
+
+    Example:
+        >>> gif(['image1.png', 'image2.png'], 'output.gif', frame_duration=200, resize_dimensions=(800, 600))
     """
     import imageio.v2 as imageio
     import numpy as np
@@ -95,141 +105,231 @@ def gif(image_list: list[str], gif_name: str, duration: float = 200, resize: tup
     frames = []
 
     # 获取目标尺寸
-    if resize is None and image_list:
+    if resize_dimensions is None and image_paths:
         # 使用第一张图片的尺寸作为标准
-        with Image.open(image_list[0]) as img:
-            resize = img.size
+        with Image.open(image_paths[0]) as img:
+            resize_dimensions = img.size
 
     # 读取并调整所有图片的尺寸
-    for image_name in image_list:
+    for image_name in image_paths:
         with Image.open(image_name) as img:
-            if resize:
-                img = img.resize(resize, Image.LANCZOS)
+            if resize_dimensions:
+                img = img.resize(resize_dimensions, Image.LANCZOS)
             frames.append(np.array(img))
 
-    # 修改此处：明确使用 duration 值，并将其作为每帧的持续时间（以秒为单位）
+    # 修改此处：明确使用 frame_duration 值，并将其作为每帧的持续时间（以秒为单位）
     # 某些版本的 imageio 可能需要以毫秒为单位，或者使用 fps 参数
     try:
-        # 先尝试直接使用 duration 参数（以秒为单位）
-        imageio.mimsave(gif_name, frames, format="GIF", duration=duration)
+        # 先尝试直接使用 frame_duration 参数（以秒为单位）
+        imageio.mimsave(output_gif_name, frames, format="GIF", duration=frame_duration)
     except Exception as e:
-        print(f"尝试使用fps参数替代duration: {e}")
-        # 如果失败，尝试使用 fps 参数（fps = 1/duration）
-        fps = 1.0 / duration if duration > 0 else 5.0
-        imageio.mimsave(gif_name, frames, format="GIF", fps=fps)
+        print(f"[yellow]Warning:[/yellow] Attempting to use fps parameter instead of duration: {e}")
+        # 如果失败，尝试使用 fps 参数（fps = 1/frame_duration）
+        fps = 1.0 / frame_duration if frame_duration > 0 else 5.0
+        imageio.mimsave(output_gif_name, frames, format="GIF", fps=fps)
 
-    print(f"Gif制作完成！尺寸: {resize}, 帧间隔: {duration}毫秒")
+    print(f"[green]GIF created successfully![/green] Size: {resize_dimensions}, Frame interval: {frame_duration} ms")
     return
 
 
-# ** 转化经/纬度刻度
-def add_lonlat_unit(lon: list[float] = None, lat: list[float] = None, decimal: int = 2) -> tuple[list[str], list[str]] | list[str]:
-    """
-    param        {*} lon : 经度列表
-    param        {*} lat : 纬度列表
-    param        {*} decimal : 小数位数
-    return       {*} 转化后的经/纬度列表
-    example     : add_lonlat_unit(lon=lon, lat=lat, decimal=2)
+def add_lonlat_unit(longitudes: list[float] = None, latitudes: list[float] = None, decimal_places: int = 2) -> tuple[list[str], list[str]] | list[str]:
+    """Convert longitude and latitude values to formatted string labels.
+
+    Args:
+        longitudes (list[float], optional): List of longitude values to format.
+        latitudes (list[float], optional): List of latitude values to format.
+        decimal_places (int, optional): Number of decimal places to display. Defaults to 2.
+
+    Returns:
+        tuple[list[str], list[str]] | list[str]: Formatted longitude and/or latitude labels.
+            Returns a tuple of two lists if both longitudes and latitudes are provided,
+            otherwise returns a single list of formatted values.
+
+    Examples:
+        >>> add_lonlat_unit(longitudes=[120, 180], latitudes=[30, 60], decimal_places=1)
+        (['120.0°E', '180.0°'], ['30.0°N', '60.0°N'])
+        >>> add_lonlat_unit(longitudes=[120, -60])
+        ['120.00°E', '60.00°W']
     """
 
-    def _format_longitude(x_list):
+    def _format_longitude(longitude_values: list[float]) -> list[str] | str:
+        """Format longitude values to string labels with directional indicators.
+
+        Converts numerical longitude values to formatted strings with degree symbols
+        and East/West indicators. Values outside the -180 to 180 range are normalized.
+
+        Args:
+            longitude_values: List of longitude values to format.
+
+        Returns:
+            List of formatted strings if input contains multiple values,
+            or a single string if input contains just one value.
+        """
         out_list = []
-        for x in x_list:
-            if x > 180:
-                x -= 360
-            # degrees = int(abs(x))
-            degrees = round(abs(x), decimal)
+        for x in longitude_values:
+            if x > 180 or x < -180:
+                print(f"[yellow]Warning:[/yellow] Longitude value {x} outside normal range (-180 to 180)")
+                x = ((x + 180) % 360) - 180  # Normalize to -180 to 180 range
+
+            degrees = round(abs(x), decimal_places)
             direction = "E" if x >= 0 else "W"
-            out_list.append(f"{degrees:.{decimal}f}°{direction}" if x != 0 and x != 180 else f"{degrees}°")
+            out_list.append(f"{degrees:.{decimal_places}f}°{direction}" if x != 0 and x != 180 else f"{degrees}°")
         return out_list if len(out_list) > 1 else out_list[0]
 
-    def _format_latitude(y_list):
+    def _format_latitude(latitude_values: list[float]) -> list[str] | str:
+        """Format latitude values to string labels with directional indicators.
+
+        Converts numerical latitude values to formatted strings with degree symbols
+        and North/South indicators. Values outside the -90 to 90 range are normalized.
+
+        Args:
+            latitude_values (list[float]): List of latitude values to format
+
+        Returns:
+            list[str] | str: List of formatted strings if input contains multiple values,
+                             or a single string if input contains just one value
+        """
         out_list = []
-        for y in y_list:
-            if y > 90:
-                y -= 180
-            # degrees = int(abs(y))
-            degrees = round(abs(y), decimal)
+        for y in latitude_values:
+            if y > 90 or y < -90:
+                print(f"[yellow]Warning:[/yellow] Latitude value {y} outside valid range (-90 to 90)")
+                y = min(max(y % 180 - 90, -90), 90)  # Normalize to -90 to 90 range
+
+            degrees = round(abs(y), decimal_places)
             direction = "N" if y >= 0 else "S"
-            out_list.append(f"{degrees:.{decimal}f}°{direction}" if y != 0 else f"{degrees}°")
+            out_list.append(f"{degrees:.{decimal_places}f}°{direction}" if y != 0 else f"{degrees}°")
         return out_list if len(out_list) > 1 else out_list[0]
 
-    if lon and lat:
-        return _format_longitude(lon), _format_latitude(lat)
-    elif lon:
-        return _format_longitude(lon)
-    elif lat:
-        return _format_latitude(lat)
+    # Input validation
+    if longitudes is not None and not isinstance(longitudes, list):
+        longitudes = [longitudes]  # Convert single value to list
+    if latitudes is not None and not isinstance(latitudes, list):
+        latitudes = [latitudes]  # Convert single value to list
+
+    if longitudes and latitudes:
+        result = _format_longitude(longitudes), _format_latitude(latitudes)
+    elif longitudes:
+        result = _format_longitude(longitudes)
+    elif latitudes:
+        result = _format_latitude(latitudes)
+    else:
+        result = []
+
+    print("[green]Longitude and latitude values formatted successfully.[/green]")
+    return result
+
+
+def add_gridlines(axes: plt.Axes, longitude_lines: list[float] = None, latitude_lines: list[float] = None, map_projection: ccrs.Projection = ccrs.PlateCarree(), line_color: str = "k", line_alpha: float = 0.5, line_style: str = "--", line_width: float = 0.5) -> tuple[plt.Axes, mpl.ticker.Locator]:
+    """Add gridlines to a map.
+
+    Args:
+        axes (plt.Axes): The axes to add gridlines to.
+        longitude_lines (list[float], optional): List of longitude positions for gridlines.
+        latitude_lines (list[float], optional): List of latitude positions for gridlines.
+        map_projection (ccrs.Projection, optional): Coordinate reference system. Defaults to PlateCarree.
+        line_color (str, optional): Line color. Defaults to "k".
+        line_alpha (float, optional): Line transparency. Defaults to 0.5.
+        line_style (str, optional): Line style. Defaults to "--".
+        line_width (float, optional): Line width. Defaults to 0.5.
+
+    Returns:
+        tuple[plt.Axes, mpl.ticker.Locator]: The axes and gridlines objects.
 
-
-# ** 添加网格线
-def add_gridlines(ax: plt.Axes, xline: list[float] = None, yline: list[float] = None, projection: ccrs.Projection = ccrs.PlateCarree(), color: str = "k", alpha: float = 0.5, linestyle: str = "--", linewidth: float = 0.5) -> tuple[plt.Axes, mpl.ticker.Locator]:
+    Example:
+        >>> add_gridlines(axes, longitude_lines=[0, 30], latitude_lines=[-90, 90], map_projection=ccrs.PlateCarree())
+        >>> axes, gl = add_gridlines(axes, longitude_lines=[0, 30], latitude_lines=[-90, 90])
+    """
     from matplotlib import ticker as mticker
 
     # add gridlines
-    gl = ax.gridlines(crs=projection, draw_labels=True, linewidth=linewidth, color=color, alpha=alpha, linestyle=linestyle)
+    gl = axes.gridlines(crs=map_projection, draw_labels=True, linewidth=line_width, color=line_color, alpha=line_alpha, linestyle=line_style)
     gl.right_labels = False
     gl.top_labels = False
     gl.xformatter = LongitudeFormatter(zero_direction_label=False)
     gl.yformatter = LatitudeFormatter()
 
-    if xline is not None:
-        gl.xlocator = mticker.FixedLocator(np.array(xline))
-    if yline is not None:
-        gl.ylocator = mticker.FixedLocator(np.array(yline))
+    if longitude_lines is not None:
+        gl.xlocator = mticker.FixedLocator(np.array(longitude_lines))
+    if latitude_lines is not None:
+        gl.ylocator = mticker.FixedLocator(np.array(latitude_lines))
+
+    print("[green]Gridlines added successfully.[/green]")
+    return axes, gl
 
-    return ax, gl
 
+def add_cartopy(axes: plt.Axes, longitude_data: np.ndarray = None, latitude_data: np.ndarray = None, map_projection: ccrs.Projection = ccrs.PlateCarree(), show_gridlines: bool = True, land_color: str = "lightgrey", ocean_color: str = "lightblue", coastline_linewidth: float = 0.5) -> None:
+    """Add cartopy features to a map.
 
-# ** 添加地图
-def add_cartopy(ax: plt.Axes, lon: np.ndarray = None, lat: np.ndarray = None, projection: ccrs.Projection = ccrs.PlateCarree(), gridlines: bool = True, landcolor: str = "lightgrey", oceancolor: str = "lightblue", cartopy_linewidth: float = 0.5) -> None:
+    Args:
+        axes (plt.Axes): The axes to add map features to.
+        longitude_data (np.ndarray, optional): Array of longitudes to set map extent.
+        latitude_data (np.ndarray, optional): Array of latitudes to set map extent.
+        map_projection (ccrs.Projection, optional): Coordinate reference system. Defaults to PlateCarree.
+        show_gridlines (bool, optional): Whether to add gridlines. Defaults to True.
+        land_color (str, optional): Color of land. Defaults to "lightgrey".
+        ocean_color (str, optional): Color of oceans. Defaults to "lightblue".
+        coastline_linewidth (float, optional): Line width for coastlines. Defaults to 0.5.
+
+    Returns:
+        None
+
+    Example:
+        >>> add_cartopy(axes, longitude_data=lon_data, latitude_data=lat_data, map_projection=ccrs.PlateCarree(), show_gridlines=True)
+        >>> axes = add_cartopy(axes, longitude_data=None, latitude_data=None, map_projection=ccrs.PlateCarree(), show_gridlines=False)
+
+    """
     # add coastlines
-    ax.add_feature(cfeature.LAND, facecolor=landcolor)
-    ax.add_feature(cfeature.OCEAN, facecolor=oceancolor)
-    ax.add_feature(cfeature.COASTLINE, linewidth=cartopy_linewidth)
-    # ax.add_feature(cfeature.BORDERS, linewidth=cartopy_linewidth, linestyle=":")
+    axes.add_feature(cfeature.LAND, facecolor=land_color)
+    axes.add_feature(cfeature.OCEAN, facecolor=ocean_color)
+    axes.add_feature(cfeature.COASTLINE, linewidth=coastline_linewidth)
+    # axes.add_feature(cfeature.BORDERS, linewidth=coastline_linewidth, linestyle=":")
 
     # add gridlines
-    if gridlines:
-        ax, gl = add_gridlines(ax, projection=projection)
+    if show_gridlines:
+        axes, gl = add_gridlines(axes, map_projection=map_projection)
 
     # set longitude and latitude format
     lon_formatter = LongitudeFormatter(zero_direction_label=False)
     lat_formatter = LatitudeFormatter()
-    ax.xaxis.set_major_formatter(lon_formatter)
-    ax.yaxis.set_major_formatter(lat_formatter)
+    axes.xaxis.set_major_formatter(lon_formatter)
+    axes.yaxis.set_major_formatter(lat_formatter)
 
     # set extent
-    if lon is not None and lat is not None:
-        lon_min, lon_max = np.nanmin(lon), np.nanmax(lon)
-        lat_min, lat_max = np.nanmin(lat), np.nanmax(lat)
-        ax.set_extent([lon_min, lon_max, lat_min, lat_max], crs=projection)
+    if longitude_data is not None and latitude_data is not None:
+        lon_min, lon_max = np.nanmin(longitude_data), np.nanmax(longitude_data)
+        lat_min, lat_max = np.nanmin(latitude_data), np.nanmax(latitude_data)
+        axes.set_extent([lon_min, lon_max, lat_min, lat_max], crs=map_projection)
+
+    print("[green]Cartopy features added successfully.[/green]")
+    return axes
 
 
-# ** 自定义归一化类，使得0值处为中心点
 class MidpointNormalize(mpl.colors.Normalize):
-    """
-    Description: 自定义归一化类，使得0值处为中心点
+    """Custom normalization class to center 0 value.
 
-    param {*} mpl.colors.Normalize : 继承Normalize类
-    return {*}
+    Args:
+        min_value (float, optional): Minimum data value. Defaults to None.
+        max_value (float, optional): Maximum data value. Defaults to None.
+        center_value (float, optional): Center value for normalization. Defaults to None.
+        clip_values (bool, optional): Whether to clip data outside the range. Defaults to False.
 
     Example:
-    nrom = MidpointNormalize(vmin=-2, vmax=1, vcenter=0)
+        >>> norm = MidpointNormalize(min_value=-2, max_value=1, center_value=0)
     """
 
-    def __init__(self, vmin: float = None, vmax: float = None, vcenter: float = None, clip: bool = False) -> None:
-        self.vcenter = vcenter
-        super().__init__(vmin, vmax, clip)
+    def __init__(self, min_value: float = None, max_value: float = None, center_value: float = None, clip_values: bool = False) -> None:
+        self.vcenter = center_value
+        super().__init__(min_value, max_value, clip_values)
 
-    def __call__(self, value: np.ndarray, clip: bool = None) -> np.ma.MaskedArray:
+    def __call__(self, input_values: np.ndarray, clip_values: bool = None) -> np.ma.MaskedArray:
         x, y = [self.vmin, self.vcenter, self.vmax], [0, 0.5, 1.0]
-        return np.ma.masked_array(np.interp(value, x, y, left=-np.inf, right=np.inf))
+        return np.ma.masked_array(np.interp(input_values, x, y, left=-np.inf, right=np.inf))
 
-    def inverse(self, value: np.ndarray) -> np.ndarray:
+    def inverse(self, normalized_values: np.ndarray) -> np.ndarray:
         y, x = [self.vmin, self.vcenter, self.vmax], [0, 0.5, 1]
-        return np.interp(value, x, y, left=-np.inf, right=np.inf)
+        return np.interp(normalized_values, x, y, left=-np.inf, right=np.inf)
 
+    # print("[green]Midpoint normalization applied successfully.[/green]")
 
 
 if __name__ == "__main__":