SHINIER

Overview

  • README

User Guide

  • Documentation
    • Table of Contents
    • Overview
      • Main Objectives
    • Package Architecture
      • Module Structure
      • Processing Flow
    • MATLAB vs Python Differences
      • 1. Rounding Operators
        • MATLAB round()
        • Python numpy.round() - IEEE 754 Standard
        • SHINIER Solution - Compatibility vs Standards
      • 2. Integer Type Conversion
        • MATLAB uint8()
        • Python numpy.astype('uint8')
        • SHINIER Solution
      • 3. Standard Deviation Calculation
        • MATLAB std2()
        • Python numpy.std() - Statistical Best Practice
        • SHINIER Solution - Scientific Flexibility
      • 4. RGB to Grayscale Conversion
        • MATLAB rgb2gray() / NTSC-YIQ Intensity
        • SHINIER rgb2gray() - Modern Standards Support
      • 5. Convolution — FMA and Unit in the Last Place (ULP)
    • Detailed Processing Modes
      • Pixel-based matching (Modes 1–2)
        • Mode 1: Luminance Matching Only
        • Mode 2: Histogram Matching Only
      • Spatial-frequency-based matching (Modes 3–4)
        • Mode 3: Spatial Frequency Matching Only
        • Mode 4: Spectrum Matching Only
      • Composite modes (Modes 5–8)
        • Mode 5: Histogram + Spatial Frequency
        • Mode 6: Histogram + Spectrum
        • Mode 7: Spatial Frequency + Histogram
        • Mode 8: Spectrum + Histogram (Recommended)
      • Standalone transforms (Mode 9)
        • Mode 9: Standalone per-image transform
        • Histogram equalization: exact specification and histogram-derived remapping
    • Border Artifacts and FFT Padding
    • Main Classes
      • Converter
      • GamutControl (Color gamut management)
      • Options
      • ImageDataset
      • ImageProcessor
    • Visualization Functions
    • StimulusMasker
    • Implemented Algorithms
      • 1. Exact Histogram Specification
      • 2. SSIM Optimization for Histogram
      • 3. Floyd-Steinberg Dithering
      • 4. Noisy Bit Dithering
      • 5. Classic Global Histogram Equalization (Classic HE)
      • 6. Tripartite Image Decomposition-Based Histogram Equalization (TIDHE)
      • 7. Recursive Dualistic Fuzzy Histogram Equalization (RDFHE)
      • 8. Nonlinear Fuzzification–Linear Defuzzification-Based ICE (NFLDICE)
      • 9. Bi-Entropy Curve Equalization (BETCE)
      • 10. Sakaguchi-Type Function-Based Cost-Effective Filtering (SFCEF)
    • Memory Management and Performance
      • Memory Conservation Mode (conserve_memory=True)
    • Testing and Validation
      • Unit Tests
      • Validation Tests
      • MATLAB SHINE Comparison
    • Troubleshooting and Optimization
      • Common Issues
    • Additional Resources
  • Demos / How-to-use
    • Case 1 – Using the CLI
      • I. Calling the CLI
        • 1) Recommended: From terminal
        • 2) From Python (Not recommended)
      • II. CLI Use Cases
        • 1) Press Enter
        • 2) Press q
        • 3) Write custom input
      • III. CLI Profiles
    • Case 2 – Customizing Options
      • 1) Define the Options
        • Mode 1 – lum_match
        • Mode 2 – hist_match
        • Mode 3 – sf_match
        • Mode 4 – spec_match
        • Mode 5 – hist_match → sf_match
        • Mode 6 – hist_match → spec_match
        • Mode 7 – sf_match → hist_match
        • Mode 8 – spec_match → hist_match
        • Mode 9 – Standalone Per-Image Transform
        • Example 10 – Mode 2 + extra parameters
        • Example 11 – Preserve colors with constrain_image_chrominance
      • 2) Create the Dataset
        • (i) Recommended: from folders
        • (ii) Manual: from pre-loaded images (not recommended)
      • 3) Image Processing
        • Optional: display a processing overview
    • Thank you

Contributors Guide

  • Contributing to SHINIER
    • Table of Contents
    • Code of Conduct
    • Development Setup
    • Coding Standards
      • Git rules
      • To do before a PR
      • Language & typing
      • Docstrings
      • Read the Docs
      • Pydantic models
      • Exceptions
      • Unit-Tests and Validation Tests
        • Test README
  • Testing Guide
    • Pytest Configuration
    • Markers
    • Multi-Core Execution
    • Validation Tests — Coverage Modes
      • Environment variables
    • Running Shards Locally (GNU parallel)
    • Running on a Compute Cluster (SLURM/sbatch)
    • Debugging Tests
      • Drop into debugger on failure
      • Step interactively inside test
      • Show full traceback
    • Hard vs Soft Failures in Validation Tests
      • Hard failures (call _dump_and_fail)
      • Soft failures (collected in combo_warnings, dumped but don’t fail)
    • Resume From a Given Combo
    • Image Enhancement MATLAB Reference Hashes
    • Replay a Dumped Failure
    • Tips
    • Example Workflow
    • MATLAB SHINE Comparison

Project

  • Project Links
  • SHINIER PDF
  • License

API Reference

  • API Reference
    • Core Classes
      • Options
      • ImageDataset
        • ImageDataset.close()
        • ImageDataset.initialize_dataset()
        • ImageDataset.post_init()
        • ImageDataset.print_log()
        • ImageDataset.save_images()
      • ImageProcessor
        • ImageProcessor.dithering()
        • ImageProcessor.float01_to_float255()
        • ImageProcessor.float255_to_float01()
        • ImageProcessor.get_results()
        • ImageProcessor.hist_match()
        • ImageProcessor.ie_methods()
        • ImageProcessor.lum_match()
        • ImageProcessor.print_log_results()
        • ImageProcessor.process()
        • ImageProcessor.sf_match()
        • ImageProcessor.spec_match()
        • ImageProcessor.uint8_to_float255()
    • Color Processing
      • ColorConverter
        • ColorConverter.apply_standard_config()
        • ColorConverter.lab_to_sRGB()
        • ColorConverter.lab_to_xyz()
        • ColorConverter.linRGB_to_sRGB()
        • ColorConverter.linRGB_to_xyz()
        • ColorConverter.sRGB_to_lab()
        • ColorConverter.sRGB_to_linRGB()
        • ColorConverter.sRGB_to_xyY()
        • ColorConverter.sRGB_to_xyz()
        • ColorConverter.xyY_to_sRGB()
        • ColorConverter.xyY_to_xyz()
        • ColorConverter.xyz_to_lab()
        • ColorConverter.xyz_to_linRGB()
        • ColorConverter.xyz_to_sRGB()
        • ColorConverter.xyz_to_xyY()
      • ColorTreatment
        • ColorTreatment.backward_color_treatment()
        • ColorTreatment.forward_color_treatment()
      • GamutControl
        • GamutControl.apply_dataset()
        • GamutControl.apply_image()
        • GamutControl.apply_low_Y_desaturation()
        • GamutControl.get_max_luminance_map()
      • rgb2gray()
      • rgb2ntsc_intensity()
      • gray2rgb()
    • Utility Functions
      • Plotting
        • hist_plot()
        • imhist_plot()
        • imshow()
        • sf_plot()
        • spectrum_plot()
        • im_power_spectrum_plot()
        • tidhe_hist_plot()
        • show_processing_overview()
      • Utility Classes
        • Bcolors
        • DiffusionMaps
        • StepSizeController
        • ImageStats
      • StimulusMasker
        • StimulusMasker
      • MatlabOperators
        • MatlabOperators
      • Functions
        • print_shinier_header()
        • pydantic_field_choices()
        • pydantic_model_choices()
        • sf_profile()
        • freq_axis()
        • get_radius_grid()
        • rotational_avg()
        • stretch()
        • convolve_1d()
        • convolve_2d()
        • has_duplicates()
        • n_unique()
        • strict_ordering()
        • exact_histogram()
        • apply_histogram_mapping()
        • floyd_steinberg_dithering()
        • error_diffusion_dither()
        • soft_clip()
        • noisy_bit_dithering()
        • uint_to_float01()
        • float01_to_uint()
        • pol2cart()
        • cart2pol()
        • separate()
        • image_spectrum()
        • gaussian_kernel()
        • center_surround_kernel()
        • laplacian_kernel()
        • tie_breaking_noise_level()
        • print_log()
        • strip_ansi()
        • colorize()
        • console_log()
        • beta_bounds_from_ssim()
        • ssim_sens()
        • hist_match_validation()
        • sf_match_validation()
        • spec_match_validation()
        • compute_rmse()
        • normalized_rmse()
        • get_images_spectra()
        • rescale_image()
        • load_images_from_folder()
        • load_np_array()
        • rescale_images255()
        • uint8_plus()
        • apply_median_blur()
        • hist2list()
        • im3D()
        • imhist()
        • classic_he_gray()
        • tidhe_gray()
        • rdfhe_gray()
        • nfldice_gray()
        • betce_gray()
        • sfcef_gray()
      • Contrast Enhancement Metrics
        • compute_ambe()
        • compute_contrast_improvement()
        • compute_image_entropy()
        • compute_mssim()
        • compute_psnr()
        • compute_bp2bpsim()
      • Histogram And Image Statistics
        • rounded_target_hist()
        • compute_tvd_hist()
        • avg_hist()
        • imstats()
    • CLI
      • prompt()
      • options_display()
      • get_image_list()
      • main()
    • Base Helpers
      • image_list_validator()
      • InformativeBaseModel
        • InformativeBaseModel.model_post_init()
        • InformativeBaseModel.post_init()
    • Others
      • Chroma Loss Metrics
        • ChromaMetrics
        • AggregateMetric
        • AggregateRow
        • ChromaInfoRetention
        • ChromaInfoLossResult
        • chroma_metrics_for_image()
        • aggregate_chroma_metrics()
        • build_chroma_loss_report()
        • chroma_info_loss_bpp()
        • mean_chroma_loss_pct_lab()
        • lab_chroma_retention()
      • ImageListIO
        • ImageListIO
SHINIER
  • Search

© Copyright 2026, Nicolas Dupuis-Roy and Mathias Salvas-Hebert.

Built with Sphinx using a theme provided by Read the Docs.