Dev v0.2.1#5
Merged
Merged
Conversation
utils.py — image enhancement algorithms (mode 9)
- Added classic_he_gray, tidhe_gray, rdfhe_gray, nfldice_gray, betce_gray, sfcef_gray; all support legacy_mode=True.
- Documented intentional deviations from SHINE/MATLAB in-source:
· exact_histogram 'noise' tie-strategy uses centered noise [-level, +level] instead of SHINE match.m's
one-sided rand()*0.1, avoiding systematic upward bias.
· sf_match/spec_match use soft_clip instead of MATLAB's silent uint8 hard-clip, even in legacy_mode
(hard-clip distorts the matched spectrum).
utils.py — validation
- Added sf_match_validation and spec_match_validation (adapted for fft_padding_mode).
- Added corr_rmse_per_item and mean_spectrum (de-duplicate repeated code).
utils.py — metrics
- Added ImageStats and imstats (replicate MATLAB imstats.m).
- Added compute_ambe, compute_mssim, compute_psnr, compute_bp2bpsim, compute_contrast_improvement,
compute_image_entropy.
- Added tidhe_hist_plot.
Options.py
- Added mode=9 standalone_op parameter ('dithering', 'ie_methods'). Mode 9 is no longer dithering-only:
it now groups the non-matching processing options and catalogues the image enhancement methods.
SHINIER.py
- Mode 9 CLI prompts for standalone_op selection.
Bug fixes
ImageProcessor.py — background pixel overflow in modes 7 and 8
- Frequency operations (sf_match, spec_match) produce out-of-range IFFT values for background pixels
(outside the mask, not processed by the following hist_match); with _is_moving_target=True these
accumulate across iterations. Fixed by applying soft_clip when _iter_num == iterations-1 (last outer
iteration) instead of only at _is_last_operation. soft_clip is monotonic, so it preserves the rank
ordering seen by the following hist_match on foreground pixels.
utils.py — rescale_images255 option 3
- Dataset-average min/max normalization could map outlier images outside [0, 255]; added
np.clip(..., 0, 255) after the linear rescaling.
Converter.py — legacy_mode improvements
- forward_color_treatment/backward_color_treatment with legacy_mode=True now explicitly call
rgb2gray(weighting_standard="rec601", matlab_601=True) — equivalent to rgb2ntsc_intensity — matching
the Y channel of MATLAB rgb2ntsc / NTSC-YIQ, and output the Y component.
- Renamed parameter conversion_type -> color_conversion in both methods.
- Added MATLAB_RGB2GRAY_WEIGHTS constant with the exact MATLAB Rec.601 weights.
- Improved legacy_mode docstring: clarifies when the NTSC-YIQ path is taken and its relationship to
Options(legacy_mode=True).
quantify_chroma_loss.py
- Shortened the file name and several function names.
Tests
tests/tools/utils.py
- is_already_done skips only terminal-success statuses; failed/error combos are retried, not cached green.
- prepare_images treats only the first image per buffer cell and drops the unused buffers_other (~12 -> 2 MB).
tests/validation_tests/ImageProcessor_validation_test.py
- Seed authoritative per combo (from_unit_test + proc.seed, then process()); no wall-clock reseed, so
failures reproduce. seed_iter strips volatile paths; combo_hash namespaced by option-space fingerprint.
- Unexpected Options() errors hard-fail (not "invalid"); real coverage accounting replaces the vacuous
cnt>=0 assert.
- 'final' SSIM check hard only for mode 2; composite modes 5-8 gate on final-output SSIM (hard collapse
floor + soft degraded warning). RMSE baseline now uses proc._initial_buffer.
New test files
- tests/unit_tests/Utils_test.py.
- tests/unit_tests/PrunedCoverage_test.py.
- tests/validation_tests/ImageEnhancement_validation_test.py (pixel-exact MATLAB SHA-256 hashes for
TIDHE/RDFHE/NFLDICE/BETCE; pixel-difference bound <= 1 gray level for SFCEF due to FMA rounding).
- tests/assets/image_enhancement_matlab_sha256.json.
- tests/assets/sfcef_matlab_reference/.
Documentation
documentation.md
- Expanded the RGB-to-grayscale section.
- Added "Convolution — FMA and Unit in the Last Place (ULP)".
- Updated mode 9 to document standalone_op and ie_methods.
- Added "Histogram Equalization: Exact Specification and Histogram-Derived Remapping".
- Added algorithm descriptions (sections 5-10): Classic HE, TIDHE, RDFHE, NFLDICE, BETCE, SFCEF.
- Updated the testing section: Utils_test, PrunedCoverage_test, ImageEnhancement_validation_test.
demos.md
- Updated the mode 9 example; split into 9a (standalone_op="ie_methods", with ie_methods selection)
and 9b (standalone_op="dithering").
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds image-enhancement methods, new validation utilities and metrics, several bug fixes, stronger test coverage, and updated documentation.
Image enhancement
utils.pyAdded six grayscale enhancement methods:
classic_he_graytidhe_grayrdfhe_graynfldice_graybetce_graysfcef_grayAll methods support
legacy_mode=True.Documented two intentional differences from SHINE/MATLAB:
noisetie strategy inexact_histogramuses centered noise instead of SHINE’s one-sided noise, avoiding upward bias.sf_matchandspec_matchusesoft_cliprather than MATLAB-style hard clipping, because hard clipping distorts the matched spectrum.Mode 9
Mode 9 now supports two standalone operation groups through
standalone_op:"ie_methods"for image enhancement"dithering"for ditheringThe CLI now prompts users to select the standalone operation.
Validation and metrics
Added:
sf_match_validationspec_match_validationcorr_rmse_per_itemmean_spectrumImageStatsimstatstidhe_hist_plotThe spectrum validation functions support
fft_padding_mode.Bug fixes
ImageProcessor.pyFixed background-pixel overflow in modes 7 and 8 by applying
soft_clipduring the final outer iteration. This prevents out-of-range IFFT values from accumulating while preserving foreground rank ordering before histogram matching.utils.pyAdded clipping after dataset-level min/max normalization in
rescale_images255option 3, preventing outlier images from exceeding[0, 255].Converter.pyImproved
legacy_modecompatibility:rgb2ntsc.MATLAB_RGB2GRAY_WEIGHTS.conversion_typetocolor_conversion.ImageProcessor.pyseedfrom Options was never used, always resorted to "int(datetime.now().timestamp())"Chroma-loss utilities
Shortened
quantify_chroma_loss.pyand several function names.Tests
Improved test infrastructure:
Options()errors now fail explicitly.Added:
Utils_test.pyPrunedCoverage_test.pyImageEnhancement_validation_test.pyTIDHE, RDFHE, NFLDICE, and BETCE are validated against pixel-exact MATLAB hashes. SFCEF allows a maximum difference of one gray level because of floating-point and FMA rounding.
Documentation
Updated
documentation.mdwith:Updated
demos.mdwith separate mode 9 examples for image enhancement and dithering.