codec

type CoefficientExtractor interface {
	// Extract retrieves all DCT coefficients from a JPEG file.
	//
	// The returned coefficients include position information for per-mode analysis.
	// Coefficients are returned for all color components (Y, Cb, Cr).
	//
	// Parameters:
	//   - data: Complete JPEG file data
	//
	// Returns:
	//   - coefficients: Slice of DCT coefficients with position metadata
	//   - error: If extraction fails or data is not valid JPEG
	Extract(data []byte) ([]DCTCoefficient, error)
}

type DCTCoefficient struct {
	Row       int
	Col       int
	Component int
	Value     int16
}

type Error struct {
	Cause   error
	Code    string
	Message string
}

type ImageProcessor interface {
	// ConvertToYCbCr converts RGB pixels to YCbCr color space.
	ConvertToYCbCr(rgbPixels []byte, width, height int) (ycbcrPixels []byte, err error)

	// ConvertToRGB converts YCbCr pixels to RGB color space.
	ConvertToRGB(ycbcrPixels []byte, width, height int) (rgbPixels []byte, err error)

	// CropImage removes pixels from image edges.
	CropImage(pixels []byte, width, height, channels, cropSize int) (
		croppedPixels []byte, newWidth, newHeight int, err error,
	)

	// ApplyBlur applies a smoothing blur to reduce quantization noise.
	ApplyBlur(pixels []byte, width, height, channels int, epsilon float64) (
		blurredPixels []byte, err error,
	)
}

type JPEGCodec interface {
	// Decode decompresses JPEG data to raw pixel values.
	//
	// The returned pixels are in RGB format, row-major order:
	//   - pixels[y*width*3 + x*3 + 0] = Red
	//   - pixels[y*width*3 + x*3 + 1] = Green
	//   - pixels[y*width*3 + x*3 + 2] = Blue
	//
	// Parameters:
	//   - data: Complete JPEG file data
	//
	// Returns:
	//   - pixels: Raw RGB pixel data
	//   - width: Image width in pixels
	//   - height: Image height in pixels
	//   - error: If decoding fails or data is not valid JPEG
	Decode(data []byte) (pixels []byte, width, height int, err error)

	// Encode compresses raw pixel data to JPEG format.
	//
	// The input pixels must be in RGB format, row-major order.
	//
	// Parameters:
	//   - pixels: Raw RGB pixel data
	//   - width: Image width in pixels
	//   - height: Image height in pixels
	//   - quality: JPEG quality factor (1-100)
	//
	// Returns:
	//   - data: Complete JPEG file data
	//   - error: If encoding fails or dimensions are invalid
	Encode(pixels []byte, width, height, quality int) (data []byte, err error)

	// QualityFactor returns the detected quality factor of the last decoded image.
	//
	// This method must be called after Decode() to get meaningful results.
	// The quality factor is estimated from the quantization tables.
	//
	// Returns:
	//   - quality: Estimated quality factor (1-100), or 0 if not detected
	QualityFactor() int

	// IsBaseline returns whether the last decoded image was baseline JPEG.
	//
	// This method must be called after Decode() to get meaningful results.
	// F5 steganalysis only works on baseline JPEGs (SOF0).
	//
	// Returns:
	//   - baseline: True if baseline JPEG, false otherwise
	IsBaseline() bool

	// QuantizationTables returns the luminance and chrominance quantization
	// tables of the last decoded image. Each is a 64-entry slice in ZIGZAG
	// order (as stored in the JPEG DQT marker). Either may be nil if no image
	// has been decoded or the table is absent (e.g. chroma on a grayscale JPEG).
	//
	// Must be called after Decode(). These tables are intended to be passed to
	// EncodeWithTables so a re-compression reuses the source image's actual
	// quantization rather than a standard table scaled by an estimated scalar
	// quality (Fridrich §3.2 cover-histogram estimation).
	QuantizationTables() (luma, chroma []int)

	// EncodeWithTables compresses raw RGB pixel data to JPEG format using the
	// supplied quantization tables instead of deriving them from a scalar
	// quality factor.
	//
	// lumaTable and chromaTable are 64-entry slices in ZIGZAG order (the order
	// returned by QuantizationTables / the JPEG DQT marker). A nil table falls
	// back to the standard-scaled table at the given fallbackQuality for that
	// channel. fallbackQuality is also used for any encoder bookkeeping that
	// still needs a scalar.
	//
	// Chroma subsampling and all other encoder behavior match Encode().
	EncodeWithTables(
		pixels []byte, width, height, fallbackQuality int,
		lumaTable, chromaTable []int,
	) (data []byte, err error)
}