PyPI - workpytools - Versions diffs - 0.1.4__py3-none-any.whl - Mend

workpytools 0.1.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

workpytools/__init__.py +1 -0
workpytools/cli.py +76 -0
workpytools/common/__init__.py +0 -0
workpytools/common/browser_preview.py +40 -0
workpytools/common/clipboard.py +318 -0
workpytools/common/clustering.py +85 -0
workpytools/common/config.py +44 -0
workpytools/common/embedding.py +101 -0
workpytools/common/help_gen.py +542 -0
workpytools/common/logging.py +12 -0
workpytools/common/markdown_html.py +15 -0
workpytools/common/outline_parse.py +81 -0
workpytools/common/output.py +71 -0
workpytools/common/powerpoint.py +43 -0
workpytools/common/shape_cluster.py +75 -0
workpytools/common/table_shapes.py +157 -0
workpytools/common/tabular.py +248 -0
workpytools/common/textfile.py +90 -0
workpytools/common/walk.py +133 -0
workpytools/data/__init__.py +0 -0
workpytools/data/synonym.tsv +3 -0
workpytools/data/user.dic +2 -0
workpytools/processing/__init__.py +0 -0
workpytools/processing/base.py +23 -0
workpytools/processing/clipfmt.py +143 -0
workpytools/processing/clipmd.py +237 -0
workpytools/processing/clipview.py +194 -0
workpytools/processing/cwc.py +427 -0
workpytools/processing/denoise.py +81 -0
workpytools/processing/help.py +47 -0
workpytools/processing/ikko.py +205 -0
workpytools/processing/kukiri.py +94 -0
workpytools/processing/lsdir.py +218 -0
workpytools/processing/mdtsv.py +177 -0
workpytools/processing/mokuji.py +91 -0
workpytools/processing/nagasa.py +94 -0
workpytools/processing/outline.py +85 -0
workpytools/processing/profiler.py +277 -0
workpytools/processing/seiretsu.py +111 -0
workpytools/processing/tbl.py +358 -0
workpytools/processing/touka.py +52 -0
workpytools/processing/vv.py +147 -0
workpytools-0.1.4.dist-info/METADATA +458 -0
workpytools-0.1.4.dist-info/RECORD +48 -0
workpytools-0.1.4.dist-info/WHEEL +5 -0
workpytools-0.1.4.dist-info/entry_points.txt +20 -0
workpytools-0.1.4.dist-info/licenses/LICENSE +21 -0
workpytools-0.1.4.dist-info/top_level.txt +1 -0

workpytools/processing/clipview.py ADDED Viewed

@@ -0,0 +1,194 @@
+from __future__ import annotations
+import argparse
+import logging
+from workpytools.common.browser_preview import write_and_open
+from workpytools.common.clipboard import (
+    get_clipboard_html_fragment,
+    get_clipboard_text,
+    has_clipboard_html,
+    has_clipboard_text,
+)
+from workpytools.common.markdown_html import markdown_to_html_fragment
+from workpytools.processing.base import Processor
+logger = logging.getLogger(__name__)
+_PREVIEW_FILENAME = "workpytools_clipview_preview.html"
+_SVG_PREVIEW_FILENAME = "workpytools_clipview_preview.svg"
+# markdown-it-pyが```mermaidフェンスをレンダリングすると
+# <pre><code class="language-mermaid">...</code></pre> になる。
+# この文字列の有無だけを見て、Mermaidブロックの存在を検出する
+# （存在しない通常のMarkdown/HTMLプレビューでは外部通信を一切発生させないため）。
+_MERMAID_CLASS_MARKER = 'class="language-mermaid"'
+_MERMAID_CDN_URL = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"
+_MERMAID_SCRIPT = f"""\
+<script src="{_MERMAID_CDN_URL}"></script>
+<script>
+  document.querySelectorAll("pre code.language-mermaid").forEach((el) => {{
+    const pre = el.parentElement;
+    const div = document.createElement("div");
+    div.className = "mermaid";
+    div.textContent = el.textContent;
+    pre.replaceWith(div);
+  }});
+  mermaid.initialize({{ startOnLoad: true }});
+</script>
+"""
+_STYLE = """\
+:root { color-scheme: light dark; }
+body {
+  max-width: 46rem;
+  margin: 2rem auto;
+  padding: 0 1rem;
+  font-family: -apple-system, "Segoe UI", sans-serif;
+  line-height: 1.6;
+  color: #222;
+  background: #fff;
+}
+table { border-collapse: collapse; margin: 1rem 0; }
+th, td { border: 1px solid #999; padding: 0.4rem 0.8rem; }
+pre {
+  background: #f5f5f5;
+  padding: 0.8rem;
+  overflow-x: auto;
+  font-family: Consolas, "Courier New", monospace;
+}
+code { font-family: Consolas, "Courier New", monospace; }
+blockquote {
+  border-left: 4px solid #ccc;
+  margin-left: 0;
+  padding-left: 1rem;
+  color: #555;
+}
+@media (prefers-color-scheme: dark) {
+  body { color: #ddd; background: #1e1e1e; }
+  th, td { border-color: #555; }
+  pre { background: #2a2a2a; }
+  blockquote { border-left-color: #555; color: #aaa; }
+}
+"""
+def wrap_preview_html(body_fragment: str) -> str:
+    mermaid_script = _MERMAID_SCRIPT if _MERMAID_CLASS_MARKER in body_fragment else ""
+    return f"""<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Cache-Control" content="no-store">
+<title>clipview preview</title>
+<style>
+{_STYLE}
+</style>
+</head>
+<body>
+{body_fragment}
+{mermaid_script}</body>
+</html>
+"""
+class ClipviewProcessor(Processor):
+    """Preview clipboard Markdown or HTML in the default browser.
+    Unlike the other clip* commands, this one never modifies the clipboard;
+    it only reads it and writes a temporary preview file.
+    """
+    name = "clipview"
+    help = "クリップボードのMarkdown/HTMLをブラウザでプレビューする"
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        group = parser.add_mutually_exclusive_group()
+        group.add_argument(
+            "--markdown", action="store_true", help="入力をMarkdownとして解釈する"
+        )
+        group.add_argument("--html", action="store_true", help="入力をHTMLとして解釈する")
+        group.add_argument("--svg", action="store_true", help="入力をSVGとして解釈する")
+        parser.add_argument(
+            "--no-open", action="store_true", help="ブラウザを開かず、パスの表示のみ行う"
+        )
+    def run(self, args: argparse.Namespace) -> int:
+        svg_text = self._resolve_svg(args)
+        if svg_text is not None:
+            if not svg_text.strip():
+                raise SystemExit("変換結果が空です")
+            try:
+                preview_path = write_and_open(svg_text, _SVG_PREVIEW_FILENAME, args.no_open)
+            except RuntimeError as exc:
+                raise SystemExit(str(exc)) from exc
+            print(preview_path)
+            return 0
+        body_fragment = self._resolve_body_fragment(args)
+        if not body_fragment.strip():
+            raise SystemExit("変換結果が空です")
+        if _MERMAID_CLASS_MARKER in body_fragment:
+            logger.info(
+                "Mermaidブロックを検出したため、CDN(%s)からmermaid.jsを読み込みます",
+                _MERMAID_CDN_URL,
+            )
+        html = wrap_preview_html(body_fragment)
+        try:
+            preview_path = write_and_open(html, _PREVIEW_FILENAME, args.no_open)
+        except RuntimeError as exc:
+            raise SystemExit(str(exc)) from exc
+        print(preview_path)
+        return 0
+    def _resolve_svg(self, args: argparse.Namespace) -> str | None:
+        has_text = has_clipboard_text()
+        if args.svg:
+            if not has_text:
+                raise SystemExit("クリップボードにテキストがありません")
+            logger.info("--svg指定: SVGとして扱います")
+            return get_clipboard_text()
+        if args.markdown or args.html:
+            return None
+        if has_text:
+            text = get_clipboard_text()
+            if text.lstrip().startswith("<svg"):
+                logger.info("SVGコードを検出したため、そのままファイルにしてプレビューします")
+                return text
+        return None
+    def _resolve_body_fragment(self, args: argparse.Namespace) -> str:
+        has_html = has_clipboard_html()
+        has_text = has_clipboard_text()
+        if args.markdown:
+            if not has_text:
+                raise SystemExit("クリップボードにテキストがありません")
+            logger.info("--markdown指定: Markdownとして変換します")
+            return markdown_to_html_fragment(get_clipboard_text())
+        if args.html:
+            if not has_html and not has_text:
+                raise SystemExit("クリップボードにHTMLがありません")
+            logger.info("--html指定: HTMLとして解釈します")
+            return get_clipboard_html_fragment() if has_html else get_clipboard_text()
+        if has_html:
+            logger.info("CF_HTMLを検出したためHTMLとしてプレビューします")
+            return get_clipboard_html_fragment()
+        if has_text:
+            logger.info("CF_UNICODETEXTのみのためMarkdownとして変換します")
+            return markdown_to_html_fragment(get_clipboard_text())
+        raise SystemExit("クリップボードにプレビューできる内容がありません")

workpytools/processing/cwc.py ADDED Viewed

@@ -0,0 +1,427 @@
+from __future__ import annotations
+import argparse
+import logging
+import re
+import unicodedata
+from importlib import resources
+from pathlib import Path
+from wordcloud import STOPWORDS, WordCloud
+from workpytools.common.clipboard import load_text
+from workpytools.common.clustering import agglomerative_average_linkage
+from workpytools.common.config import load_default_config
+from workpytools.common.embedding import DEFAULT_MODEL_NAME, embed_sentences
+from workpytools.common.output import describe_output, save_result
+from workpytools.processing.base import Processor
+logger = logging.getLogger(__name__)
+_DEFAULT_FONT = Path(r"C:\Windows\Fonts\meiryo.ttc")
+# 文字クラス内では ] と - をエスケープする（] は先頭以外だとクラスの終端と解釈される）。
+_SPLIT_CHARS = "。（）「」『』【】〔〕［\\］｛｝〈〉《》()\\[\\]{}\\s"
+_SPLIT_PATTERN = re.compile(f"[{_SPLIT_CHARS}]+")
+# --similar 用の文分割。正規化後は全角!/?が半角になるため半角で指定する。
+_SENTENCE_SPLIT_PATTERN = re.compile(r"[。!?\s]+")
+# --similar の入力文数の上限。凝集型クラスタリングはO(n^2)の距離行列を使うため無制限にはしない。
+_SIMILAR_MAX_SENTENCES = 2000
+_HINSHI_CHOICES = (
+    "名詞",
+    "動詞",
+    "形容詞",
+    "副詞",
+    "助詞",
+    "助動詞",
+    "連体詞",
+    "接続詞",
+    "感動詞",
+    "接頭詞",
+    "記号",
+    "フィラー",
+    "その他",
+)
+# 送り仮名・漢字かな交ぜ書きのゆれをNFKC正規化の後に統一する変換表。
+_KANA_KANJI_REWRITES = {
+    "無し": "なし",
+    "有る": "ある",
+    "無い": "ない",
+}
+_DEFAULT_STOPWORDS_JA = frozenset(
+    {
+        # 形式名詞・指示語
+        "こと",
+        "もの",
+        "これ",
+        "それ",
+        "あれ",
+        "ため",
+        "よう",
+        "とき",
+        # 汎用動詞・補助的な語
+        "する",
+        "ある",
+        "いる",
+        "なる",
+        "できる",
+        # 助詞・助動詞
+        "の",
+        "に",
+        "は",
+        "を",
+        "が",
+        "で",
+        "と",
+        "も",
+        "や",
+        "から",
+        "まで",
+        "です",
+        "ます",
+    }
+)
+def _normalize(text: str) -> str:
+    normalized = unicodedata.normalize("NFKC", text)
+    for old, new in _KANA_KANJI_REWRITES.items():
+        normalized = normalized.replace(old, new)
+    return normalized
+def _split_default(text: str) -> list[str]:
+    return [token for token in _SPLIT_PATTERN.split(text) if token]
+def _split_wakachi(text: str, user_dict: Path | None) -> list[tuple[str, str, str]]:
+    """Tokenize with Janome. Returns (surface, base_form, hinshi) triples."""
+    from janome.tokenizer import Tokenizer  # 遅延インポート: -w/--hinshi指定時のみ読み込む
+    if user_dict is not None:
+        tokenizer = Tokenizer(udic=str(user_dict), udic_type="simpledic")
+    else:
+        tokenizer = Tokenizer()
+    result = []
+    for token in tokenizer.tokenize(text):
+        hinshi = token.part_of_speech.split(",")[0]
+        result.append((token.surface, token.base_form, hinshi))
+    return result
+def _resolve_user_dict(args: argparse.Namespace) -> Path | None:
+    if getattr(args, "no_user_dict", False):
+        return None
+    candidate: Path | None = None
+    with resources.as_file(resources.files("workpytools.data") / "user.dic") as bundled:
+        if bundled.exists():
+            candidate = bundled
+    config = load_default_config()
+    configured = config.get("cwc", {}).get("user_dict")
+    if configured is not None:
+        candidate = Path(configured)
+    if args.user_dict is not None:
+        candidate = Path(args.user_dict)
+    if candidate is not None and not candidate.exists():
+        logger.warning("ユーザー辞書が見つからないためスキップします: %s", candidate)
+        return None
+    return candidate
+def _resolve_synonym_dict(args: argparse.Namespace) -> Path | None:
+    if getattr(args, "no_synonym_dict", False):
+        return None
+    candidate: Path | None = None
+    with resources.as_file(resources.files("workpytools.data") / "synonym.tsv") as bundled:
+        if bundled.exists():
+            candidate = bundled
+    config = load_default_config()
+    configured = config.get("cwc", {}).get("synonym_dict")
+    if configured is not None:
+        candidate = Path(configured)
+    if args.synonym_dict is not None:
+        candidate = Path(args.synonym_dict)
+    if candidate is not None and not candidate.exists():
+        logger.warning("同義語辞書が見つからないためスキップします: %s", candidate)
+        return None
+    return candidate
+def _load_synonym_map(path: Path) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    with path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.rstrip("\n")
+            if not line or line.startswith("#"):
+                continue
+            columns = line.split("\t")
+            representative, *variants = columns
+            for variant in variants:
+                mapping[variant] = representative
+    return mapping
+def _resolve_stopwords(args: argparse.Namespace) -> frozenset[str]:
+    if args.no_default_stopwords:
+        words: set[str] = set()
+    else:
+        words = set(_DEFAULT_STOPWORDS_JA) | set(STOPWORDS)
+    if args.stopwords:
+        for chunk in args.stopwords:
+            words.update(w.strip() for w in chunk.split(",") if w.strip())
+    if args.stopwords_file:
+        path = Path(args.stopwords_file)
+        with path.open("r", encoding="utf-8") as f:
+            words.update(line.strip() for line in f if line.strip())
+    return frozenset(words)
+class CwcProcessor(Processor):
+    """Generate a word cloud image from input text.
+    Input source is auto-detected (file path or clipboard), following the
+    same convention as touka/denoise/kukiri. Word splitting defaults to
+    delimiter-based splitting; `-w` switches to Janome tokenization.
+    """
+    name = "cwc"
+    help = "テキストからワードクラウド画像を生成する（ファイルパス／クリップボード入力対応）"
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "path",
+            nargs="?",
+            default=None,
+            help="テキストファイルパス。省略時はクリップボードのテキスト/コピーしたファイルを使用",
+        )
+        parser.add_argument(
+            "-o", "--output", default=None, help="出力先パス（省略時は自動生成、拡張子はpng）"
+        )
+        parser.add_argument(
+            "--encoding",
+            default=None,
+            help="入力ファイルのエンコーディングを明示指定（省略時はUTF-8→CP932の順に試す）",
+        )
+        parser.add_argument(
+            "-w", "--wakachi", action="store_true", help="Janomeによる分かち書きで分割する"
+        )
+        parser.add_argument(
+            "--hinshi",
+            nargs="+",
+            default=None,
+            help=(
+                "集計対象の品詞を指定（複数可、カンマ区切りも可）。"
+                f"指定可能: {', '.join(_HINSHI_CHOICES)}"
+            ),
+        )
+        parser.add_argument(
+            "--semantic", action="store_true", help="同義語辞書で異表記を代表語に寄せる"
+        )
+        parser.add_argument("--synonym-dict", default=None, help="同義語辞書ファイルのパス")
+        parser.add_argument(
+            "--no-synonym-dict", action="store_true", help="同義語辞書を一切使用しない"
+        )
+        parser.add_argument("--user-dict", default=None, help="Janomeユーザー辞書のパス")
+        parser.add_argument(
+            "--no-user-dict", action="store_true", help="Janomeユーザー辞書を一切使用しない"
+        )
+        parser.add_argument(
+            "--stopwords",
+            action="append",
+            default=None,
+            help="追加するストップワード（カンマ区切り）",
+        )
+        parser.add_argument(
+            "--stopwords-file", default=None, help="追加するストップワードのファイルパス"
+        )
+        parser.add_argument(
+            "--no-default-stopwords",
+            action="store_true",
+            help="デフォルトのストップワードを無効化する",
+        )
+        parser.add_argument("--font", default=None, help="使用するフォントファイルのパス")
+        parser.add_argument(
+            "--similar",
+            action="store_true",
+            help="集計単位を語ではなく文にし、埋め込みベクトルの類似度でクラスタリングする",
+        )
+        parser.add_argument(
+            "--similar-threshold",
+            type=float,
+            default=0.2,
+            help="--similar のクラスタをまとめる距離の閾値（コサイン距離、既定: 0.2）",
+        )
+        parser.add_argument(
+            "--similar-model",
+            default=DEFAULT_MODEL_NAME,
+            help="--similar で使用する埋め込みモデル名",
+        )
+        parser.add_argument(
+            "--similar-max-length",
+            type=int,
+            default=10,
+            help="--similar の代表文の表示文字数の上限（0で無制限、既定: 10）",
+        )
+    def run(self, args: argparse.Namespace) -> int:
+        self._validate_exclusive_options(args)
+        loaded = load_text(args.path, encoding=args.encoding)
+        text = _normalize(loaded.text)
+        if args.similar:
+            frequencies = self._frequencies_from_similar(text, args)
+        else:
+            frequencies = self._frequencies_from_words(text, args)
+        if not frequencies:
+            raise SystemExit(
+                "集計対象が0件です。入力が空か、全ての単語がストップワードで除去された"
+                "可能性があります。--no-default-stopwords を試してください。"
+            )
+        font_path = Path(args.font) if args.font else _DEFAULT_FONT
+        if not font_path.exists():
+            raise SystemExit(f"フォントが見つかりません: {font_path}")
+        wc = WordCloud(font_path=str(font_path), width=800, height=600, background_color="white")
+        result = wc.generate_from_frequencies(frequencies).to_image()
+        output_path = save_result(loaded, result, "cwc", args.output)
+        print(describe_output(output_path))
+        return 0
+    def _validate_exclusive_options(self, args: argparse.Namespace) -> None:
+        if args.semantic and (args.wakachi or args.hinshi is not None):
+            raise SystemExit("--semantic は -w / --hinshi と同時に指定できません")
+        if args.similar and (args.semantic or args.wakachi or args.hinshi is not None):
+            raise SystemExit("--similar は --semantic / -w / --hinshi と同時に指定できません")
+    def _frequencies_from_words(self, text: str, args: argparse.Namespace) -> dict[str, int]:
+        use_wakachi = args.wakachi or args.hinshi is not None
+        if args.hinshi is not None and not args.wakachi:
+            logger.info("--hinshi 指定のため分かち書き経路を自動的に有効化します")
+        if use_wakachi:
+            words = self._tokens_from_wakachi(text, args)
+        else:
+            words = _split_default(text)
+            if args.semantic:
+                words = self._apply_synonyms(words, args)
+        stopwords = _resolve_stopwords(args)
+        words = [w for w in words if w not in stopwords]
+        frequencies: dict[str, int] = {}
+        for word in words:
+            frequencies[word] = frequencies.get(word, 0) + 1
+        return frequencies
+    def _frequencies_from_similar(self, text: str, args: argparse.Namespace) -> dict[str, int]:
+        sentences = [s for s in _SENTENCE_SPLIT_PATTERN.split(text) if s]
+        if not sentences:
+            return {}
+        if len(sentences) > _SIMILAR_MAX_SENTENCES:
+            logger.warning(
+                "--similar の入力文数が上限(%d)を超えたため、先頭%d件のみ使用します（全%d件）",
+                _SIMILAR_MAX_SENTENCES,
+                _SIMILAR_MAX_SENTENCES,
+                len(sentences),
+            )
+            sentences = sentences[:_SIMILAR_MAX_SENTENCES]
+        vectors = embed_sentences(sentences, model_name=args.similar_model)
+        distance_matrix = 1.0 - (vectors @ vectors.T)
+        labels = agglomerative_average_linkage(distance_matrix, args.similar_threshold)
+        clusters: dict[int, list[str]] = {}
+        for sentence, label in zip(sentences, labels, strict=True):
+            clusters.setdefault(int(label), []).append(sentence)
+        max_length = args.similar_max_length
+        frequencies: dict[str, int] = {}
+        for members in clusters.values():
+            counts: dict[str, int] = {}
+            for s in members:
+                counts[s] = counts.get(s, 0) + 1
+            best_count = max(counts.values())
+            candidates = [s for s, c in counts.items() if c == best_count]
+            representative = min(candidates, key=len)
+            display = representative
+            if max_length > 0 and len(display) > max_length:
+                display = display[:max_length] + "…"
+                logger.info(
+                    "代表文を切り詰めました: %s -> %s（元クラスタ件数=%d）",
+                    representative,
+                    display,
+                    len(members),
+                )
+            if display in frequencies:
+                logger.info(
+                    "切り詰め後の表示が別クラスタと衝突したため頻度を合算します: %s", display
+                )
+            frequencies[display] = frequencies.get(display, 0) + len(members)
+        return frequencies
+    def _tokens_from_wakachi(self, text: str, args: argparse.Namespace) -> list[str]:
+        user_dict = _resolve_user_dict(args)
+        tokens = _split_wakachi(text, user_dict)
+        hinshi_filter: set[str] | None = None
+        if args.hinshi is not None:
+            hinshi_filter = set()
+            for chunk in args.hinshi:
+                hinshi_filter.update(h.strip() for h in chunk.split(",") if h.strip())
+            unknown = hinshi_filter - set(_HINSHI_CHOICES)
+            if unknown:
+                raise SystemExit(
+                    f"未知の品詞名です: {', '.join(sorted(unknown))}"
+                    f"（指定可能: {', '.join(_HINSHI_CHOICES)}）"
+                )
+        words = []
+        for surface, base_form, hinshi in tokens:
+            if hinshi_filter is not None and hinshi not in hinshi_filter:
+                continue
+            if hinshi_filter is not None:
+                words.append(base_form if base_form != "*" else surface)
+            else:
+                words.append(surface)
+        return words
+    def _apply_synonyms(self, words: list[str], args: argparse.Namespace) -> list[str]:
+        synonym_dict = _resolve_synonym_dict(args)
+        if synonym_dict is None:
+            return words
+        mapping = _load_synonym_map(synonym_dict)
+        result = []
+        for word in words:
+            representative = mapping.get(word)
+            if representative is not None and representative != word:
+                logger.info("同義語として寄せました: %s -> %s", word, representative)
+                result.append(representative)
+            else:
+                result.append(word)
+        return result

workpytools/processing/denoise.py ADDED Viewed

@@ -0,0 +1,81 @@
+from __future__ import annotations
+import argparse
+import logging
+import cv2
+import numpy as np
+from PIL import Image
+from workpytools.common.clipboard import load_image
+from workpytools.common.output import describe_output, save_result
+from workpytools.processing.base import Processor
+logger = logging.getLogger(__name__)
+_DEFAULT_H_COLOR = 10.0
+_DEFAULT_TEMPLATE_WINDOW_SIZE = 7
+_DEFAULT_SEARCH_WINDOW_SIZE = 21
+class DenoiseProcessor(Processor):
+    """Remove photographic grain / sensor noise using OpenCV Non-local Means Denoising.
+    Input source and default output location follow the same convention as
+    touka: explicit `path` or a file copied in Explorer saves next to (or,
+    for the clipboard-file case, into the OS temp dir and back onto the
+    clipboard as) `{stem}_denoised.png`; raw clipboard image data skips the
+    file and is placed directly on the clipboard as image data.
+    """
+    name = "denoise"
+    help = "画像のノイズ除去（ファイルパス／クリップボード入力対応、OpenCV Non-local Means）"
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "path",
+            nargs="?",
+            default=None,
+            help="画像ファイルパス。省略時はクリップボードの画像/コピーしたファイルを使用",
+        )
+        parser.add_argument(
+            "-o", "--output", default=None, help="出力先パス（省略時は自動生成、拡張子はpng）"
+        )
+        parser.add_argument(
+            "--strength",
+            type=float,
+            default=10.0,
+            help="ノイズ除去強度 h（デフォルト: 10.0）。"
+            "値を大きくするほどノイズは減るがディテールも失われる",
+        )
+    def run(self, args: argparse.Namespace) -> int:
+        loaded = load_image(args.path)
+        logger.info("denoise starting (size=%s, strength=%s)", loaded.image.size, args.strength)
+        result = self._denoise(loaded.image, h=args.strength)
+        output_path = save_result(loaded, result, "denoised", args.output)
+        print(describe_output(output_path))
+        return 0
+    @staticmethod
+    def _denoise(image: Image.Image, h: float) -> Image.Image:
+        """Apply fastNlMeansDenoisingColored, preserving the original alpha channel untouched."""
+        rgba = np.array(image)
+        rgb = rgba[:, :, :3]
+        alpha = rgba[:, :, 3]
+        bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+        denoised_bgr = cv2.fastNlMeansDenoisingColored(
+            bgr,
+            None,
+            h=h,
+            hColor=_DEFAULT_H_COLOR,
+            templateWindowSize=_DEFAULT_TEMPLATE_WINDOW_SIZE,
+            searchWindowSize=_DEFAULT_SEARCH_WINDOW_SIZE,
+        )
+        denoised_rgb = cv2.cvtColor(denoised_bgr, cv2.COLOR_BGR2RGB)
+        out = np.dstack([denoised_rgb, alpha])
+        return Image.fromarray(out, mode="RGBA")