Repository navigation
v0.6.0 Release Notes
The deep-learning backend has moved from TensorFlow/Keras to PyTorch. The U-Net, its training code, and the CNN feature extractors used for grain clustering are now implemented with torch and torchvision; SAM 2.1 already used PyTorch. Installation no longer requires TensorFlow or Keras, and a single framework serves all models. Segmentation results are unchanged: the shipped PyTorch U-Net reproduces the Keras model's predictions to within 1e-5.
Breaking Changes
- The U-Net model file is now a PyTorch checkpoint. The shipped model is
models/seg_model_smooth_labels.pt(9 MB, replacing the 26 MB.kerasfile) and is loaded withseg.load_unet(path)instead ofkeras.saving.load_model(path). The notebooks have been updated accordingly.seg.Unet()returns the PyTorchUNetmodule. - Custom or fine-tuned Keras models must be converted once, in an environment where Keras and TensorFlow are still installed:
seg.convert_keras_model("my_model.keras", "my_model.pt"). The converter checks that the two models agree before writing the file. Models from any previous version convert, including v0.3.0-era models with the softmax built in. Passing a Keras model object to the segmentation functions still works for now but emits aFutureWarning; this fallback will be removed in a later release. - The training API is built on PyTorch and lives in the new
trainingsubmodule (still re-exported at the package level):create_train_val_test_datareturns PyTorchDataLoaders (withbatch_sizeandnum_workersarguments) instead oftf.datadatasets, with the same train/validation/test split;create_and_train_modelacceptslearning_rateanddevicearguments and a.pt(or, with Keras installed,.keras) starting model;weighted_crossentropytakes logits of shape(N, 3, H, W)and targets as class indices(N, H, W)or one-hot(N, 3, H, W), with unchanged class weights and label smoothing;patchify_training_datais implemented with numpy and returns the image and label directories;evaluate_modelreturns a dictionary withloss,accuracy,mean_iou, andper_class_iou. Trained models are saved withseg.save_unet(model, "model.pt"). grain_utils.extract_vgg16_featuresuses torchvision's ImageNet models (VGG16, ResNet50, InceptionV3) with the same preprocessing as before. Features are not numerically identical to the Keras ones because the pretrained weights differ, so previously computed feature vectors and clusterings are not directly comparable to new ones. Thelayer_nameargument keeps the Keras names (fc1,fc2,flatten,avg_pool, ...). The weights are downloaded by torchvision on first use.tensorflowandkerasare no longer dependencies;torchvisionis a new one.load_and_preprocesswas removed (its work is done byGrainPatchDataset).- Environment files are split by hardware instead of operating system:
environment.yml(Apple Silicon via MPS, or CPU) andenvironment_cuda.yml(NVIDIA GPUs via the conda-forgepytorch-gpupackage).environment_macos.ymlis removed.
New Features
UNetmodule,load_unet,save_unet,predict_batch,get_device(CUDA, MPS or CPU auto-detection), andconvert_keras_modelin the newunetsubmodule.train_model,plot_training_history,GrainPatchDataset, andaugment_pairin the newtrainingsubmodule.predict_imageaccepts abatch_sizeargument; tiles are batched through the model instead of being predicted one by one, and the result is returned asfloat32probabilities.sam_segmentationraises an informativeValueErrorwhen called with an empty prompt list, andpredict_large_imageemits a warning when no grains are detected. Previously a failed U-Net prediction could surface as a cryptic downstream error such as "attempt to get argmax of an empty sequence" (#10).
Bug Fixes
GrainPlotandplot_image_w_colorful_grainswork with matplotlib 3.11, wherematplotlib.cm.get_cmapwas removed.- Region properties are requested under their current scikit-image names (
axis_major_length,intensity_mean, ...), which silences the deprecation warnings of scikit-image 0.26. Grain summary columns keep their existing names (major_axis_length,mean_intensity-0, ...). - On macOS, importing the package no longer risks the duplicate OpenMP runtime abort (
OMP: Error #15) caused by loading TensorFlow and PyTorch in the same process.
Improvements
- PyTorch is installed from conda-forge in the environment files so that it shares the environment's OpenMP runtime with numpy/scipy.
interactions.load_imageandseg.load_imguse Pillow instead ofkeras.utils.load_img;interactions.save_maskwrites the same 8-bit grayscale PNG as before.- U-Net inference is substantially faster on Apple Silicon: a 256x256 tile takes about 4 ms on the MPS backend, compared with about 33 ms with TensorFlow Metal.
- CI tests on Python 3.10 and 3.12 with CPU-only PyTorch wheels; the documentation build mocks torch, torchvision and sam2.
- Added tests for the PyTorch U-Net, the Keras conversion, and the training pipeline (124 tests total, up from 80).
Deprecations
- Passing a Keras model object to
predict_image,predict_large_imageand the other segmentation functions still works but emits aFutureWarning. Convert the model withseg.convert_keras_modeland load the resulting.ptfile withseg.load_unet.
Full Changelog: v0.5.0...v0.6.0