fix: improve control image matching by sorting image paths and avoidi…

README.ja.md

@@ -58,6 +58,11 @@
 
 GitHub Discussionsを有効にしました。コミュニティのQ&A、知識共有、技術情報の交換などにご利用ください。バグ報告や機能リクエストにはIssuesを、質問や経験の共有にはDiscussionsをご利用ください。[Discussionはこちら](https://github.com/kohya-ss/musubi-tuner/discussions)
 
+- 2025/10/25
+    - 制御画像を持つ画像データセットで、対象画像と制御画像の組み合わせが正しく読み込まれない不具合を修正しました。[PR #684](https://github.com/kohya-ss/musubi-tuner/pull/684)
+        - **制御画像を持つ画像データセットをご利用の場合、latentキャッシュの再作成を行ってください。**
+        - 先頭のマッチだけで判断していたため、対象画像が`a.png`、`ab.png`で、制御画像が`a_1.png`、`ab_1.png`のとき、`a.png`には、`a_1.png`と`ab_1.png`が組み合わされてしまっていました。
+
 - 2025/10/13
     - Qwen-Image-Edit、2509の推論スクリプトで、ピクセル単位での生成画像の一貫性を向上するReference Consistency Mask (RCM)機能を追加しました。[PR #643]
     (https://github.com/kohya-ss/musubi-tuner/pull/643)

README.md

@@ -63,6 +63,11 @@ If you find this project helpful, please consider supporting its development via
 
 GitHub Discussions Enabled: We've enabled GitHub Discussions for community Q&A, knowledge sharing, and technical information exchange. Please use Issues for bug reports and feature requests, and Discussions for questions and sharing experiences. [Join the conversation →](https://github.com/kohya-ss/musubi-tuner/discussions)
 
+- October 25, 2025
+    - Fixed a bug in image datasets with control images where the combination of target and control images was not loaded correctly. See [PR #684](https://github.com/kohya-ss/musubi-tuner/pull/684).
+        - **If you are using an image dataset with control images, please recreate the latent cache.**
+        - Since only the first match was used for judgment, when the target images were `a.png` and `ab.png`, and the control images were `a_1.png` and `ab_1.png`, both `a_1.png` and `ab_1.png` were combined with `a.png`.
+
 - October 13, 2025
     - Added Reference Consistency Mask (RCM) feature to Qwen-Image-Edit, 2509 inference script to improve pixel-level consistency of generated images. See [PR #643](https://github.com/kohya-ss/musubi-tuner/pull/643)
         - RCM addresses the issue of slight positional drift in generated images compared to the control image. For details, refer to the [Qwen-Image documentation](./docs/qwen_image.md#inpainting-and-reference-consistency-mask-rcm).

src/musubi_tuner/dataset/image_video_dataset.py

@@ -851,10 +851,28 @@ def __init__(
             logger.info(f"glob control images in {self.control_directory}")
             self.has_control = True
             self.control_paths = {}
-            for image_path in self.image_paths:
+
+            # sort image paths for matching control images properly: longer names first
+            image_paths_sorted = sorted(self.image_paths, key=lambda p: -len(os.path.basename(p)))
+
+            # glob control images first
+            all_control_image_paths = set(glob_images(self.control_directory))
+
+            for image_path in image_paths_sorted:
                 image_basename = os.path.basename(image_path)
                 image_basename_no_ext = os.path.splitext(image_basename)[0]
-                potential_paths = glob.glob(os.path.join(self.control_directory, os.path.splitext(image_basename)[0] + "*.*"))
+
+                # find matching control images
+                potential_paths = [
+                    p
+                    for p in all_control_image_paths
+                    if os.path.basename(p).startswith(image_basename_no_ext + ".")
+                    or os.path.basename(p).startswith(image_basename_no_ext + "_")
+                ]
+
+                # remove to avoid duplicate matching
+                all_control_image_paths.difference_update(potential_paths)
+
                 if potential_paths:
                     # sort by the digits (`_0000`) suffix, prefer the one without the suffix
                     def sort_key(path):