cfskit 0.0.2__py3-none-any.whl

cfskit/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from cfskit.log_util import setup_logger
+from cfskit.tb_util import TensorBoardWriter, setup_tensorboard
+from cfskit.ipc_util import (
+    get_s1,
+    get_s2,
+    register_signal_handler,
+    switch_s1,
+    switch_s2,
+)
+from cfskit.version import __version__
+
+__all__ = [
+    "__version__",
+    "setup_logger",
+    "setup_tensorboard",
+    "TensorBoardWriter",
+    "register_signal_handler",
+    "get_s1",
+    "get_s2",
+    "switch_s1",
+    "switch_s2",
+]

cfskit/ipc_util.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2025/2/12 13:50
+# @Author  : CFuShn
+# @Comments:
+# @Software: PyCharm
+
+import os
+import signal
+import threading
+
+# 两个自定义信号量, 供用户处理事件, 通过SIGUSR1 和 SIGUSR2 信号操作其值
+__s1 = 0  # 对应SIGUSR1 = 10
+__s2 = 0  # 对应SIGUSR2 = 12
+# 全局锁, 保护 __s1 / __s2 的读写
+__sig_lock = threading.Lock()
+
+
+def _signal_handler(signum, frame):
+    msg = None
+    global __s1, __s2
+    with __sig_lock:
+        if signum == signal.SIGUSR1:
+            __s1 = 1 - __s1  # 在0,1之间switch
+            msg = f"\n================= Received signal {signum}, set s1 = {__s1} ==================\n"
+        elif signum == signal.SIGUSR2:
+            __s2 = 1 - __s2  # 在0,1之间switch
+            msg = f"\n================= Received signal {signum}, set s2 = {__s2} ==================\n"
+    msg and print(msg)
+
+
+def register_signal_handler():
+    """注册用户自定义signal_handler,在接收信号时触发触发对应信号量的自定义操作"""
+    signal.signal(signal.SIGUSR1, _signal_handler)
+    signal.signal(signal.SIGUSR2, _signal_handler)
+    print(f"================= signal handler for pid: {os.getpid()} registered. =================")
+
+
+def get_s1():
+    """对应信号:SIGUSR1 = 10"""
+    with __sig_lock:
+        return __s1
+
+
+def get_s2():
+    """对应信号:SIGUSR2 = 12"""
+    with __sig_lock:
+        return __s2
+
+
+def switch_s1(num):
+    """对应信号:SIGUSR1 = 10"""
+    assert num in (0, 1)
+    global __s1
+    with __sig_lock:  # 在 switch 处加安全锁
+        if __s1 != num:
+            __s1 = num
+            print(f"=================== switch s1 to {__s1} ====================")
+
+
+def switch_s2(num):
+    """对应信号:SIGUSR2 = 12"""
+    assert num in (0, 1)
+    global __s2
+    with __sig_lock:  # 在 switch 处加安全锁
+        if __s2 != num:
+            __s2 = num
+            print(f"=================== switch s2 to {__s2} ====================")
+
+
+if __name__ == "__main__":
+
+    import sys
+    import time
+
+    # 必须先注册, 信号操作才会生效
+    register_signal_handler()
+
+    for i in range(50):
+        get_s2() > 0 and sys.exit("SIGUSR2 is active! This process exit!")
+        for j in range(10):
+            time.sleep(1)
+            get_s1() and print("SIGUSR1 is active!")
+            print(i, j)

cfskit/log_util.py

@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2026/5/8 16:13
+# @Author  : CFuShn
+# @Comments:
+# @Software: PyCharm
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+
+from loguru import logger
+
+if TYPE_CHECKING:  # pragma: no cover
+    from loguru import Logger
+
+_LOGGER_INITIALIZED = False
+_LOG_PATH = None
+
+
+class TqdmCompatibleSink:
+    """
+    用 tqdm.write() 替代普通 print/stderr 写入，避免打乱 tqdm 进度条。
+    """
+
+    def __init__(self):
+        try:
+            from tqdm import tqdm
+            self._tqdm = tqdm
+        except Exception:
+            self._tqdm = None
+
+    def write(self, message: str):
+        message = message.rstrip("\n")
+        if not message:
+            return
+
+        if self._tqdm is not None:
+            self._tqdm.write(message)
+        else:
+            print(message, file=sys.stderr)
+
+    def flush(self):
+        pass
+
+
+def setup_logger(
+        log_dir: str | Path = "logs",
+        name: Optional[str] = None,
+        level: str = "INFO",
+        console: bool = True,
+        file: bool = True,
+        rotation: str = "50 MB",
+        retention: str = "30 days",
+        enqueue: bool = False,
+        allow_reconfigure: bool = False,
+) -> tuple["Logger", Path]:
+    """
+    项目统一 logger 初始化。
+
+    默认行为：
+    - 只允许初始化一次
+    - 控制台彩色输出
+    - txt 文件纯文本输出
+    - INFO 级别
+    - tqdm 兼容
+    - logger.bind(console=False).info(...) 可仅写文件
+
+    如果确实想重新配置，显式传 allow_reconfigure=True。
+    """
+
+    global _LOGGER_INITIALIZED, _LOG_PATH
+
+    if _LOGGER_INITIALIZED and not allow_reconfigure:
+        raise RuntimeError(
+            f"setup_logger() has already been called once. "
+            f"Current log file: {_LOG_PATH}. "
+            f"If you really want to reconfigure logger, call "
+            f"setup_logger(..., allow_reconfigure=True)."
+        )
+
+    logger.remove()
+
+    log_dir = Path(log_dir)
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    if name is None:
+        name = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+    log_path = log_dir / f"{name}.txt"
+
+    console_fmt = (
+        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+        "<level>{level:<8}</level> | "
+        "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
+        "<level>{message}</level>"
+    )
+
+    file_fmt = (
+        "{time:YYYY-MM-DD HH:mm:ss.SSS} | "
+        "{level:<8} | "
+        "{name}:{function}:{line} | "
+        "{message}"
+    )
+
+    def console_filter(record):
+        return record["extra"].get("console", True)
+
+    if console:
+        logger.add(
+            TqdmCompatibleSink(),
+            level=level,
+            format=console_fmt,
+            filter=console_filter,
+            colorize=True,
+            enqueue=enqueue,
+        )
+
+    if file:
+        logger.add(
+            log_path,
+            level=level,
+            format=file_fmt,
+            encoding="utf-8",
+            rotation=rotation,
+            retention=retention,
+            colorize=False,
+            enqueue=enqueue,
+        )
+
+    _LOGGER_INITIALIZED = True
+    _LOG_PATH = log_path
+
+    logger.info(f"Log file: {log_path}")
+
+    return logger, log_path

cfskit/tb_util.py

@@ -0,0 +1,417 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2026/5/8 16:13
+# @Author  : CFuShn
+# @Comments:
+# @Software: PyCharm
+
+from __future__ import annotations
+
+import json
+import socket
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional, Mapping, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    import torch
+    from torch.utils.tensorboard import SummaryWriter
+
+_TB_INITIALIZED = False
+
+
+def _is_main_process(accelerator=None) -> bool:
+    if accelerator is None:
+        return True
+    return bool(accelerator.is_main_process)
+
+
+def _to_float(value: Any) -> float:
+    """
+    尽量把 torch scalar / numpy scalar / python number 转成 float。
+    """
+    try:
+        import torch  # type: ignore
+
+        if isinstance(value, torch.Tensor):
+            value = value.detach()
+            if value.numel() != 1:
+                raise ValueError(f"Expected scalar tensor, got shape={tuple(value.shape)}")
+            return float(value.item())
+    except Exception:
+        pass
+    return float(value)
+
+
+def _to_device_cpu(x: Any):
+    """
+    TensorBoard 写图片/直方图时，尽量 detach + cpu，避免持有计算图或 GPU 显存。
+    """
+    try:
+        import torch  # type: ignore
+
+        if isinstance(x, torch.Tensor):
+            return x.detach().cpu()
+    except Exception:
+        pass
+    return x
+
+
+class NullTensorBoardWriter:
+    """
+    非主进程使用的空操作 logger。
+    这样训练代码可以无脑写 tb.scalar(...)，不用到处 if rank0。
+    """
+
+    enabled = False
+    log_dir = None
+    writer = None
+
+    def __getattr__(self, name):
+        def noop(*args, **kwargs):
+            return None
+
+        return noop
+
+    def close(self):
+        return None
+
+    def flush(self):
+        return None
+
+
+class TensorBoardWriter:
+    """
+    对 SummaryWriter 的轻量封装。
+
+    常用方法：
+    - scalar
+    - scalars
+    - metrics
+    - image
+    - images
+    - histogram
+    - histograms
+    - text
+    - config
+    - graph
+    - flush
+    - close
+    """
+
+    enabled = True
+
+    def __init__(
+            self,
+            log_dir: str | Path,
+            *,
+            max_queue: int = 10,
+            flush_secs: int = 120,
+            comment: str = "",
+            filename_suffix: str = "",
+    ):
+        try:
+            from torch.utils.tensorboard import SummaryWriter  # type: ignore
+        except Exception as e:  # pragma: no cover
+            raise ImportError(
+                "TensorBoardLogger 需要 PyTorch。请执行：pip install \"cfskit[torch]\"（或 cfskit[tb]）。"
+            ) from e
+
+        self.log_dir = Path(log_dir)
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+        self.writer: "SummaryWriter" = SummaryWriter(
+            log_dir=str(self.log_dir),
+            comment=comment,
+            max_queue=max_queue,
+            flush_secs=flush_secs,
+            filename_suffix=filename_suffix,
+        )
+
+    def scalar(self, tag: str, value: Any, step: int):
+        self.writer.add_scalar(tag, _to_float(value), global_step=step)
+
+    def scalars(self, main_tag: str, tag_scalar_dict: Mapping[str, Any], step: int):
+        values = {k: _to_float(v) for k, v in tag_scalar_dict.items()}
+        self.writer.add_scalars(main_tag, values, global_step=step)
+
+    def metrics(
+            self,
+            metrics: Mapping[str, Any],
+            step: int,
+            *,
+            prefix: Optional[str] = None,
+    ):
+        """
+        批量写 scalar。
+
+        示例：
+            tb.metrics({"loss": loss, "lr": lr}, step, prefix="Train")
+        写成：
+            Train/loss
+            Train/lr
+        """
+        for k, v in metrics.items():
+            tag = f"{prefix}/{k}" if prefix else k
+            self.scalar(tag, v, step)
+
+    def image(
+            self,
+            tag: str,
+            img_tensor: "torch.Tensor",
+            step: int,
+            *,
+            dataformats: str = "CHW",
+    ):
+        """
+        写单张图片。
+
+        常见格式：
+        - CHW: [C, H, W]
+        - HWC: [H, W, C]
+        """
+        img_tensor = _to_device_cpu(img_tensor)
+        self.writer.add_image(
+            tag,
+            img_tensor,
+            global_step=step,
+            dataformats=dataformats,
+        )
+
+    def images(
+            self,
+            tag: str,
+            img_tensor: "torch.Tensor",
+            step: int,
+            *,
+            dataformats: str = "NCHW",
+    ):
+        """
+        写一组图片。
+
+        常见格式：
+        - NCHW: [N, C, H, W]
+        - NHWC: [N, H, W, C]
+        """
+        img_tensor = _to_device_cpu(img_tensor)
+        self.writer.add_images(
+            tag,
+            img_tensor,
+            global_step=step,
+            dataformats=dataformats,
+        )
+
+    def image_grid(
+            self,
+            tag: str,
+            img_tensor: "torch.Tensor",
+            step: int,
+            *,
+            nrow: int = 4,
+            normalize: bool = True,
+            value_range: Optional[tuple[float, float]] = None,
+    ):
+        """
+        把 [B, C, H, W] 做成 grid 后写入。
+        SR / ContSR 任务非常常用。
+        """
+        from torchvision.utils import make_grid
+
+        img_tensor = _to_device_cpu(img_tensor)
+
+        grid = make_grid(
+            img_tensor,
+            nrow=nrow,
+            normalize=normalize,
+            value_range=value_range,
+        )
+        self.image(tag, grid, step, dataformats="CHW")
+
+    def sr_triplet(
+            self,
+            tag: str,
+            lr: "torch.Tensor",
+            sr: "torch.Tensor",
+            hr: "torch.Tensor",
+            step: int,
+            *,
+            nrow: int = 4,
+            normalize: bool = True,
+            with_error: bool = True,
+    ):
+        """
+        超分任务常用：一次性记录 LR / SR / HR / Error Map。
+
+        要求：
+        - lr / sr / hr 尽量都是 [B, C, H, W]
+        - 如果 LR 尺寸小于 SR/HR，建议你在外面先 interpolate 到相同尺寸
+        """
+        self.image_grid(f"{tag}/lr", lr, step, nrow=nrow, normalize=normalize)
+        self.image_grid(f"{tag}/sr", sr, step, nrow=nrow, normalize=normalize)
+        self.image_grid(f"{tag}/hr", hr, step, nrow=nrow, normalize=normalize)
+
+        if with_error:
+            err = (sr.detach() - hr.detach()).abs()
+            self.image_grid(f"{tag}/error", err, step, nrow=nrow, normalize=True)
+
+    def histogram(self, tag: str, values: "torch.Tensor", step: int, *, bins: str = "tensorflow"):
+        values = _to_device_cpu(values)
+        self.writer.add_histogram(tag, values, global_step=step, bins=bins)
+
+    def histograms(
+            self,
+            model: "torch.nn.Module",
+            step: int,
+            *,
+            log_weights: bool = True,
+            log_grads: bool = True,
+            prefix: str = "",
+    ):
+        """
+        记录模型权重和梯度分布。
+        注意：不要每个 step 都写，建议几百/几千 step 写一次。
+        """
+        prefix = prefix.strip("/")
+        for name, param in model.named_parameters():
+            safe_name = name.replace(".", "/")
+            if prefix:
+                safe_name = f"{prefix}/{safe_name}"
+
+            if log_weights:
+                self.histogram(f"Weights/{safe_name}", param, step)
+
+            if log_grads and param.grad is not None:
+                self.histogram(f"Gradients/{safe_name}", param.grad, step)
+
+    def grad_norms(
+            self,
+            model: "torch.nn.Module",
+            step: int,
+            *,
+            prefix: str = "GradNorm",
+            norm_type: float = 2.0,
+    ):
+        """
+        记录每个参数的梯度范数。
+        比 histogram 更轻量。
+        """
+        for name, param in model.named_parameters():
+            if param.grad is None:
+                continue
+            tag = f"{prefix}/{name.replace('.', '/')}"
+            value = param.grad.detach().norm(norm_type)
+            self.scalar(tag, value, step)
+
+    def text(self, tag: str, text_string: str, step: int = 0):
+        self.writer.add_text(tag, text_string, global_step=step)
+
+    def config(self, config: Any, step: int = 0, tag: str = "Config"):
+        """
+        写入配置。
+        支持 dict / list / str / 其他可 json 化对象。
+        """
+        if isinstance(config, str):
+            text = config
+        else:
+            try:
+                text = json.dumps(config, indent=2, ensure_ascii=False)
+                text = f"```json\n{text}\n```"
+            except TypeError:
+                text = f"```text\n{str(config)}\n```"
+
+        self.text(tag, text, step=step)
+
+    def graph(self, model: "torch.nn.Module", input_to_model: Any):
+        """
+        记录模型 graph。
+        对动态 forward / 多输入模型可能失败，这是 TensorBoard graph 本身限制。
+        """
+        try:
+            import torch  # type: ignore
+
+            if isinstance(input_to_model, torch.Tensor):
+                input_to_model = input_to_model.detach()
+            elif isinstance(input_to_model, tuple):
+                input_to_model = tuple(
+                    x.detach() if isinstance(x, torch.Tensor) else x
+                    for x in input_to_model
+                )
+        except Exception:
+            pass
+        self.writer.add_graph(model, input_to_model)
+
+    def hparams(
+            self,
+            hparam_dict: Mapping[str, Any],
+            metric_dict: Mapping[str, Any],
+    ):
+        """
+        记录超参数。
+        注意：SummaryWriter.add_hparams 会生成额外子目录，TensorBoard 里显示方式和普通 scalar 不完全一样。
+        """
+        clean_metrics = {k: _to_float(v) for k, v in metric_dict.items()}
+        self.writer.add_hparams(dict(hparam_dict), clean_metrics)
+
+    def flush(self):
+        self.writer.flush()
+
+    def close(self):
+        self.writer.flush()
+        self.writer.close()
+
+
+def setup_tensorboard(
+        log_dir: str | Path = "runs",
+        name: Optional[str] = None,
+        *,
+        project: Optional[str] = None,
+        run_id: Optional[str] = None,
+        accelerator=None,
+        max_queue: int = 10,
+        flush_secs: int = 120,
+        comment: str = "",
+        filename_suffix: str = "",
+        allow_reconfigure: bool = False,
+) -> Union["TensorBoardWriter", "NullTensorBoardWriter"]:
+    global _TB_INITIALIZED
+
+    if _TB_INITIALIZED and not allow_reconfigure:
+        raise RuntimeError(
+            "setup_tensorboard() has already been called once. "
+            "If you really want to reconfigure it, call "
+            "setup_tensorboard(..., allow_reconfigure=True)."
+        )
+
+    is_main = _is_main_process(accelerator)
+
+    base_dir = Path(log_dir)
+
+    if run_id is not None:
+        run_name = run_id
+    else:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        hostname = socket.gethostname()
+
+        if name is None:
+            run_name = f"{timestamp}_{hostname}"
+        else:
+            run_name = f"{timestamp}_{hostname}_{name}"
+
+    if project is not None:
+        tb_log_dir = base_dir / project / run_name
+    else:
+        tb_log_dir = base_dir / run_name
+
+    if is_main:
+        tb = TensorBoardWriter(
+            tb_log_dir,
+            max_queue=max_queue,
+            flush_secs=flush_secs,
+            comment=comment,
+            filename_suffix=filename_suffix,
+        )
+    else:
+        tb = NullTensorBoardWriter()
+
+    _TB_INITIALIZED = True
+
+    return tb

cfskit/todos/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2026/5/8 18:43
+# @Author  : CFuShn
+# @Comments: 
+# @Software: PyCharm

cfskit/todos/t01_context.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2025/5/23 16:08
+# @Author  : CFuShn
+# @Comments: 全局上下文文件,用于加载配置信息,统管上下文
+# @Software: PyCharm
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:
+    import tomli as tomllib  # For Python <3.11
+from dataclasses import dataclass
+from typing import Optional
+
+from accelerate.utils import set_seed
+
+
+@dataclass
+class CFuShnContext:
+    # sys & env
+    seed = 3407  # 3407 is all you need
+
+    # 系统,环境
+    project_root = ""
+    output_root = ""
+    ckpt_version = ""
+
+    # 上下文传递
+    # ...
+
+    def __str__(self) -> str:
+        """一行一行打印参数"""
+        pretty = ""
+        # for key, value in self.__dict__.items():
+        #     pretty += (f"{key}: {value}\n" if key != "_instance" else "")
+        # 上面的方法无法保证属性是有序输出的,
+        # 使用__annotations__获取成员变量就是有序的, 但是在定义时必须指定其类型
+        # eg: version = xxx 就不在__annotations__中, 必须指定类型: version:str = xxx
+        for key in self.__annotations__.keys():
+            pretty += (f"{key}: {getattr(self, key)}\n" if key != "_instance" else "")
+        return pretty
+
+    # 单例实例
+    _instance: Optional["CFuShnContext"] = None
+    _initialized = False  # 初始化保护
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        """
+        整个项目基础上下文的初始化
+        """
+        if self._initialized:
+            return  # 防止重复初始化
+        self._initialized = True
+
+        # 设置所有相关的的随机数种子
+        # use accelerate lib # set the seed in `random`, `numpy`, `torch`
+        set_seed(self.seed)
+
+
+# 实例化并作为全局配置对象
+ctx = CFuShnContext()

cfskit/todos/t31_omni_dataset.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2026/5/8 17:30
+# @Author  : CFuShn
+# @Comments: 
+# @Software: PyCharm

cfskit/todos/t32_cc_image.py

@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2025/6/3 21:11
+# @Author  : CFuShn
+# @Comments: 单张人脸图像
+# @Software: PyCharm
+
+from typing import Optional
+
+import cv2
+
+
+class CcImage:
+
+    def __init__(self, _id, path=None, origin=None):
+        # 基本信息
+        self.id: str = _id  # 必传 (格式: 数据集id_{path.basename})
+        self.path: Optional[str | None] = path
+        self.origin: Optional[str | None] = origin  # 溯源
+
+        # 文本prompt
+        self.prompt: str = ""  # prompt 或 image caption
+
+    def img(self, mode="BGR"):
+        # img = cv2.imread(self.path, cv2.IMREAD_UNCHANGED)  # IMREAD_UNCHANGED表示保留alpha通道
+        bgr_img = cv2.imread(self.path)  # 默认是IMREAD_COLOR模式,只读取彩色, 且默认返回BGR顺序
+        if bgr_img is None:
+            return None
+        img = _ensure_bgr2rgb(bgr_img) if mode == "RGB" else _ensure_bgr(bgr_img)
+        return img
+
+
+# 将 BGR图像转换为RGB, 同时确保是彩色
+def _ensure_bgr2rgb(img):
+    if img is None:
+        return None
+    if len(img.shape) == 2:  # 灰度图
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
+    elif img.shape[2] == 1:  # 单通道
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
+    elif img.shape[2] == 3:  # BGR->RGB
+        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        return np.clip(img, 0, 255).astype('uint8')  # 新增保证
+    else:
+        print(f"[WARNING] 非标准图像通道数: {img.shape}")
+        return img
+
+
+def _ensure_bgr(img):
+    if img is None:
+        return None
+    if len(img.shape) == 2:  # 灰度图
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+    elif img.shape[2] == 1:  # 单通道
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+    elif img.shape[2] == 3:  # 已是BGR
+        return img
+    elif img.shape[2] == 4:  # BGRA -> BGR
+        return cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)
+    else:
+        print(f"[WARNING] 非标准图像通道数: {img.shape}")
+        return img[:, :, :3]  # 默认保前三通道

cfskit/todos/t90_DiffAugment_pytorch.py

@@ -0,0 +1,110 @@
+# Differentiable Augmentation for Data-Efficient GAN Training
+# Shengyu Zhao, Zhijian Liu, Ji Lin, Jun-Yan Zhu, and Song Han
+# https://arxiv.org/pdf/2006.10738
+
+import torch
+import torch.nn.functional as F
+
+
+def DiffAugment(x, policy='', channels_first=True):
+    """
+    在 GAN 训练过程中进行数据增强，适用于数据量较小的情况，以防止模式崩溃（mode collapse）。
+    增强操作是可微分的，确保反向传播不会被打断。
+    支持不同的增强策略（policy），如亮度、对比度、平移、裁剪等。
+    """
+    if policy:
+        if not channels_first:
+            x = x.permute(0, 3, 1, 2)
+        for p in policy.split(','):
+            for f in AUGMENT_FNS[p]:
+                x = f(x)
+        if not channels_first:
+            x = x.permute(0, 2, 3, 1)
+        x = x.contiguous()
+    return x
+
+
+def rand_brightness(x):
+    """
+    亮度增强
+    给图像整体加上一个随机亮度偏移量 [-0.5, 0.5]
+    (由于 rand_brightness 直接对 x 进行加法运算，因此是可微分的)
+    """
+    x = x + (torch.rand(x.size(0), 1, 1, 1, dtype=x.dtype, device=x.device) - 0.5)
+    return x
+
+
+def rand_saturation(x):
+    """
+    饱和度增强
+    计算 x 在 通道维度 的均值（即去除颜色信息，转灰度）。
+    按一个随机因子 缩放颜色饱和度。
+    """
+    x_mean = x.mean(dim=1, keepdim=True)
+    x = (x - x_mean) * (torch.rand(x.size(0), 1, 1, 1, dtype=x.dtype, device=x.device) * 2) + x_mean
+    return x
+
+
+def rand_contrast(x):
+    """
+    对比度增强
+    计算整个图像 x 的均值；
+    让 x 按随机因子缩放，使得对比度变化。
+    """
+    x_mean = x.mean(dim=[1, 2, 3], keepdim=True)
+    x = (x - x_mean) * (
+            torch.rand(x.size(0), 1, 1, 1, dtype=x.dtype, device=x.device) + 0.5) + x_mean
+    return x
+
+
+def rand_translation(x, ratio=0.125):
+    """
+    随机平移
+    使其在一定范围内进行随机像素偏移，防止模型过拟合于固定位置的特征。
+	适用于 GAN 训练，使生成器学习到更丰富的特征，而不是依赖固定的位置关系。
+	通过 meshgrid + 索引变换，避免插值影响可微性
+    """
+    # ratio=0.125 表示平移范围是图片尺寸的 12.5%。
+    shift_x, shift_y = int(x.size(2) * ratio + 0.5), int(x.size(3) * ratio + 0.5)
+    translation_x = torch.randint(-shift_x, shift_x + 1, size=[x.size(0), 1, 1], device=x.device)
+    translation_y = torch.randint(-shift_y, shift_y + 1, size=[x.size(0), 1, 1], device=x.device)
+    grid_batch, grid_x, grid_y = torch.meshgrid(
+        torch.arange(x.size(0), dtype=torch.long, device=x.device),
+        torch.arange(x.size(2), dtype=torch.long, device=x.device),
+        torch.arange(x.size(3), dtype=torch.long, device=x.device),
+    )
+    grid_x = torch.clamp(grid_x + translation_x + 1, 0, x.size(2) + 1)
+    grid_y = torch.clamp(grid_y + translation_y + 1, 0, x.size(3) + 1)
+    x_pad = F.pad(x, [1, 1, 1, 1, 0, 0, 0, 0])
+    x = x_pad.permute(0, 2, 3, 1).contiguous()[grid_batch, grid_x, grid_y].permute(0, 3, 1, 2)
+    return x
+
+
+def rand_cutout(x, ratio=0.5):
+    """
+    随机遮挡一部分图像区域
+    让模型学会忽略局部信息,通过 mask 操作高效实现裁剪区域零填充
+    """
+    cutout_size = int(x.size(2) * ratio + 0.5), int(x.size(3) * ratio + 0.5)
+    offset_x = torch.randint(0, x.size(2) + (1 - cutout_size[0] % 2), size=[x.size(0), 1, 1],
+                             device=x.device)
+    offset_y = torch.randint(0, x.size(3) + (1 - cutout_size[1] % 2), size=[x.size(0), 1, 1],
+                             device=x.device)
+    grid_batch, grid_x, grid_y = torch.meshgrid(
+        torch.arange(x.size(0), dtype=torch.long, device=x.device),
+        torch.arange(cutout_size[0], dtype=torch.long, device=x.device),
+        torch.arange(cutout_size[1], dtype=torch.long, device=x.device),
+    )
+    grid_x = torch.clamp(grid_x + offset_x - cutout_size[0] // 2, min=0, max=x.size(2) - 1)
+    grid_y = torch.clamp(grid_y + offset_y - cutout_size[1] // 2, min=0, max=x.size(3) - 1)
+    mask = torch.ones(x.size(0), x.size(2), x.size(3), dtype=x.dtype, device=x.device)
+    mask[grid_batch, grid_x, grid_y] = 0
+    x = x * mask.unsqueeze(1)
+    return x
+
+
+AUGMENT_FNS = {
+    'color': [rand_brightness, rand_saturation, rand_contrast],
+    'translation': [rand_translation],
+    'cutout': [rand_cutout],
+}

cfskit/version.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+# @Time    : 2025/10/30 13:55
+# @Author  : CFuShn
+# @Comments: version utilities (single source of truth)
+# @Software: PyCharm
+
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore
+
+
+def _read_version_from_pyproject() -> str | None:
+    """
+    When running from a source tree, fall back to the repo's pyproject.toml version.
+    This avoids keeping a hard-coded fallback in sync manually.
+    """
+    # src/cfskit/version.py -> repo_root/pyproject.toml
+    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+
+    try:
+        data = tomllib.loads(pyproject.read_text("utf-8"))
+        return str(data.get("project", {}).get("version")) or None
+    except Exception:
+        return None
+
+
+def get_version() -> str:
+    """
+    Get installed package version.
+
+    - If `cfskit` is installed (wheel/sdist), read version from package metadata.
+    - Otherwise, fall back to `pyproject.toml`'s [project].version (source tree).
+    - If that also fails, return "0.0.0".
+    """
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            return version("cfskit")
+        except PackageNotFoundError:
+            return _read_version_from_pyproject() or "0.0.0"
+    except Exception:
+        return _read_version_from_pyproject() or "0.0.0"
+
+
+__version__ = get_version()

cfskit-0.0.2.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: cfskit
+Version: 0.0.2
+Summary: Common research utilities for our NUIST-GenAI-Lab and CCGM tasks
+Author-email: CFuShn <1354809038@qq.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru<1,>=0.6.0
+Requires-Dist: accelerate<1,>=0.23.0; python_version < "3.10"
+Requires-Dist: accelerate<2,>=1.0.0; python_version >= "3.10"
+Requires-Dist: tensorboard<2.20,>=2.12.0; python_version < "3.9"
+Requires-Dist: tensorboard<3,>=2.20.0; python_version >= "3.9"
+Provides-Extra: torch
+Requires-Dist: torch<3,>=2.0.0; extra == "torch"
+Provides-Extra: tb
+Requires-Dist: torch<3,>=2.0.0; extra == "tb"
+Provides-Extra: tb-vision
+Requires-Dist: torchvision<1,>=0.15.0; extra == "tb-vision"
+Dynamic: license-file
+
+# cfskit
+
+cfskit 是一个科研学术项目脚手架, 初版专注于3个功能点: 日志、实验可视化写入、进程信号控制, 并提供一个完全可运行, 可展示全部功能的代码模板: [nlab-template](examples/nlab-template/).
+
+配合这个统一的模板, 可以让所有论文代码复现、二次开发、新建项目在一开始就完成非逻辑性的结构改造，统一成规范标准、结构清晰的实验工程形态。
+
+| 工具 | 模块 | 说明 |
+|------|------|------|
+| Logger | `cfskit.log_util` | 基于 loguru 的统一日志，tqdm 兼容，单次初始化 |
+| Writer | `cfskit.tb_util` | 基于 TensorBoard 的实验可视化写入，多进程自动适配 |
+| IPC | `cfskit.ipc_util` | 基于 SIGUSR1/SIGUSR2 的进程间信号量，支持优雅控制训练流程 |
+
+### 安装
+
+```bshash
+pip install cfskit
+```

cfskit-0.0.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+cfskit/__init__.py,sha256=AHbX9Vvb78HyRh2USR9URzJkDDshSwdt_H0iqlqnXF0,492
+cfskit/ipc_util.py,sha256=GEdaUJuaZdmPAxWQkjj4vsdn-8KTycIcxrvuLpzUlls,2345
+cfskit/log_util.py,sha256=XvFDfw8YXkOasS6dmxPdpbxurdnyIsKQCPzXTcC7QbM,3328
+cfskit/tb_util.py,sha256=5rfMK_QcC769swDtQ9JvnFV4f2C1mLga-dZXCWZujVI,11569
+cfskit/version.py,sha256=_rIhgmJs7pYme8AoJ7ehSbI1vQruoq63EjFaliA2E-c,1541
+cfskit/todos/__init__.py,sha256=SnqhH3saFVdJkFtOvH4KxrytKiqHqPAMFFSnDQBEA7A,107
+cfskit/todos/t01_context.py,sha256=CtRddagsKAH_sIpPnQjyTII20G0XaTaS8nV_Z_QNkDE,1902
+cfskit/todos/t31_omni_dataset.py,sha256=Y0R2gTZlPJGtbCmKdx4w-jKJJqhZqcc2zqc0eIMHDA8,107
+cfskit/todos/t32_cc_image.py,sha256=rG1px9muDDRsUDgUzExrUpkNp9JSDhnf3iuVUn3qT_M,2025
+cfskit/todos/t90_DiffAugment_pytorch.py,sha256=49r5xxvgPlXmGKSpgjSExr9sWcMAoaFag-x-HQzHVbo,4400
+cfskit-0.0.2.dist-info/licenses/LICENSE,sha256=DyWkc--IPT0QZez5hPQovfsyg8NQB46IQtcq3l1FoM0,1072
+cfskit-0.0.2.dist-info/METADATA,sha256=rngqd-K6vjAXKlDokhJ-u44f8WzQMDN6BpvAXkwxsS4,1649
+cfskit-0.0.2.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+cfskit-0.0.2.dist-info/top_level.txt,sha256=z0McdDkWozDKlDRTQK2mJ9C0Dhw7h6DF9r0_3yd5w9w,7
+cfskit-0.0.2.dist-info/RECORD,,

cfskit-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cfskit-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NUIST-GenAI-Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cfskit-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+cfskit