Five quick-win fixes: #30, #44, #33, #60, #56

- #30: save trained YOLO model with model.save() not model.export()
- #44: open all text files (YAML/JSON/TXT, incl. .iap project) as UTF-8
  to prevent the Windows cp1252 'charmap' crash
- #33: edit the smallest containing polygon so nested annotations are
  reachable (reuses shoelace calculate_area)
- #60: sort the image list alphabetically via a signals-blocked
  model+view rebuild (not setSortingEnabled), preserving the
  all_images[i] <-> image_list.item(i) invariant
- #56: add imagecodecs dependency and catch the LZW/compressed-TIFF
  ValueError with an actionable dialog instead of crashing

Stacked on the #27/#57 branch (PR #71) because #60/#56 build on the
image-list filter work. 157 tests pass; ruff F,E9 clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: cofade

docs/05_building_block_view.md

@@ -209,7 +209,7 @@ the controller graph.
 | Controller | Responsibility |
 |------------|----------------|
 | `ProjectController` | `.iap` save/load, auto-save, backup/restore, missing-image prompts, window-title sync. Owns the `is_loading_project` autosave guard (load/save round-trip safety, v0.8.12). |
-| `ImageController` | Open / load / switch images and slices. TIFF + CZI loaders, the multi-dim `DimensionDialog`, the `[-ndim:]` axis-slice bug fix from the v0.9.0 era. Image-list annotation-status filter (`image_has_annotations`, `apply_image_filter` — upstream #27). |
+| `ImageController` | Open / load / switch images and slices. TIFF + CZI loaders (with `imagecodecs` codec-error handling — #56), the multi-dim `DimensionDialog`, the `[-ndim:]` axis-slice bug fix from the v0.9.0 era. Image-list annotation-status filter (`image_has_annotations`, `apply_image_filter` — #27) and alphabetical sort (`sort_image_list` — #60). |
 | `AnnotationController` | Annotation CRUD, list sorting, highlight, edit-mode entry/exit, `finish_polygon`, `finish_rectangle`, `replace_annotations` (eraser path). Validates writes before mutating `all_annotations`. |
 | `ClassController` | Class add / delete / rename / colour / visibility. `update_slice_list_colors`, `is_class_visible`. |
 | `SAMController` | SAM box/points tool lifecycle, debounce timer, `_sam_inference_in_flight` re-entrancy guard (ADR-013), model picker. |

docs/08_crosscutting_concepts.md

@@ -558,6 +558,37 @@ emitters follow up with `annotationsBatchSaved`
 New mutation paths must keep one of those two routes — don't add
 bespoke `apply_image_filter()` call sites.
 
+## Image List Sorting — Rebuild, Don't `setSortingEnabled`
+
+The image list is kept alphabetical (upstream issue #60,
+`ImageController.sort_image_list`). Two constraints shape the
+implementation:
+
+- `currentRowChanged` is wired to `switch_image`, so `setSortingEnabled(True)`
+  is forbidden — a live re-sort would reorder rows and fire spurious
+  image switches.
+- COCO import (and other positional lookups) assume `all_images[i]`
+  matches `image_list.item(i)`. So the model and the view are sorted
+  **together**: `all_images` is sorted, then the list is cleared and
+  repopulated from it with `blockSignals(True)` around the rebuild, and
+  the prior (or newly added) selection is restored explicitly. The #27
+  filter is re-applied at the end of the rebuild.
+
+`update_image_list` routes through `sort_image_list`; `add_images_to_list`
+calls it with the first added file selected. It is skipped per-image
+during project load (the list is rebuilt once via `update_ui`) to avoid
+an O(n²) re-sort.
+
+## TIFF Compression Codecs
+
+Reading an LZW- (or otherwise) compressed TIFF requires the optional
+`imagecodecs` package; without it `tifffile` raises `ValueError` mid-read
+(upstream issue #56). `imagecodecs` is now a hard dependency, but
+`ImageController.add_images_to_list` also catches the codec `ValueError`
+(`_is_missing_codec_error`) and shows an actionable "pip install
+imagecodecs" dialog, skipping the file instead of crashing or leaving a
+half-added entry. Non-codec `ValueError`s still propagate.
+
 ## Canvas Decoupling — Signals + CanvasContext
 
 `ImageLabel` (the canvas widget) does **not** hold a reference to

setup.py

@@ -33,6 +33,7 @@
         "numpy>=2.0.0",  # pip resolves 2.4+ on Py3.14, 2.2.x on Py3.10 (last 3.10-compatible)
         "Pillow>=10.0.0",
         "tifffile>=2023.0.0",
+        "imagecodecs>=2023.1.23",  # tifffile needs it for LZW/compressed TIFF (#56)
         "czifile>=2019.7.2",
         "opencv-python>=4.8.0",
         "pyyaml>=6.0.0",

src/digitalsreeni_image_annotator/controllers/annotation_controller.py

@@ -217,7 +217,7 @@ def load_annotations(self):
         if not file_name:
             return
 
-        with open(file_name, "r") as f:
+        with open(file_name, "r", encoding='utf-8') as f:
             self.mw.loaded_json = json.load(f)
 
         self.mw.class_list.clear()
@@ -259,9 +259,11 @@ def load_annotations(self):
 
         for img in json_images.values():
             updated_all_images.append(img)
-            self.mw.image_list.addItem(img["file_name"])
 
         self.mw.all_images = updated_all_images
+        # Rebuild the list in sorted order (issue #60). The reconciliation
+        # loop above already consumed the pre-sort row/index alignment.
+        self.mw.update_image_list()
 
         self.mw.all_annotations.clear()
         for annotation in self.mw.loaded_json["annotations"]:
@@ -538,7 +540,7 @@ def are_all_polygons_connected(polygons):
         msg_box.setText("Do you want to keep the original annotations?")
         msg_box.setIcon(QMessageBox.Icon.Question)
 
-        keep_button = msg_box.addButton("Keep", QMessageBox.ButtonRole.YesRole)
+        msg_box.addButton("Keep", QMessageBox.ButtonRole.YesRole)
         delete_button = msg_box.addButton("Delete", QMessageBox.ButtonRole.NoRole)
         cancel_button = msg_box.addButton("Cancel", QMessageBox.ButtonRole.RejectRole)
 

src/digitalsreeni_image_annotator/controllers/image_controller.py

@@ -86,11 +86,56 @@ def __init__(self, main_window):
         self.mw = main_window
 
     def update_image_list(self):
+        # Rebuild (and sort) the list, preserving the current selection
+        # without switching images.
+        self.sort_image_list()
+
+    def sort_image_list(self, select_name=None, do_switch=False):
+        """Populate image_list in alphabetical order (upstream issue #60).
+
+        Sorts the model (`all_images`) and the view together so the
+        `all_images[i]` ↔ `image_list.item(i)` positional invariant holds
+        (relied on by COCO import reconciliation). `setSortingEnabled` is
+        deliberately NOT used: `currentRowChanged` is wired to
+        `switch_image`, so a live re-sort would fire spurious image
+        switches. We rebuild with signals blocked instead, then re-select
+        explicitly.
+
+        select_name: file to select after the rebuild (defaults to the
+        previously-current item). do_switch: call switch_image once for
+        the selected item (used when adding new images).
+        """
+        current = None
+        if self.mw.image_list.currentItem() is not None:
+            current = self.mw.image_list.currentItem().text()
+
+        self.mw.all_images.sort(
+            key=lambda info: (
+                info.get("file_name", "").casefold(),
+                info.get("file_name", ""),
+            )
+        )
+
+        self.mw.image_list.blockSignals(True)
         self.mw.image_list.clear()
-        for image_info in self.mw.all_images:
-            self.mw.image_list.addItem(image_info["file_name"])
+        for info in self.mw.all_images:
+            self.mw.image_list.addItem(info["file_name"])
+        self.mw.image_list.blockSignals(False)
+
         self.apply_image_filter()
 
+        target = select_name if select_name is not None else current
+        if target is not None:
+            items = self.mw.image_list.findItems(
+                target, Qt.MatchFlag.MatchExactly
+            )
+            if items:
+                self.mw.image_list.blockSignals(True)
+                self.mw.image_list.setCurrentItem(items[0])
+                self.mw.image_list.blockSignals(False)
+                if do_switch:
+                    self.switch_image(items[0])
+
     def image_has_annotations(self, image_info):
         """True if the image (or, for multi-dim images, any of its slices)
         has at least one annotation."""
@@ -181,7 +226,7 @@ def open_images(self):
             self.add_images_to_list(file_names)
 
     def add_images_to_list(self, file_names):
-        first_added_item = None
+        first_added_name = None
         for file_name in file_names:
             base_name = os.path.basename(file_name)
             if base_name not in self.mw.image_paths:
@@ -194,7 +239,25 @@ def add_images_to_list(self, file_names):
                 }
 
                 if file_name.lower().endswith((".tif", ".tiff", ".czi")):
-                    self.load_multi_slice_image(file_name)
+                    try:
+                        self.load_multi_slice_image(file_name)
+                    except ValueError as e:
+                        # LZW/compressed TIFFs need the optional imagecodecs
+                        # package; without it tifffile raises ValueError and
+                        # the app used to crash (#56). Skip the file with an
+                        # actionable message instead of a half-added entry.
+                        if self._is_missing_codec_error(e):
+                            QMessageBox.critical(
+                                self.mw,
+                                "Cannot open TIFF",
+                                f"'{base_name}' uses a compression that requires "
+                                "the 'imagecodecs' package, which is not "
+                                "installed.\n\nInstall it with:\n"
+                                "    pip install imagecodecs\n\n"
+                                "then reopen the image.",
+                            )
+                            continue
+                        raise
                     base_name_without_ext = os.path.splitext(base_name)[0]
                     if (
                         base_name_without_ext in self.mw.image_slices
@@ -218,22 +281,34 @@ def add_images_to_list(self, file_names):
                     image_info["width"] = image.width()
 
                 self.mw.all_images.append(image_info)
-                item = QListWidgetItem(base_name)
-                self.mw.image_list.addItem(item)
-                if first_added_item is None:
-                    first_added_item = item
+                if first_added_name is None:
+                    first_added_name = base_name
 
                 self.mw.image_paths[base_name] = file_name
 
-        if first_added_item:
-            self.mw.image_list.setCurrentItem(first_added_item)
-            self.switch_image(first_added_item)
-
-        self.apply_image_filter()
+        # Rebuild the list in sorted order and select/switch to the first
+        # newly added image. Skipped during project load (the list is
+        # rebuilt once via update_ui afterwards, and load picks row 0) to
+        # avoid an O(n^2) re-sort per image.
+        if first_added_name is not None and not self.mw.is_loading_project:
+            self.sort_image_list(select_name=first_added_name, do_switch=True)
+        else:
+            self.apply_image_filter()
 
         if not self.mw.is_loading_project:
             self.mw.auto_save()
 
+    @staticmethod
+    def _is_missing_codec_error(exc):
+        """True if a tifffile read failed because the imagecodecs package
+        is unavailable for the TIFF's compression — e.g. LZW (#56).
+
+        Matches only the reliable 'imagecodecs' token: tifffile names the
+        package in every such message. A broader 'compression' match would
+        silently swallow unrelated ValueErrors behind a misleading dialog.
+        """
+        return "imagecodecs" in str(exc).lower()
+
     def update_all_images(self, new_image_info):
         for info in new_image_info:
             if not any(

src/digitalsreeni_image_annotator/controllers/project_controller.py

@@ -116,7 +116,7 @@ def open_specific_project(self, project_file):
             try:
                 self.mw.is_loading_project = True
 
-                with open(project_file, "r") as f:
+                with open(project_file, "r", encoding='utf-8') as f:
                     project_data = json.load(f)
 
                 self.mw.clear_all(show_messages=False)
@@ -490,7 +490,7 @@ def save_project(self, show_message=True):
         if dino_cfg["phrases"] or dino_cfg["thresholds"]:
             project_data["dino_config"] = dino_cfg
 
-        with open(self.mw.current_project_file, "w") as f:
+        with open(self.mw.current_project_file, "w", encoding='utf-8') as f:
             json.dump(image_utils.convert_to_serializable(project_data), f, indent=2)
 
         if show_message:

src/digitalsreeni_image_annotator/dialogs/coco_json_combiner.py

@@ -63,7 +63,7 @@ def combine_json_files(self):
 
         try:
             for file_path in self.json_files:
-                with open(file_path, 'r') as f:
+                with open(file_path, 'r', encoding='utf-8') as f:
                     data = json.load(f)
 
                 # Combine categories
@@ -98,7 +98,7 @@ def combine_json_files(self):
 
             output_file, _ = QFileDialog.getSaveFileName(self, "Save Combined JSON", "", "JSON Files (*.json)")
             if output_file:
-                with open(output_file, 'w') as f:
+                with open(output_file, 'w', encoding='utf-8') as f:
                     json.dump(combined_data, f, indent=2)
                 QMessageBox.information(self, "Success", f"Combined JSON saved to {output_file}")
 

src/digitalsreeni_image_annotator/dialogs/dataset_splitter.py

@@ -160,7 +160,7 @@ def split_images_only(self):
         QMessageBox.information(self, "Success", "Dataset split successfully!")
 
     def split_images_and_annotations(self):
-        with open(self.json_file, 'r') as f:
+        with open(self.json_file, 'r', encoding='utf-8') as f:
             coco_data = json.load(f)
 
         image_files = [img['file_name'] for img in coco_data['images']]
@@ -246,7 +246,7 @@ def save_coco_annotations(self, data, subset):
         subset_dir = os.path.join(self.output_directory, subset)
         os.makedirs(subset_dir, exist_ok=True)
         output_file = os.path.join(subset_dir, f"{subset}_annotations.json")
-        with open(output_file, 'w') as f:
+        with open(output_file, 'w', encoding='utf-8') as f:
             json.dump(data, f, indent=2)
 
     def split_yolo_format(self, coco_data, train_images, val_images, test_images):
@@ -289,7 +289,7 @@ def split_yolo_format(self, coco_data, train_images, val_images, test_images):
 
                 # Create YOLO format labels
                 label_file = os.path.join(labels_dir, os.path.splitext(image_file)[0] + ".txt")
-                with open(label_file, "w") as f:
+                with open(label_file, "w", encoding='utf-8') as f:
                     for ann in annotations:
                         # Convert COCO class id to YOLO class id
                         yolo_class = categories[ann["category_id"]]
@@ -310,7 +310,7 @@ def split_yolo_format(self, coco_data, train_images, val_images, test_images):
         }
         yaml_data.update(yaml_paths)  # Add only paths for non-empty splits
 
-        with open(os.path.join(self.output_directory, 'data.yaml'), 'w') as f:
+        with open(os.path.join(self.output_directory, 'data.yaml'), 'w', encoding='utf-8') as f:
             yaml.dump(yaml_data, f, default_flow_style=False)
 
         QMessageBox.information(self, "Success", "Dataset and YOLO annotations split successfully!")

src/digitalsreeni_image_annotator/dialogs/dicom_converter.py

@@ -3,8 +3,7 @@
 import numpy as np
 from datetime import datetime
 from PyQt6.QtWidgets import (QDialog, QVBoxLayout, QHBoxLayout, QPushButton, QFileDialog, 
-                            QLabel, QProgressDialog, QRadioButton, QButtonGroup, 
-                            QMessageBox, QApplication, QGroupBox)
+                            QLabel, QProgressDialog, QRadioButton, QMessageBox, QApplication, QGroupBox)
 from PyQt6.QtCore import Qt
 import pydicom
 from pydicom.pixel_data_handlers.util import apply_voi_lut
@@ -230,7 +229,7 @@ def convert_dicom(self):
             metadata_file = os.path.join(self.output_directory, 
                                        os.path.splitext(os.path.basename(self.input_file))[0] + 
                                        "_metadata.json")
-            with open(metadata_file, 'w') as f:
+            with open(metadata_file, 'w', encoding='utf-8') as f:
                 json.dump(series_metadata, f, indent=2)
 
             # Get physical sizes from metadata

src/digitalsreeni_image_annotator/dialogs/dino_merge_dialog.py

@@ -6,7 +6,6 @@
 
 import json
 import math
-import os
 import random
 import traceback
 from collections import defaultdict
@@ -180,7 +179,7 @@ def _run(self):
             # Load and validate
             records = []
             for path in coco_files:
-                with open(path) as f:
+                with open(path, encoding='utf-8') as f:
                     data = json.load(f)
                 if not data.get("images") or not data.get("annotations"):
                     self._log_msg(f"  [skip] {path.name}: empty.")
@@ -295,9 +294,9 @@ def _build_coco(imgs):
             train_data = _build_coco(train_imgs)
             val_data = _build_coco(val_imgs)
 
-            with open(out_path / "train.json", "w") as f:
+            with open(out_path / "train.json", "w", encoding='utf-8') as f:
                 json.dump(train_data, f, indent=2)
-            with open(out_path / "val.json", "w") as f:
+            with open(out_path / "val.json", "w", encoding='utf-8') as f:
                 json.dump(val_data, f, indent=2)
 
             self._log_msg(f"Train images: {len(train_imgs)}, annotations: {len(train_data['annotations'])}")