maque 0.2.1__py3-none-any.whl

maque/clustering/visualizer.py

@@ -0,0 +1,205 @@
+# -*- coding: utf-8 -*-
+"""
+聚类可视化工具
+
+支持多种降维算法：UMAP、t-SNE、PCA
+"""
+
+from pathlib import Path
+from typing import Literal, Optional, Tuple, Union
+
+import numpy as np
+from loguru import logger
+
+# 设置 matplotlib 后端（服务器环境兼容）
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+
+from sklearn.manifold import TSNE
+from sklearn.decomposition import PCA
+
+DimReductionMethod = Literal["umap", "tsne", "pca"]
+
+
+class ClusterVisualizer:
+    """
+    聚类结果可视化器
+
+    支持多种降维算法：
+    - UMAP: 速度快，保持全局结构（推荐）
+    - t-SNE: 保持局部结构，适合小数据集
+    - PCA: 最快，线性降维
+
+    Example:
+        >>> visualizer = ClusterVisualizer(method="umap")
+        >>> visualizer.plot(embeddings, labels, "clusters.png")
+    """
+
+    def __init__(
+        self,
+        method: DimReductionMethod = "umap",
+        figsize: Tuple[int, int] = (12, 8),
+        dpi: int = 150,
+        random_state: int = 42,
+        # UMAP 参数
+        n_neighbors: int = 15,
+        min_dist: float = 0.1,
+        # t-SNE 参数
+        perplexity: int = 30,
+    ):
+        """
+        Args:
+            method: 降维方法 ("umap", "tsne", "pca")
+            figsize: 图片大小
+            dpi: 图片分辨率
+            random_state: 随机种子
+            n_neighbors: UMAP 邻居数
+            min_dist: UMAP 最小距离
+            perplexity: t-SNE perplexity 参数
+        """
+        self.method = method
+        self.figsize = figsize
+        self.dpi = dpi
+        self.random_state = random_state
+        self.n_neighbors = n_neighbors
+        self.min_dist = min_dist
+        self.perplexity = perplexity
+
+    def reduce_dimensions(self, embeddings: np.ndarray) -> np.ndarray:
+        """
+        将高维向量降维到 2D
+
+        Args:
+            embeddings: 向量矩阵 (n_samples, n_features)
+
+        Returns:
+            2D 坐标矩阵 (n_samples, 2)
+        """
+        if self.method == "umap":
+            return self._reduce_umap(embeddings)
+
+        elif self.method == "tsne":
+            return self._reduce_tsne(embeddings)
+
+        elif self.method == "pca":
+            return self._reduce_pca(embeddings)
+
+        else:
+            raise ValueError(f"未知降维方法: {self.method}")
+
+    def _reduce_umap(self, embeddings: np.ndarray) -> np.ndarray:
+        """UMAP 降维"""
+        try:
+            import umap
+        except ImportError:
+            raise ImportError("UMAP 需要: pip install umap-learn")
+
+        logger.info(f"使用 UMAP 降维 (n_neighbors={self.n_neighbors}, min_dist={self.min_dist})...")
+        reducer = umap.UMAP(
+            n_components=2,
+            n_neighbors=min(self.n_neighbors, len(embeddings) - 1),
+            min_dist=self.min_dist,
+            random_state=self.random_state,
+            metric='cosine',
+        )
+        return reducer.fit_transform(embeddings)
+
+    def _reduce_tsne(self, embeddings: np.ndarray) -> np.ndarray:
+        """t-SNE 降维"""
+        logger.info(f"使用 t-SNE 降维 (perplexity={self.perplexity})...")
+        tsne = TSNE(
+            n_components=2,
+            random_state=self.random_state,
+            perplexity=min(self.perplexity, len(embeddings) - 1),
+        )
+        return tsne.fit_transform(embeddings)
+
+    def _reduce_pca(self, embeddings: np.ndarray) -> np.ndarray:
+        """PCA 降维"""
+        logger.info("使用 PCA 降维...")
+        pca = PCA(n_components=2, random_state=self.random_state)
+        return pca.fit_transform(embeddings)
+
+    def plot(
+        self,
+        embeddings: np.ndarray,
+        labels: np.ndarray,
+        output_path: Union[str, Path],
+        title: Optional[str] = None,
+        embeddings_2d: Optional[np.ndarray] = None,
+    ) -> bool:
+        """
+        绘制聚类可视化图
+
+        Args:
+            embeddings: 向量矩阵（如果提供 embeddings_2d 则忽略）
+            labels: 聚类标签
+            output_path: 输出文件路径
+            title: 图片标题
+            embeddings_2d: 预计算的 2D 坐标（可选）
+
+        Returns:
+            bool: 是否成功生成图片
+        """
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # 降维
+        if embeddings_2d is None:
+            embeddings_2d = self.reduce_dimensions(embeddings)
+
+        # 绘图
+        logger.info("生成可视化图...")
+        plt.figure(figsize=self.figsize)
+
+        unique_labels = sorted(set(labels))
+        n_clusters = len(unique_labels) - (1 if -1 in unique_labels else 0)
+
+        # 根据簇数量选择颜色方案
+        if n_clusters <= 20:
+            colors = plt.cm.tab20(np.linspace(0, 1, 20))
+        else:
+            # 簇数 > 20 时使用连续色图
+            colors = plt.cm.gist_ncar(np.linspace(0.05, 0.95, n_clusters))
+
+        color_idx = 0
+        for label in unique_labels:
+            mask = labels == label
+            if label == -1:
+                plt.scatter(
+                    embeddings_2d[mask, 0],
+                    embeddings_2d[mask, 1],
+                    c='gray',
+                    alpha=0.3,
+                    s=10,
+                    label='Noise'
+                )
+            else:
+                if n_clusters <= 20:
+                    color = colors[label % 20]
+                else:
+                    color = colors[color_idx]
+                    color_idx += 1
+                plt.scatter(
+                    embeddings_2d[mask, 0],
+                    embeddings_2d[mask, 1],
+                    c=[color],
+                    alpha=0.6,
+                    s=15,
+                    label=f'Cluster {label}'
+                )
+
+        if n_clusters <= 10:
+            plt.legend(loc='best', fontsize=8)
+
+        method_name = self.method.upper()
+        plt.title(title or f'Cluster Visualization ({method_name}, n={n_clusters})')
+        plt.xlabel(f'{method_name} dim 1')
+        plt.ylabel(f'{method_name} dim 2')
+        plt.tight_layout()
+        plt.savefig(output_path, dpi=self.dpi)
+        plt.close()
+
+        logger.info(f"可视化图片保存到: {output_path}")
+        return True

maque/constant.py

@@ -0,0 +1,13 @@
+"""常用数学和物理常量的定义模块。"""
+
+import math
+
+# Math
+PI = math.pi
+TAU = 2 * PI
+
+# Physics
+G = 9.8
+
+e = "2.71828182845904523536028747135266249775724709369995957496696762772407663035354759457138217852516642742746639193200305992181741359662904357290033429526059563073813232862794349076323382988075319525101901157383418793070215408914993488416750924476146066808226480016847741185374234544243710753907774499206955170276183860626133138458300075204493382656029760673711320070932870912744374704723069697720931014169283681902551510865746377211125238978442505695369677078544996996794686445490598793163688923009879312773617821542499922957635148220826989519366803318252886939849646510582093923982948879332036250944311730123819706841614039701983767932068328237646480429531180232878250981945581530175671736133206981125099618188159304169035159888851934580727386673858942287922849989208680582574927961048419844436346324496848756023362482704197862320900216099023530436994184914631409343173814364054625315209618369088870701676839642437814059271456354906130310720851038375051011574770417189861068739696552126715468895703503"
+pi = "3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679821480865132823066470938446095505822317253594081284811174502841027019385211055596446229489549303819644288109756659334461284756482337867831652712019091456485669234603486104543266482133936072602491412737245870066063155881748815209209628292540917153643678925903600113305305488204665213841469519415116094330572703657595919530921861173819326117931051185480744623799627495673518857527248912279381830119491298336733624406566430860213949463952247371907021798609437027705392171762931767523846748184676694051320005681271452635608277857713427577896091736371787214684409012249534301465495853710507922796892589235420199561121290219608640344181598136297747713099605187072113499999983729780499510597317328160963185950244594553469083026425223082533446850352619311881710100031378387528865875332083814206171776691473035982534904287554687311595628638823537875937519577818577805321712268066130019278766111959092164201989"

maque/core.py

@@ -0,0 +1,133 @@
+from collections import Counter
+from functools import wraps
+import pickle
+import numpy as np
+from deprecated import deprecated
+
+
+def clamp(x, x_min, x_max):
+    """Clamp a number to same range.
+    It's equivalent to np.clip()
+    Examples:
+        >>> clamp(-1, 0, 1)
+        >>> 0
+        >>> clamp([-1, 2, 3], [0, 0, 0], [1, 1, 1])
+        >>> [0, 1, 1]
+    """
+    return np.maximum(x_min, np.minimum(x_max, x))
+
+
+def broadcast(func):  # It can be replaced by `np.vectorize`
+    """Only for a functions with a single argument
+    example:
+    @broadcast
+    def f(x):
+        # A function that can map only a single element
+        if x==1 or x==0:
+            return x
+        else:
+            return f(x-1)+f(x-2)
+
+    >> f([2,4,10])
+    >> (1, 3, 832040)
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        value_list = []
+        for arg in args:
+            value_list.append(func(arg, **kwargs))
+        return tuple(value_list)
+
+    return wrapper
+
+
+class _Dict_enhance(dict):
+    """Enables the dictionary to be dot operated"""
+
+    def __init__(self, *args, **kwargs):
+        dict.__init__(self, *args, **kwargs)
+        self.__dict__ = self
+
+
+def dict_dotable(dic):
+    """
+    : input: a dictionary
+    : output: an enhanced dictionary
+    Example:
+        enhance_dic = dict_dotable(dic)
+    then, you can operate an enhanced dictionary like this:
+        enhance_dic.key1.key2. ...
+    """
+    dic = _Dict_enhance(dic)
+    for i in dic:
+        if type(dic[i]) == dict:
+            dic[i] = dict_dotable(dic[i])
+    return dic
+
+
+class Constant:
+    """
+    define a constant like C language.
+    `object.__setattr__(self, name, value)`
+    this built-in function will called when assigning values to properties of the class
+
+    `object.__dict__` holds all writable attributes in object,
+    key as variable name and value as variable value.
+    """
+
+    def __setattr__(self, name, value):
+        if hasattr(self, name):
+            raise ValueError("Constant value can't be changed")
+        else:
+            self.__dict__[name] = value
+
+
+def number_digits(number):
+    res = number
+    digit = 1
+    if res >= 1:
+        while res > 10:
+            digit += 1
+            # res, mod = np.divmod(res, 10)
+            res //= 10
+    else:
+        while res < 1:
+            digit -= 1
+            res *= 10
+    return digit
+
+
+def num_digits(number_like):
+    number_str = str(int(str(number_like)))
+    return len(number_str)
+
+
+def sort_count(_list: list):
+    """
+    返回lis的由大到小排序好的元素列表
+    Example:
+    l = np.array([2,2,2,2,5,5,3,9,9])
+    sort_count(l) : [(2, 4), (5, 2), (9, 2), (3, 1)]
+    # return [2, 5, 9,3], [4, 2, 2, 1]
+    """
+    a = Counter(_list)
+    b = sorted(a.items(), key=lambda item: item[1], reverse=True)
+    # idx, counts = [b[i][0] for i in range(len(b))], [b[i][1] for i in range(len(b))]
+    return b
+
+
+def reduce_list_element(array, *elems):
+    """
+    example:
+    a = [ 5, 6, 6, 7, 8, 9, 9]
+    reduce_list_element(a, 6, 9)
+    print(a)
+    >> [ 5, 7, 8]
+    """
+    length = len(array)
+    for idx in range(length):
+        index = length - idx - 1
+        for elem in elems:
+            if array[index] == elem:
+                array.pop(index)

maque/cv/__init__.py

@@ -0,0 +1 @@
+from .utils import *

maque/cv/image.py

@@ -0,0 +1,219 @@
+import cv2
+import numpy as np
+from PIL import Image
+import base64
+import io
+from dataclasses import dataclass
+from typing import List, Union, Optional, Literal
+
+ReturnFormat = Literal['pil', 'numpy', 'base64']
+
+@dataclass
+class FrameExtractionResult:
+    width: int
+    height: int
+    total_frames: int
+    original_fps: float
+    extracted_frames: List[Union[Image.Image, np.ndarray, str]]  # str for base64
+    start_time: float
+    end_time: float
+    extraction_fps: Optional[float] = None
+    format: ReturnFormat = 'pil'
+
+
+class VideoFrameExtractor:
+    def __init__(self, video_path: str):
+        """初始化视频帧提取器
+
+        Args:
+            video_path (str): 视频文件路径
+        """
+        self.video_path = video_path
+        self._video = None
+        self._init_video_capture()
+
+    def _init_video_capture(self):
+        """初始化视频捕获对象"""
+        self._video = cv2.VideoCapture(self.video_path)
+        if not self._video.isOpened():
+            raise ValueError(f"无法打开视频文件: {self.video_path}")
+        
+        self.video_fps = self._video.get(cv2.CAP_PROP_FPS)
+        self.total_frames = int(self._video.get(cv2.CAP_PROP_FRAME_COUNT))
+        self.width = int(self._video.get(cv2.CAP_PROP_FRAME_WIDTH))
+        self.height = int(self._video.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+    def extract_frames(
+        self,
+        start_time: float,
+        end_time: float = -1,
+        fps: Optional[float] = None,
+        n_frames: Optional[int] = None,
+        return_format: ReturnFormat = 'pil',
+        max_width: Optional[int] = None,
+        max_height: Optional[int] = None
+    ) -> FrameExtractionResult:
+        """提取视频帧
+
+        Args:
+            start_time (float): 开始时间（秒）
+            end_time (float): 结束时间（秒），-1表示到视频结束
+            fps (float, optional): 目标帧率
+            n_frames (int, optional): 需要提取的帧数
+            return_format (str): 返回格式，支持 'pil'、'numpy' 或 'base64'
+            max_width (int, optional): 最大宽度，保持宽高比缩放
+            max_height (int, optional): 最大高度，保持宽高比缩放
+
+        Returns:
+            FrameExtractionResult: 包含提取结果的数据类
+        """
+        # 计算开始和结束帧
+        start_frame = int(start_time * self.video_fps)
+        if end_time == -1:
+            end_frame = self.total_frames
+            end_time = self.total_frames / self.video_fps
+        else:
+            end_frame = int(end_time * self.video_fps)
+
+        # 计算需要提取的帧数
+        if fps:
+            n_frames = int((end_time - start_time) * fps)
+        else:
+            fps = self.video_fps
+            if n_frames is None:
+                raise ValueError("fps和n_frames不能同时为None")
+        
+        if n_frames <= 0:
+            raise ValueError("n_frames必须大于0")
+
+        # 计算采样步长
+        step = (end_frame - start_frame) / n_frames
+
+        # 计算目标尺寸
+        target_width = self.width
+        target_height = self.height
+        if max_width or max_height:
+            scale_w = max_width / self.width if max_width else float('inf')
+            scale_h = max_height / self.height if max_height else float('inf')
+            scale = min(scale_w, scale_h, 1.0)  # 确保不会放大
+            target_width = int(self.width * scale)
+            target_height = int(self.height * scale)
+
+        # 提取帧
+        extracted_frames = []
+        for i in np.arange(start_frame, end_frame, step):
+            self._video.set(cv2.CAP_PROP_POS_FRAMES, int(i))
+            ret, frame = self._video.read()
+            if ret:
+                rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+                
+                # 如果需要调整大小
+                if target_width != self.width or target_height != self.height:
+                    rgb_frame = cv2.resize(rgb_frame, (target_width, target_height), 
+                                         interpolation=cv2.INTER_AREA)
+
+                if return_format == 'pil':
+                    frame_data = Image.fromarray(rgb_frame)
+                elif return_format == 'numpy':
+                    frame_data = rgb_frame
+                elif return_format == 'base64':  # base64
+                    pil_image = Image.fromarray(rgb_frame)
+                    buffer = io.BytesIO()
+                    pil_image.save(buffer, format='PNG')
+                    frame_data = base64.b64encode(buffer.getvalue()).decode('utf-8')
+                else:
+                    raise TypeError(f"不支持的返回格式: {return_format}")
+                extracted_frames.append(frame_data)
+            else:
+                break
+
+        return FrameExtractionResult(
+            width=target_width,
+            height=target_height,
+            total_frames=self.total_frames,
+            original_fps=self.video_fps,
+            extracted_frames=extracted_frames,
+            start_time=start_time,
+            end_time=end_time,
+            extraction_fps=fps,
+            format=return_format
+        )
+
+    def frames_to_video(
+        self,
+        frames_result: FrameExtractionResult,
+        output_path: str,
+        fps: Optional[float] = None,
+        codec: str = 'mp4v'
+    ) -> None:
+        """将提取的帧重新组装为视频
+
+        Args:
+            frames_result (FrameExtractionResult): 帧提取结果
+            output_path (str): 输出视频的路径
+            fps (float, optional): 输出视频的帧率，默认使用提取时的帧率
+            codec (str, optional): 视频编码器，默认为'mp4v'
+        """
+        if not frames_result.extracted_frames:
+            raise ValueError("没有可用的帧进行视频合成")
+
+        # 使用提取时的帧率或指定的帧率
+        output_fps = fps if fps is not None else (
+            frames_result.extraction_fps if frames_result.extraction_fps
+            else frames_result.original_fps
+        )
+
+        # 创建VideoWriter对象
+        fourcc = cv2.VideoWriter_fourcc(*codec)
+        out = cv2.VideoWriter(
+            output_path,
+            fourcc,
+            output_fps,
+            (frames_result.width, frames_result.height)
+        )
+
+        try:
+            for frame in frames_result.extracted_frames:
+                # 根据不同的格式转换为OpenCV可用的格式
+                if frames_result.format == 'pil':
+                    cv_frame = cv2.cvtColor(np.array(frame), cv2.COLOR_RGB2BGR)
+                elif frames_result.format == 'numpy':
+                    cv_frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
+                elif frames_result.format == 'base64':
+                    # 解码base64字符串
+                    img_data = base64.b64decode(frame)
+                    nparr = np.frombuffer(img_data, np.uint8)
+                    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+                    cv_frame = img
+                else:
+                    raise ValueError(f"不支持的帧格式: {frames_result.format}")
+
+                out.write(cv_frame)
+        finally:
+            out.release()
+
+    def __del__(self):
+        """析构函数，确保视频资源被释放"""
+        if self._video is not None:
+            self._video.release()
+
+
+if __name__ == "__main__":
+    extractor = VideoFrameExtractor('input.mp4')
+
+    # 限制最大宽度为 1280，高度会按比例缩放
+    frames = extractor.extract_frames(
+        start_time=0,
+        end_time=10,
+        fps=30,
+        max_width=1280
+    )
+
+    # 同时限制最大宽度和高度，会按照最小缩放比例进行缩放
+    frames = extractor.extract_frames(
+        start_time=0,
+        end_time=10,
+        fps=30,
+        max_width=1280,
+        max_height=720
+    )

maque/cv/utils.py

@@ -0,0 +1,68 @@
+import base64
+
+try:    
+    import numpy as np
+    import cv2
+except ImportError:
+    # print("cv2 is not installed, please install it using 'pip install opencv-python'")
+    pass
+
+
+def put_chinese_text(img, text, pos, font_size, color, font_path=None):
+    """插入中文文本"""
+    import freetype
+    import numpy as np
+
+    if font_path is None:
+        font_path = "/System/Library/Fonts/PingFang.ttc"
+    face = freetype.Face(font_path)
+    face.set_char_size(font_size * 64)
+
+    for i, char in enumerate(text):
+        face.load_char(char)
+        bitmap = face.glyph.bitmap
+        h, w = bitmap.rows, bitmap.width
+        x, y = pos[0] + i * w, pos[1]
+
+        img_char = np.array(bitmap.buffer, dtype=np.uint8).reshape(h, w)
+        for c in range(3):
+            img[y : y + h, x : x + w, c] = color[c] * (img_char / 255.0) + img[y : y + h, x : x + w, c] * (
+                1 - img_char / 255.0
+            )
+
+def base64_to_numpy(image_base64):
+    image_bytes = base64.b64decode(image_base64)
+    image_np = np.frombuffer(image_bytes, dtype=np.uint8)
+    image_np2 = cv2.imdecode(image_np, cv2.IMREAD_COLOR)
+    # image_np2 = cv2.cvtColor(image_np2, cv2.COLOR_BGR2RGB)
+    image_np2 = image_np2 / 255
+    return image_np2.astype(np.float32)
+
+
+def numpy_to_base64(image, unnormalize: bool):
+    if unnormalize:
+        image = image / 2 + 0.5  # unnormalize
+    if image.dtype in (np.float32, np.double) and image.max() <= 1:
+        image = (image * 255).astype('uint8')
+    retval, buffer = cv2.imencode('.jpg', image)
+    pic_str = base64.b64encode(buffer)
+    return pic_str.decode()
+
+
+def numpy_to_tensor(image_np, normalize=True):
+    if normalize:
+        image_np = (image_np - 0.5) * 2
+    return np.transpose(image_np, (2, 0, 1))[None, ...]
+
+
+def tensor_to_base64(image_tensor, unnormalize=True):
+    import torch
+    if image_tensor.dtype == torch.float:
+        image_tensor = np.array(image_tensor.cpu())
+    b64_list = [numpy_to_base64(np.transpose(image, (1, 2, 0)), unnormalize) for image in image_tensor]
+    return b64_list
+
+
+def base64_list_to_tensor(b64_list, normalize=True):
+    tensor_list = [numpy_to_tensor(base64_to_numpy(b64), normalize) for b64 in b64_list]
+    return np.concatenate(tensor_list, 0)

maque/cv/video/__init__.py

@@ -0,0 +1,3 @@
+from .keyframe_extractor import AdvancedKeyframeExtractor, Method
+
+__all__ = ["AdvancedKeyframeExtractor", "Method"]