kevin-toolbox-dev 1.4.11__py3-none-any.whl → 1.4.13__py3-none-any.whl

kevin_toolbox/nested_dict_list/serializer/read.py

@@ -12,6 +12,7 @@ def read(input_path, **kwargs):
 
         参数：
             input_path:             <path> 文件夹或者 .tar 文件，具体结构参考 write()
+            b_keep_identical_relations: <boolean> 覆盖 record.json 中记录的同名参数，该参数的作用详见 write() 中的介绍。
     """
     assert os.path.exists(input_path)
 
@@ -42,7 +43,7 @@ def _read_unpacked_ndl(input_path, **kwargs):
 
     # 读取被处理的节点
     processed_nodes = []
-    if record_s:
+    if "processed" in record_s:
         for name, value in ndl.get_nodes(var=record_s["processed"], level=-1, b_strict=True):
             if value:
                 processed_nodes.append(name)
@@ -68,6 +69,8 @@ def _read_unpacked_ndl(input_path, **kwargs):
             ndl.set_value(var=var, name=name, value=bk.read(**value))
 
     #
+    if "b_keep_identical_relations" in kwargs:
+        record_s["b_keep_identical_relations"] = kwargs["b_keep_identical_relations"]
     if record_s.get("b_keep_identical_relations", False):
         from kevin_toolbox.nested_dict_list import value_parser
         var = value_parser.replace_identical_with_reference(var=var, flag="same", b_reverse=True)

kevin_toolbox/patches/for_matplotlib/common_charts/__init__.py

@@ -48,4 +48,9 @@ from .plot_distribution import plot_distribution
 from .plot_bars import plot_bars
 from .plot_scatters_matrix import plot_scatters_matrix
 from .plot_confusion_matrix import plot_confusion_matrix
+from .plot_2d_matrix import plot_2d_matrix
+from .plot_contour import plot_contour
+from .plot_3d import plot_3d
 from .plot_from_record import plot_from_record
+# from .plot_raincloud import plot_raincloud
+from .plot_mean_std_lines import plot_mean_std_lines

kevin_toolbox/patches/for_matplotlib/common_charts/plot_2d_matrix.py

@@ -0,0 +1,134 @@
+import copy
+import warnings
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
+from kevin_toolbox.env_info.version import compare
+
+__name = ":common_charts:plot_matrix"
+
+if compare(v_0=sns.__version__, operator="<", v_1='0.13.0'):
+    warnings.warn("seaborn version is too low, it may cause the heat map to not be drawn properly,"
+                  " please upgrade to 0.13.0 or higher")
+
+
+@COMMON_CHARTS.register(name=__name)
+def plot_2d_matrix(matrix, title, row_label="row", column_label="column", x_tick_labels=None, y_tick_labels=None,
+                   output_dir=None, output_path=None, replace_zero_division_with=0, **kwargs):
+    """
+        计算并绘制混淆矩阵
+
+        参数：
+            matrix:             <np.ndarray> 矩阵
+            row_label:          <str> 行标签。
+            column_label:       <str> 列标签。
+            title:              <str> 绘图标题，同时用于保存图片的文件名。
+            output_dir:         <str or None>
+                图像保存的输出目录。如果同时指定了 output_path，则以 output_path 为准。
+                若 output_dir 和 output_path 均未指定，则图像将直接通过 plt.show() 显示而不会保存到文件。
+
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接以 np.ndarray 形式返回图片，不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+            replace_zero_division_with:     <float> 在归一化混淆矩阵时，如果遇到除0错误的情况，将使用该值进行替代。
+                                    建议使用 np.nan 或 0，默认值为 0。
+
+        其他可选参数：
+            dpi:                <int> 图像保存的分辨率。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            normalize:          <str or None> 指定归一化方式。
+                                    可选值包括：
+                                        "row"（按行归一化）
+                                        "column"（按列归一化）
+                                        "all"（整体归一化）
+                                    默认为 None 表示不归一化。
+            value_fmt:          <str> 矩阵元素数值的显示方式。
+            b_return_matrix:    <bool> 是否在返回值中包含（当使用 normalize 操作时）修改后的矩阵。
+                                    默认为 False。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+            b_show_plot:        <boolean> 是否使用 plt.show() 展示图片。
+                                    默认为 False
+            b_bgr_image:        <boolean> 以 np.ndarray 形式返回图片时，图片的channel顺序是采用 bgr 还是 rgb。
+                                    默认为 True
+    """
+    paras = {
+        "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
+        "b_show_plot": False,
+        "b_bgr_image": True,
+        "normalize": None,  # "true", "pred", "all",
+        "b_return_matrix": False,  # 是否输出混淆矩阵
+
+    }
+    paras.update(kwargs)
+    matrix = np.asarray(matrix)
+    paras.setdefault("value_fmt",
+                     '.2%' if paras["normalize"] is not None or np.issubdtype(matrix.dtype, np.floating) else 'd')
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_2d_matrix, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    matrix = copy.deepcopy(matrix)
+
+    # replace with nan
+    if paras["normalize"] is not None:
+        if paras["normalize"] == "all":
+            if matrix.sum() == 0:
+                matrix[matrix == 0] = replace_zero_division_with
+            matrix = matrix / matrix.sum()
+        else:
+            check_axis = 1 if paras["normalize"] == "row" else 0
+            temp = np.sum(matrix, axis=check_axis, keepdims=False)
+            for i in range(len(temp)):
+                if temp[i] == 0:
+                    if check_axis == 0:
+                        matrix[:, i] = replace_zero_division_with
+                    else:
+                        matrix[i, :] = replace_zero_division_with
+            matrix = matrix / np.sum(matrix, axis=check_axis, keepdims=True)
+
+    # 绘制混淆矩阵热力图
+    plt.clf()
+    plt.figure(figsize=(8, 6))
+    sns.heatmap(matrix, annot=True, fmt=paras["value_fmt"],
+                xticklabels=x_tick_labels if x_tick_labels is not None else "auto",
+                yticklabels=y_tick_labels if y_tick_labels is not None else "auto",
+                cmap='viridis')
+
+    plt.xlabel(f'{column_label}')
+    plt.ylabel(f'{row_label}')
+    plt.title(f'{title}')
+
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+
+    if paras["b_return_matrix"]:
+        return _output_path, matrix
+    else:
+        return _output_path
+
+
+if __name__ == '__main__':
+    import os
+
+    # 示例真实标签和预测标签
+    A = np.random.randint(0, 5, (5, 5))
+    print(A)
+
+    plot_2d_matrix(
+        matrix=np.random.randint(0, 5, (5, 5)),
+        title="2D Matrix",
+        output_dir=os.path.join(os.path.dirname(__file__), "temp"),
+        replace_zero_division_with=-1,
+        # normalize="row"
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_3d.py

@@ -0,0 +1,198 @@
+import numpy as np
+import matplotlib.pyplot as plt
+from mpl_toolkits.mplot3d import Axes3D  # 兼容部分旧版 matplotlib
+from scipy.interpolate import griddata
+from kevin_toolbox.patches.for_matplotlib.color import generate_color_list
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path, \
+    log_scaling
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
+
+__name = ":common_charts:plot_3d"
+
+
+@COMMON_CHARTS.register(name=__name)
+def plot_3d(data_s, title, x_name, y_name, z_name, cate_name=None, type_=("scatter", "smooth_surf"), output_dir=None,
+            output_path=None, **kwargs):
+    """
+        绘制3D图
+            支持：散点图、三角剖分曲面及其平滑版本
+            
+        
+        参数：
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典
+                                    需要包含 x、y、z 三个键值对，分别对应 x、y、z 轴的数据。
+            title:              <str> 绘图标题。
+            x_name:             <str> x 轴的数据键名。
+            y_name:             <str> y 轴的数据键名。
+            z_name:             <str> z 轴的数据键名。
+            cate_name:          <str> 以哪个 data_name 作为数据点的类别。
+            type_:              <str/list of str> 图表类型。
+                                    目前支持以下取值，或者以下取值的列表：
+                                        - "scatter"         散点图
+                                        - "tri_surf"        三角曲面
+                                        - "smooth_surf"     平滑曲面
+                                    当指定列表时，将会绘制多个图表的混合。
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接以 np.ndarray 形式返回图片，不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+
+        其他可选参数：
+            dpi:                <int> 保存图像的分辨率。
+                                    默认为 200。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+            b_show_plot:        <boolean> 是否使用 plt.show() 展示图片。
+                                    默认为 False
+            b_bgr_image:        <boolean> 以 np.ndarray 形式返回图片时，图片的channel顺序是采用 bgr 还是 rgb。
+                                    默认为 True
+            scatter_size:       <int> 散点大小，默认 30。
+            cate_of_surf:       <str or list of str> 使用哪些类别的数据来绘制曲面。
+                                    默认为 None，表示使用所有类别的数据来绘制曲面。
+                                    仅当 cate_name 非 None 时该参数起效。
+            tri_surf_cmap:      <str> 三角剖分曲面的颜色映射，默认 "viridis"。
+            tri_surf_alpha:     <float> 三角剖分曲面的透明度，默认 0.6。
+            smooth_surf_cmap:   <str> 平滑曲面的颜色映射，默认 "coolwarm"。
+            smooth_surf_alpha:  <float> 平滑曲面的透明度，默认 0.6。
+            smooth_surf_method: <str> 平滑的方法。
+                                    支持以下取值：
+                                        - "linear"
+                                        - "cubic"
+            view_elev:          <float> 视角中的仰角，默认 30。
+            view_azim:          <float> 视角中的方位角，默认 45。
+            x_log_scale,y_log_scale,z_log_scale:    <int/float> 对 x,y,z 轴数据使用哪个底数进行对数显示。
+                                    默认为 None，此时表示不使用对数显示。
+            x_ticks,...:        <int/list of float or int> 在哪个数字下添加坐标记号。
+                                    默认为 None，表示不添加记号。
+                                    当设置为 int 时，表示自动根据 x,y,z 数据的范围，选取等间隔选取多少个坐标作为记号。
+            x_tick_labels,...:  <int/list> 坐标记号的label。
+    """
+    # 默认参数设置
+    paras = {
+        "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
+        "b_show_plot": False,
+        "b_bgr_image": True,
+        "scatter_size": 30,
+        "cate_of_surf": None,
+        "tri_surf_cmap": "viridis",
+        "tri_surf_alpha": 0.6,
+        "smooth_surf_cmap": "coolwarm",
+        "smooth_surf_alpha": 0.6,
+        "smooth_surf_method": "linear",
+        "view_elev": 30,
+        "view_azim": 45,
+        "x_log_scale": None,
+        "x_ticks": None,
+        "x_tick_labels": None,
+        "y_log_scale": None,
+        "y_ticks": None,
+        "y_tick_labels": None,
+        "z_log_scale": None,
+        "z_ticks": None,
+        "z_tick_labels": None,
+    }
+    paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_3d, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
+    if isinstance(type_, str):
+        type_ = [type_]
+    #
+    d_s = dict()
+    ticks_s = dict()
+    tick_labels_s = dict()
+    for k in ("x", "y", "z"):
+        d_s[k], ticks_s[k], tick_labels_s[k] = log_scaling(
+            x_ls=data_s[eval(f'{k}_name')], log_scale=paras[f"{k}_log_scale"],
+            ticks=paras[f"{k}_ticks"], tick_labels=paras[f"{k}_tick_labels"]
+        )
+
+    x, y, z = [d_s[i].reshape(-1) for i in ("x", "y", "z")]
+    color_s = None
+    cate_of_surf = None
+    if cate_name is not None:
+        cates = list(set(data_s[cate_name]))
+        color_s = {i: j for i, j in zip(cates, generate_color_list(nums=len(cates)))}
+        c = [color_s[i] for i in data_s[cate_name]]
+        if paras["cate_of_surf"] is not None:
+            temp = [paras["cate_of_surf"], ] if isinstance(paras["cate_of_surf"], str) else paras[
+                "cate_of_surf"]
+            cate_of_surf = [i in temp for i in data_s[cate_name]]
+    else:
+        c = "red"
+
+    plt.clf()
+    fig = plt.figure(figsize=(10, 8))
+    ax = fig.add_subplot(111, projection='3d')
+
+    # 绘制数据点
+    if "scatter" in type_:
+        ax.scatter(x, y, z, s=paras["scatter_size"], c=c, depthshade=True)
+
+    if cate_of_surf is not None:
+        x, y, z = x[cate_of_surf], y[cate_of_surf], z[cate_of_surf]
+
+    # 绘制基于三角剖分的曲面（不平滑）
+    if "tri_surf" in type_:
+        tri_surf = ax.plot_trisurf(x, y, z, cmap=paras["tri_surf_cmap"], alpha=paras["tri_surf_alpha"])
+
+    # 构造规则网格，用于平滑曲面插值
+    if "smooth_surf" in type_:
+        grid_x, grid_y = np.mgrid[x.min():x.max():100j, y.min():y.max():100j]
+        grid_z = griddata((x, y), z, (grid_x, grid_y), method=paras["smooth_surf_method"])
+        # 绘制平滑曲面
+        smooth_surf = ax.plot_surface(grid_x, grid_y, grid_z, cmap=paras["smooth_surf_cmap"],
+                                      edgecolor='none', alpha=paras["smooth_surf_alpha"])
+        # 添加颜色条以展示平滑曲面颜色与 z 值的对应关系
+        cbar = fig.colorbar(smooth_surf, ax=ax, shrink=0.5, aspect=10)
+        cbar.set_label(z_name, fontsize=12)
+
+    # 设置坐标轴标签和图形标题
+    ax.set_xlabel(x_name, fontsize=12)
+    ax.set_ylabel(y_name, fontsize=12)
+    ax.set_zlabel(z_name, fontsize=12)
+    ax.set_title(title, fontsize=14)
+    for i in ("x", "y", "z"):
+        if ticks_s[i] is not None:
+            getattr(ax, f'set_{i}ticks')(ticks_s[i])
+            getattr(ax, f'set_{i}ticklabels')(tick_labels_s[i])
+
+    # 调整视角
+    ax.view_init(elev=paras["view_elev"], azim=paras["view_azim"])
+
+    # 创建图例
+    if "scatter" in type_ and cate_name is not None:
+        plt.legend(handles=[
+            plt.Line2D([0], [0], marker='o', color='w', label=i, markerfacecolor=j,
+                       markersize=min(paras["scatter_size"], 5)) for i, j in color_s.items()
+        ])
+
+    return save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"],
+                     b_bgr_image=paras["b_bgr_image"], b_show_plot=paras["b_show_plot"])
+
+
+if __name__ == '__main__':
+    # 示例用法：生成示例数据并绘制3D图像
+    np.random.seed(42)
+    num_points = 200
+    data = {
+        'x': np.random.uniform(-5, 5, num_points),
+        'y': np.random.uniform(-5, 5, num_points),
+        "c": np.random.uniform(-5, 5, num_points) > 0.3,
+    }
+    # 示例 z 值：例如 z = sin(sqrt(x^2+y^2))
+    data['z'] = np.sin(np.sqrt(data['x'] ** 2 + data['y'] ** 2)) + 1.1
+    plot_3d(data, x_name='x', y_name='y', z_name='z', cate_name="c", title="3D Surface Plot", z_log_scale=10, z_ticks=5,
+            type_=("scatter"), output_dir="./temp")

kevin_toolbox/patches/for_matplotlib/common_charts/plot_bars.py

@@ -27,7 +27,7 @@ def plot_bars(data_s, title, x_name, output_dir=None, output_path=None, **kwargs
             output_path:        <str or None> 图片输出路径。
                         以上两个只需指定一个即可，同时指定时以后者为准。
                         当只有 output_dir 被指定时，将会以 title 作为图片名。
-                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        若同时不指定，则直接以 np.ndarray 形式返回图片，不进行保存。
                         在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
 
         其他可选参数：
@@ -39,6 +39,10 @@ def plot_bars(data_s, title, x_name, output_dir=None, output_path=None, **kwargs
                                     默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
                                     后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
                                     该参数仅在 output_dir 和 output_path 非 None 时起效。
+            b_show_plot:        <boolean> 是否使用 plt.show() 展示图片。
+                                    默认为 False
+            b_bgr_image:        <boolean> 以 np.ndarray 形式返回图片时，图片的channel顺序是采用 bgr 还是 rgb。
+                                    默认为 True
 
         返回值：
             若 output_dir 非 None，则返回图像保存的文件路径。
@@ -78,9 +82,8 @@ def plot_bars(data_s, title, x_name, output_dir=None, output_path=None, **kwargs
     # 显示图例
     plt.legend()
 
-    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
-
-    return _output_path
+    return save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"],
+                     b_bgr_image=paras["b_bgr_image"], b_show_plot=paras["b_show_plot"])
 
 
 if __name__ == '__main__':

kevin_toolbox/patches/for_matplotlib/common_charts/plot_confusion_matrix.py

@@ -30,7 +30,7 @@ def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None
             output_path:        <str> 图片输出路径。
                         以上两个只需指定一个即可，同时指定时以后者为准。
                         当只有 output_dir 被指定时，将会以 title 作为图片名。
-                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        若同时不指定，则直接以 np.ndarray 形式返回图片，不进行保存。
                         在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
             replace_zero_division_with:     <float> 在归一化混淆矩阵时，如果遇到除0错误的情况，将使用该值进行替代。
                                     建议使用 np.nan 或 0，默认值为 0。
@@ -51,6 +51,10 @@ def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None
                                     默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
                                     后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
                                     该参数仅在 output_dir 和 output_path 非 None 时起效。
+            b_show_plot:        <boolean> 是否使用 plt.show() 展示图片。
+                                    默认为 False
+            b_bgr_image:        <boolean> 以 np.ndarray 形式返回图片时，图片的channel顺序是采用 bgr 还是 rgb。
+                                    默认为 True
 
         返回值：
             当 b_return_cfm 为 True 时，返回值可能为一个包含 (图像路径, 混淆矩阵数据) 的元组。
@@ -59,6 +63,8 @@ def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None
         "dpi": 200,
         "suffix": ".png",
         "b_generate_record": False,
+        "b_show_plot": False,
+        "b_bgr_image": True,
         "normalize": None,  # "true", "pred", "all",
         "b_return_cfm": False,  # 是否输出混淆矩阵
     }
@@ -105,12 +111,13 @@ def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None
     plt.ylabel(f'{gt_name}')
     plt.title(f'{title}')
 
-    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+    res = save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"],
+                    b_bgr_image=paras["b_bgr_image"], b_show_plot=paras["b_show_plot"])
 
     if paras["b_return_cfm"]:
-        return _output_path, cfm
+        return res, cfm
     else:
-        return _output_path
+        return res
 
 
 if __name__ == '__main__':

kevin_toolbox/patches/for_matplotlib/common_charts/plot_contour.py

@@ -0,0 +1,157 @@
+import numpy as np
+import matplotlib.pyplot as plt
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path, \
+    log_scaling
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
+
+__name = ":common_charts:plot_contour"
+
+
+@COMMON_CHARTS.register(name=__name)
+def plot_contour(data_s, title, x_name, y_name, z_name, type_=("contour", "contourf"),
+                 output_dir=None, output_path=None, **kwargs):
+    """
+        绘制等高线图
+            
+        
+        参数：
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典
+                                    需要包含 x、y、z 三个键值对，分别对应 x、y、z 轴的数据，值可以是 2D 的矩阵或者"" 1D 数据。 数组。
+            title:              <str> 绘图标题。
+            x_name:             <str> x 轴的数据键名。
+            y_name:             <str> y 轴的数据键名。
+            z_name:             <str> z 轴的数据键名。
+            type_:              <str/list of str> 图表类型。
+                                    目前支持以下取值，或者以下取值的列表：
+                                        - "contour"         等高线
+                                        - "contourf"        带颜色填充的等高线
+                                    当指定列表时，将会绘制多个图表的混合。
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接以 np.ndarray 形式返回图片，不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+
+        其他可选参数：
+            dpi:                <int> 保存图像的分辨率。
+                                    默认为 200。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+            b_show_plot:        <boolean> 是否使用 plt.show() 展示图片。
+                                    默认为 False
+            b_bgr_image:        <boolean> 以 np.ndarray 形式返回图片时，图片的channel顺序是采用 bgr 还是 rgb。
+                                    默认为 True
+            contourf_cmap:      <str> 带颜色填充的等高线的颜色映射，默认 "viridis"。
+            contourf_alpha:     <float> 颜色填充的透明度。
+            linestyles:         <str> 等高线线形。
+                                    可选值：
+                                        - 'solid'   实线
+                                        - 'dashed'  虚线（默认）
+                                        - 'dashdot' 点划线
+                                        - 'dotted'  点线
+            b_clabel:           <boolean> 是否在等高线上显示数值。
+            x_log_scale,y_log_scale,z_log_scale:    <int/float> 对 x,y,z 轴数据使用哪个底数进行对数显示。
+                                    默认为 None，此时表示不使用对数显示。
+            x_ticks,...:        <int/list of float or int> 在哪个数字下添加坐标记号。
+                                    默认为 None，表示不添加记号。
+                                    当设置为 int 时，表示自动根据 x,y,z 数据的范围，选取等间隔选取多少个坐标作为记号。
+                                    特别地，可以通过 z_ticks 来指定等高线的数量和划分位置。
+            x_tick_labels,...:  <int/list> 坐标记号的label。
+    """
+    # 默认参数设置
+    paras = {
+        "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
+        "b_show_plot": False,
+        "b_bgr_image": True,
+        "contourf_cmap": "viridis",
+        "contourf_alpha": 0.5,
+        "linestyles": "dashed",
+        "b_clabel": True,
+        "x_log_scale": None, "x_ticks": None, "x_tick_labels": None,
+        "y_log_scale": None, "y_ticks": None, "y_tick_labels": None,
+        "z_log_scale": None, "z_ticks": None, "z_tick_labels": None,
+    }
+    paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_contour, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
+    if isinstance(type_, str):
+        type_ = [type_]
+
+    d_s = dict()
+    ticks_s = dict()
+    tick_labels_s = dict()
+    for k in ("x", "y", "z"):
+        d_s[k], ticks_s[k], tick_labels_s[k] = log_scaling(
+            x_ls=data_s[eval(f'{k}_name')], log_scale=paras[f"{k}_log_scale"],
+            ticks=paras[f"{k}_ticks"], tick_labels=paras[f"{k}_tick_labels"]
+        )
+    X, Y, Z = [d_s[i] for i in ("x", "y", "z")]
+
+    plt.clf()
+    fig = plt.figure(figsize=(10, 8))
+    ax = fig.add_subplot(111)
+
+    # 等高线
+    if "contour" in type_:
+        if X.ndim == 1:
+            contour = ax.tricontour(X, Y, Z, colors='black', linestyles=paras["linestyles"], levels=ticks_s["z"])
+        elif X.ndim == 2:
+            contour = ax.contour(X, Y, Z, colors='black', linestyles=paras["linestyles"], levels=ticks_s["z"])
+        else:
+            raise ValueError("The dimension of X, Y, Z must be 1 or 2.")
+        if paras["b_clabel"]:
+            ax.clabel(contour, inline=True, fontsize=10, fmt={k: v for k, v in zip(ticks_s["z"], tick_labels_s["z"])})
+
+    # 等高线颜色填充
+    if "contourf" in type_:
+        if X.ndim == 1:
+            contourf = ax.tricontourf(X, Y, Z, cmap=paras["contourf_cmap"], alpha=paras["contourf_alpha"],
+                                      levels=ticks_s["z"])
+        elif X.ndim == 2:
+            contourf = ax.contourf(X, Y, Z, cmap=paras["contourf_cmap"], alpha=paras["contourf_alpha"],
+                                   levels=ticks_s["z"])
+        else:
+            raise ValueError("The dimension of X, Y, Z must be 1 or 2.")
+        # 添加颜色条以展示平滑曲面颜色与 z 值的对应关系
+        cbar = fig.colorbar(contourf, ax=ax, shrink=0.5, aspect=10)
+        cbar.set_label(z_name, fontsize=12)
+
+    # 设置坐标轴标签和图形标题
+    ax.set_xlabel(x_name, fontsize=12)
+    ax.set_ylabel(y_name, fontsize=12)
+    ax.set_title(title, fontsize=14)
+    for i in ("x", "y",):
+        if ticks_s[i] is not None:
+            getattr(ax, f'set_{i}ticks')(ticks_s[i])
+            getattr(ax, f'set_{i}ticklabels')(tick_labels_s[i])
+
+    return save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"],
+                     b_bgr_image=paras["b_bgr_image"], b_show_plot=paras["b_show_plot"])
+
+
+if __name__ == '__main__':
+    # 生成示例数据
+    x = np.linspace(1, 7, 100)
+    y = np.linspace(-3, 3, 100)
+    X, Y = np.meshgrid(x, y)
+    # 这里定义一个函数，使得 Z 值落在 0 到 1 之间
+    Z = np.exp(-(X ** 2 + Y ** 2))
+    data = {
+        'x': X,
+        'y': Y,
+        "z": Z,
+    }
+    plot_contour(data, x_name='x', y_name='y', z_name='z', title="Contour Plot", x_log_scale=None, z_ticks=10,
+                 type_=("contour", "contourf"), output_dir="./temp")