Documentation
¶
Overview ¶
Package calibration implements double compression detection and multi-quality-factor calibration for JPEG steganalysis.
JPEG images that have been compressed multiple times exhibit characteristic histogram artifacts that affect beta estimation accuracy. This package detects double compression and adjusts the beta estimation by testing multiple quality factors to find the best fit.
The calibration process (from Fridrich et al., Section 4):
- For each test quality factor Q_i: a. Estimate cover histogram with Q_i calibration b. Calculate beta_i using least-squares c. Calculate L2 distance between stego and expected histograms
- Select the quality factor that minimizes L2 distance
- Return the calibrated beta for that quality factor
The calibration package is self-contained and does NOT import the root steganalysis package. Instead, it defines its own local types (DCTHistogram, BetaEstimationResult, CalibrationResult, etc.) and local interfaces for codec and estimator dependencies. Concrete implementations are injected at construction time from the root facade.
The root steganalysis package provides wrapper types that convert between root types and calibration-local types, following the same pattern used for the codec and estimator packages.
Reference: Fridrich, J., Goljan, M., & Hogea, D. (2002). "Steganalysis of JPEG Images: Breaking the F5 Algorithm." 5th Information Hiding Workshop, LNCS 2578, 310-323. §4 specifies the double-compression calibration implemented here. See docs/Breaking-F5.pdf.
Index ¶
Constants ¶
const ( // MinQualityFactor is the minimum JPEG quality factor (standard range). MinQualityFactor = 1 // MaxQualityFactor is the maximum JPEG quality factor (standard range). MaxQualityFactor = 100 // DefaultCropPixels is the number of pixels to crop from each edge. DefaultCropPixels = 4 // DefaultBlurEpsilon is the blur strength for the 3x3 low-pass filter. DefaultBlurEpsilon = 0.01 // DoubleCompressionThreshold is the quality-factor gap (between the recovered // best primary quality and the stego quality) that flags double compression. // Lowered from 5 to 3 after a confirmed double-compressed F5 stego whose best // primary quality differed by 4 was missed; a saturated calibrated β is now // gated separately downstream so the lower threshold cannot cause a false // detection. DoubleCompressionThreshold = 3 // CoeffRangeMin is the minimum DCT coefficient value analyzed in histograms. CoeffRangeMin = -5 // CoeffRangeMax is the maximum DCT coefficient value analyzed in histograms. CoeffRangeMax = 5 // NumLowFrequencyModes is the number of DCT frequency modes used in analysis. NumLowFrequencyModes = 3 // FrequencyBandMode12 is the frequency band index for the Fridrich paper's // mode (1,2): first horizontal AC. Paper uses 1-indexed (k,l) where // (1,1)=DC, so 0-indexed array position is (0,1) and band = 0*8+1 = 1. FrequencyBandMode12 = 1 // FrequencyBandMode21 is the frequency band index for the Fridrich paper's // mode (2,1): first vertical AC. 0-indexed (1,0); band = 1*8+0 = 8. FrequencyBandMode21 = 8 // FrequencyBandMode22 is the frequency band index for the Fridrich paper's // mode (2,2): first diagonal AC. 0-indexed (1,1); band = 1*8+1 = 9. FrequencyBandMode22 = 9 )
const ( // ErrCodeBetaOutOfRange is the error code returned when a beta value falls // outside the valid [0, 1] range during L2 distance calculation. ErrCodeBetaOutOfRange = "beta_out_of_range" // ErrCodeTestQualityRange is the error code returned when the test quality // factor is outside the valid [1, 100] range in the calibration pipeline. ErrCodeTestQualityRange = "test_quality_out_of_range" // ErrCodeFinalQualityRange is the error code returned when the final // quality factor is outside the valid [1, 100] range in the calibration // pipeline. ErrCodeFinalQualityRange = "final_quality_out_of_range" // ErrCodeStegoQualityRange is the error code returned when the stego // quality factor is outside the valid [1, 100] range in multi-QF // calibration. ErrCodeStegoQualityRange = "stego_quality_out_of_range" // ErrCodeNoQualityFactors is the error code returned when no quality // factors are provided for multi-QF calibration. ErrCodeNoQualityFactors = "no_quality_factors" // ErrCodeEmptyHistograms is the error code returned when histogram input // contains no data for calibration. ErrCodeEmptyHistograms = "empty_histograms" // ErrCodeDecodeStegoImage is the error code returned when the stego image // cannot be decoded during the calibration pipeline. ErrCodeDecodeStegoImage = "decode_stego_image" // ErrCodeConvertToYCbCr is the error code returned when RGB to YCbCr // color space conversion fails during the calibration pipeline. ErrCodeConvertToYCbCr = "convert_to_ycbcr" // ErrCodeCropImage is the error code returned when image cropping fails // during the calibration pipeline. ErrCodeCropImage = "crop_image" // ErrCodeApplyBlur is the error code returned when blur application fails // during the calibration pipeline. ErrCodeApplyBlur = "apply_blur" // ErrCodeConvertToRGB is the error code returned when YCbCr to RGB // color space conversion fails during the calibration pipeline. ErrCodeConvertToRGB = "convert_to_rgb" // ErrCodeIntermediateCompress is the error code returned when intermediate // JPEG compression fails during the double compression calibration step. ErrCodeIntermediateCompress = "intermediate_compress" // ErrCodeIntermediateDecode is the error code returned when decoding the // intermediate JPEG fails during the double compression calibration step. ErrCodeIntermediateDecode = "intermediate_decode" // ErrCodeRecompress is the error code returned when final JPEG // recompression fails during the calibration pipeline. ErrCodeRecompress = "recompress" // ErrCodeExtractCoverCoeffs is the error code returned when DCT // coefficient extraction from the recompressed image fails during the // calibration pipeline. ErrCodeExtractCoverCoeffs = "extract_cover_coefficients" )
Variables ¶
This section is empty.
Functions ¶
func GetTranslator ¶
func GetTranslator() translator
GetTranslator returns the current translator, or nil if not set.
func SetTranslator ¶
func SetTranslator(t translator)
SetTranslator sets the translator for this package. Pass nil to disable translations and use default English messages. The root steganalysis package calls this to propagate its translator.
Types ¶
type BetaEstimationResult ¶
type BetaEstimationResult struct {
PerModeBetas map[string]float64
Beta float64
Confidence float64
MinBeta float64
BetaCV float64
IsClean bool
}
BetaEstimationResult contains the results of beta (modification rate) estimation, including per-mode breakdown and variance statistics. This is a calibration-local copy of the root type to avoid circular imports.
type DCTCoefficient ¶
DCTCoefficient represents a single DCT coefficient with its position information in the 8x8 DCT block. This is a calibration-local copy of the root steganalysis.DCTCoefficient type to avoid circular imports.
type DCTHistogram ¶
DCTHistogram represents a histogram of DCT coefficient values for a specific frequency band and color component. This is a calibration-local copy of the root steganalysis.DCTHistogram type to avoid circular imports.
type Error ¶
Error represents an error from the calibration package. It carries a code string for programmatic handling and a human-readable message.
type HistogramCalibrator ¶
type HistogramCalibrator interface {
// CalculateL2Distance computes the L2 distance between observed stego histogram
// and expected histogram based on cover estimate and modification rate.
CalculateL2Distance(stegoHist, coverHist DCTHistogram, beta float64) (float64, error)
// EstimateHistogramWithQF estimates cover histogram using a specific quality factor.
EstimateHistogramWithQF(stegoImage []byte, testQuality, finalQuality int) ([]DCTHistogram, error)
// CalibrateWithMultipleQF tests multiple quality factors to find the best beta estimate.
CalibrateWithMultipleQF(
stegoImage []byte,
stegoQuality int,
stegoHistograms []DCTHistogram,
qualityFactors []int,
) (*Result, error)
}
HistogramCalibrator implements double compression detection and calibration.
JPEG images that have been compressed multiple times exhibit characteristic histogram artifacts. This interface detects double compression and adjusts the beta estimation accordingly by testing multiple quality factors.
Implementations must be safe for concurrent use.
func NewHistogramCalibrator ¶
func NewHistogramCalibrator( histEst histogramEstimator, betaEst betaEstimator, codec jpegCodec, imgProc imageProcessor, coeffExt coefficientExtractor, ) HistogramCalibrator
NewHistogramCalibrator creates a new histogram calibrator.
Parameters:
- histEst: Histogram estimator for cover histogram estimation
- betaEst: Beta estimator for modification rate calculation
- codec: JPEG encoder/decoder
- imgProc: Image processing operations
- coeffExt: DCT coefficient extractor
Returns:
- HistogramCalibrator: A new histogram calibrator instance
type Result ¶
type Result struct {
QualityDistances map[int]float64
BestQuality int
CalibratedBeta float64
UncalibratedBeta float64
Confidence float64
IsDoubleCompressed bool
}
Result contains the results of multi-quality-factor calibration, including the best quality factor, calibrated beta, and double compression detection. This is a calibration-local copy of the root type to avoid circular imports.